clintjedwards/dropshot

expose REST APIs from a Rust program

Dropshot

Table of Contents

• A fork in the road
• Regularly scheduled programming
• Contributing
• Examples

A fork in the road

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).

  • Oxide discussion on route overlapping here.

  • 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 at https://myapp.com/api. Due to the overlapping restriction the frontend previously had to be at something like https://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/bar and /{slug}/bar/lol, A request intended for path /foo/bar/lol will 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 DEBUG log 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.

Regularly scheduled programming

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 doc

Contributing

You 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 the style checks.) You can run it with cargo clippy --all-targets — --deny warnings --allow clippy::style. CI will run clippy as well.

For maintainers (e.g., publishing new releases and managing dependabot), see MAINTAINERS.adoc.

Examples

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.