dropshot

Version 0.9.0 introduced significant changes to how RequestContext and Extractors are handled to improve type safety and performance.

1. Remove Arc from RequestContext

RequestContext is no longer wrapped in an Arc. Endpoint functions and extractors now accept RequestContext<T> directly. Action: Change the first argument of every endpoint function from Arc<RequestContext<T>> to RequestContext<T>.

2. Split Extractors into Shared and Exclusive

The Extractor trait was split into SharedExtractor and ExclusiveExtractor to prevent runtime errors when multiple extractors attempt to access the request body.

• SharedExtractor: For extractors that only need to read headers, the URL, or the method (does not consume the body).
• ExclusiveExtractor: For extractors that need to read the request body (e.g., TypedBody, UntypedBody, WebsocketConnection, or RawRequest).

Rules for Exclusive Extractors:

• An endpoint can have at most one ExclusiveExtractor.
• The ExclusiveExtractor must be the last argument in the endpoint function signature.

3. Accessing the Raw Request

To access the raw hyper::Request, use the RawRequest extractor instead of accessing rqctx.request (which was previously behind a Mutex). Action: Add raw_request: RawRequest as the last argument to your endpoint, then use let request = raw_request.into_inner();.

The HttpServer implementation has been split into two distinct types to better separate server configuration from a running server instance:

1. HttpServerStarter: Used to construct and configure the server. Use HttpServerStarter::start() to begin execution.
2. HttpServer: Represents the active, running server.

Key changes in behavior:

• Starting the server: Instead of calling .run() on an HttpServer object, you now call .start() on an HttpServerStarter object, which returns an HttpServer.
• Awaiting shutdown: In previous versions, HttpServer returned a tokio::JoinHandle and required wait_for_shutdown. In the new version, HttpServer implements Future and can be directly .await-ed to wait for the server to complete.

// Old Version:
let mut server = HttpServer::new( /* Arguments are the same between versions */ )
  .map_err(|error| format!("failed to start server: {}", error))?;

let server_task = server.run();
server.wait_for_shutdown(server_task).await;

// New Version
let server = HttpServerStarter::new( /* Arguments are the same between versions */ )
  .map_err(|error| format!("failed to start server: {}", error))?
  .start();

server.await;

The ServerBuilder is now the primary way to construct a Dropshot server, replacing HttpServerStarter. The builder provides structured errors and is the only way to add new construction-time options (like API versioning) in the future.

Migration Patterns:

Standard (Non-TLS):

// Old
HttpServerStarter::new(&config, api, private, &log).map_err(...)? .start()

// New
ServerBuilder::new(api, private, log).config(config).start().map_err(...)?

With TLS:

// Old
HttpServerStarter::new_with_tls(&config, api, private, &log, tls).map_err(...)? .start()

// New
ServerBuilder::new(api, private, log).config(config).tls(tls).start().map_err(...)?

Intermediate Starter: If you need to hold a starter object before calling .start(), use .build_starter():

let starter = ServerBuilder::new(api, private, log).config(config).build_starter().map_err(...)?;
// ...
starter.start();

Dropshot consists of two packages, dropshot and dropshot_endpoint, which are always released together with the same version number. A release involves creating a git tag with the version number and publishing both packages to crates.io.

Release Workflow

1. Prepare Changelog: Ensure CHANGELOG.adoc is up to date. Breaking changes should include concise summaries of how users are affected and how to upgrade safely.
2. Verify Working Directory:
   • Ensure you are on the main branch and synced with upstream (git pull).
   • Ensure git status shows no uncommitted files.
   • Run git clean -nxd to ensure no stale build artifacts are present.
   • Verify that CI has passed for your current commit on GitHub.
3. Identify Release Metadata:
   • Find the PREV_RELEASE_TAG (the tag used for the most recent release).
   • Determine the RELEASE_KIND (e.g., patch, minor, or major) or specify a NEW_VERSION.
4. Execute Release:
   • Install/update cargo-release.
   • Run the cargo release command.
5. Finalize:
   • Push the resulting commit and tags to the remote repository.

Note: You may need to temporarily allow administrators to override branch protection to push the release commit and tags.

# Install cargo-release
cargo install cargo-release

# Execute the release
$ cargo release --prev-tag-name=PREV_RELEASE_TAG -vv --execute RELEASE_KIND|NEW_VERSION

# Push changes
$ git push
$ git push --tags