This is a fork of Oxide Computer’s Dropshot crate.
Oxide’s crate is awesome and probably the best rust crate for managing a REST API with automatic OpenAPI generation to date.
This fork is because I wanted slightly different design decisions than the crew at Oxide went with. The main differences I added are:
-
Allowed routes to overlap, with the more specific route winning over less specific route(those with path vars).
-
This is similar to Go’s new routing enhancements. (And it intuitively makes sense).
-
The motivation is because I usually keep things in a single binary and it just looks better for my frontend to be accessed at
https://myapp.com/and my api to be accessed athttps://myapp.com/api. Due to the overlapping restriction the frontend previously had to be at something likehttps://myapp.com/-/. Some say this is bad URL design but the tribe has spoken. -
There are two drawbacks to this approach:
-
If you make overlapping routes mistakenly, you might be routed to a handler that you did not expect. The only way you find this out is through thorough testing.
-
Currently because of how specificity matching works we don’t do backmatching. That means that if we have two routes registered:
/foo/barand/{slug}/bar/lol, A request intended for path/foo/bar/lolwill fail with a 404.
-
-
-
Moved the slog logger to use tracing instead.
-
All my crates use tracing and I’ve been having a really good time with the tracing ethos and implementation.
-
It’s also used by a lot of core rust crates, seems to be pretty well supported, and has good async support.
-
First I attempted to create a slog drain that converted between the two but the code felt like a hack and didn’t map key/value pairs very well.
-
Software philosophically I don’t think a lib focused on REST API ergonomics should be handling log output or configuration, so I removed some of those pieces.
-
I also lowered some of the logging levels. Typically I run my dev terminal at
DEBUGlog level and like it so that there is more information than I would run in production but not a deluge of it. The logging levels previously were all mostly at the debug level making actual dev signal hard to get.
-
-
Implemented middleware
-
I really, really support dropshot’s decision to try to eliminate the need for out-of-band middleware. I too have come to projects and been very confused while debugging because there are 14 nested middleware functions that made the execution of the handler hard to track.
-
But while building with dropshot I found myself constantly annoyed by the design decisions I was making while attempting to avoid middleware.
-
Some of them were really good, like making the auth function the first line of every handler. This allowed me to actually quickly grok what auth settings a handler had and that made it easier to grok what the function was allowed to do. I also love keeping the request context passed to each handler lean.
-
But some of them were not so great, like the ability to do handler logging or anything that required me to wrap the handler after it has run to grab response details.
-
After fighting with for a while I determined it was better to have the evil of middleware than wrapping my handler’s code and then passing it to some other function for every single handler I wanted to write.
-
I think the middleware decision is another decision that is probably a human problem that can be addressed with appropriate static analysis, debug tooling, and policing.
-
-
Various other small quality of life changes
-
Swapped UUIDv4 to UUIDv7 for request_id so they are sortable in order of creation.
-
Since the changes above are largely non-backward compatible changes, I created this fork instead of trying to get these merged upstream.
Dropshot is a general-purpose crate for exposing REST APIs from a Rust program. For more, see the online Dropshot documentation. You can build the documentation yourself with:
$ cargo +nightly docYou can build and run the whole test suite with cargo test. The test
suite runs cleanly and should remain clean.
You can format the code using cargo fmt. CI checks that code is correctly formatted.
Clippy is used to check for common code issues. (We disable most style checks; see the [workspace.lints.clippy] section in Cargo.toml for the full configuration.) You can run it with cargo clippy --all-targets — --deny warnings. CI will run clippy as well.
For maintainers (e.g., publishing new releases and managing dependabot), see MAINTAINERS.adoc.
Dropshot servers use a TOML configuration file. Supported config properties include:
| Name | Example | Required? | Description |
|---|---|---|---|
|
|
No |
Specifies that the server should bind to the given IP address and TCP port. In general, servers can bind to more than one IP address and port, but this is not (yet?) supported. Defaults to "127.0.0.1:0". |
|
|
No |
Specifies the maximum number of bytes allowed in a request body. Larger requests will receive a 400 error. Defaults to 1024. Can be overridden per-endpoint via the |
|
|
No |
Specifies if and how TLS certificate and key information is provided. Valid values include "AsFile" and "AsBytes". |
|
|
Only if |
Specifies the path to a PEM file containing a certificate chain for the server to identify itself with. The first certificate is the end-entity certificate, and the remaining are intermediate certificates on the way to a trusted CA. If specified, the server will only listen for TLS connections. |
|
|
Only if |
Specifies the path to a PEM-encoded PKCS #8 file containing the private key the server will use. If specified, the server will only listen for TLS connections. |
|
|
Only if |
Identical to |
|
|
Only if |
Identical to |
Dropshot provides a small wrapper to configure a slog-based Logger. You can use this without using the rest of Dropshot. Logging config properties include:
| Name | Example | Required? | Description |
|---|---|---|---|
|
|
Yes |
Controls where server logging will go. Valid modes are |
|
|
Yes |
Specifies what severity of log messages should be included in the log. Valid
values include |
|
|
Only if |
If |
|
|
Only if |
If |
In designing Dropshot, we’ve tried to avoid a few problems we found with frameworks we used in the past. Many (most?) web frameworks, whether in Rust or another language, let you specify a chain of handlers for each route. You can usually specify some handlers that run before or after every request, regardless of the route. We found that after years of evolving a complex API server using this approach, it can get quite hard to follow the control flow for a particular request and to understand the implicit dependencies between different handlers within the chain. This made it time-consuming and error-prone to work on these API servers. (For more details, see the discussion in issue 58.)
With Dropshot, we wanted to try something different: if the primary purpose of these handlers is to share code between handlers, what if we rely instead on existing mechanisms — i.e., function calls. The big risk is that it’s easy for someone to accidentally forget some important function call, like the one that authenticates or authorizes a user. We haven’t gotten far enough in a complex implementation to need this yet, but the plan is to create a pattern of utility functions that return typed values. For example, where in Node.js you might add an early authentication handler that fills in request.auth, with Dropshot you’d have an authentication function that returns an AuthzContext struct. Then anything that needs authentication consumes the AuthzContext as a function argument. As an author of a handler, you know if you’ve got an AuthzContext available and, if not, how to get one (call the utility function). This composes, too: you can have an authorization function that returns an AuthnContext, and the utility function that returns one can consume the AuthzContext. Then anything that requires authorization can consume just the AuthnContext, and you know it’s been authenticated and authorized (possibly with details in that structure).
It’s early, and we may find we need richer facilities in the framework. But we’re hopeful this approach will make it faster and smoother to iterate on complex API servers. If you pick up Dropshot and try this out, let us know how it goes!
To run the examples in dropshot/examples, clone the repository and run cargo run --example [example_name], e.g. cargo run --example basic. (Do not include the file extension.)
Since we’ve moved to tracing, you can turn on logging for each test by uncommenting the tracing_subscriber implementation inside each example.