refactor: Allow overlapping routes

We now allow overlapping routes based on specificity

** This is similar to https://go.dev/blog/routing-enhancements)[Go's new routing enhancements]. (And it
intuitively makes sense).
** https://github.com/oxidecomputer/dropshot/issues/199[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.

Author: clintjedwards

README.adoc

@@ -4,38 +4,46 @@
 
 = Dropshot
 
+== A fork in the road
+
 This is a fork of https://github.com/oxidecomputer/dropshot[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 routes(those with path vars). (And
-when both routes are specific then we simply choose the one that was registered first.)
-** Oxide discussion here: https://github.com/oxidecomputer/dropshot.
-** My motivation is because I love keeping everything in a single binary and it just looks better for my frontend
+* Allowed routes to overlap, with the more specific route winning over less specific route(those with path vars).
+** This is similar to https://go.dev/blog/routing-enhancements)[Go's new routing enhancements]. (And it
+intuitively makes sense).
+** https://github.com/oxidecomputer/dropshot/issues/199[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/-/`.
-** The drawback is without proper testing you can have overlapping routes that don't follow the pattern of access
-you thought they would. My solution to this is just good tests.
-** 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.
-
+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 https://docs.rs/tracing-slog/latest/tracing_slog/[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.
 
 * Various other small quality of life changes.
 
 Since the two 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 https://docs.rs/dropshot/[online Dropshot documentation].
 You can build the documentation yourself with:
@@ -69,3 +77,6 @@ It's early, and we may find we need richer facilities in the framework.  But we'
 == 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.

dropshot/examples/basic.rs

@@ -24,11 +24,12 @@ async fn main() -> Result<(), String> {
     // port.
     let config_dropshot: ConfigDropshot = Default::default();
 
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // Build a description of the API.
     let mut api = ApiDescription::new();

dropshot/examples/file_server.rs

@@ -26,11 +26,12 @@ async fn main() -> Result<(), String> {
     // port.
     let config_dropshot = Default::default();
 
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // Build a description of the API -- in this case it's not much of an API!.
     let mut api = ApiDescription::new();

dropshot/examples/https.rs

@@ -66,11 +66,12 @@ async fn main() -> Result<(), String> {
         key_file: key_file.path().to_path_buf(),
     });
 
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // Build a description of the API.
     let mut api = ApiDescription::new();

dropshot/examples/index.rs

@@ -20,11 +20,12 @@ async fn main() -> Result<(), String> {
     // port.
     let config_dropshot: ConfigDropshot = Default::default();
 
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // Build a description of the API.
     let mut api = ApiDescription::new();

dropshot/examples/module-basic.rs

@@ -16,11 +16,12 @@ async fn main() -> Result<(), String> {
     // port.
     let config_dropshot = Default::default();
 
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // Build a description of the API.
     let mut api = ApiDescription::new();

dropshot/examples/module-shared-context.rs

@@ -24,11 +24,12 @@ async fn main() -> Result<(), String> {
     // port.
     let config_dropshot = Default::default();
 
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // Build a description of the API.
     let mut api = ApiDescription::new();

dropshot/examples/multipart.rs

@@ -19,11 +19,12 @@ async fn main() -> Result<(), String> {
     // port.
     let config_dropshot: ConfigDropshot = Default::default();
 
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // Build a description of the API.
     let mut api = ApiDescription::new();

dropshot/examples/multiple-servers.rs

@@ -188,7 +188,7 @@ impl SharedMultiServerContext {
         };
 
         tracing_subscriber::fmt()
-            .with_max_level(tracing::Level::TRACE)
+            .with_max_level(tracing::Level::INFO)
             .with_target(false)
             .compact()
             .init();

dropshot/examples/pagination-basic.rs

@@ -98,11 +98,12 @@ async fn example_list_projects(
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     let port = std::env::args()
         .nth(1)

dropshot/examples/pagination-multiple-resources.rs

@@ -267,11 +267,12 @@ where
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     let port = std::env::args()
         .nth(1)

dropshot/examples/pagination-multiple-sorts.rs

@@ -281,11 +281,12 @@ async fn example_list_projects(
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     let port = std::env::args()
         .nth(1)

dropshot/examples/petstore.rs

@@ -6,11 +6,12 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // Build a description of the API.
     let mut api = ApiDescription::new();

dropshot/examples/request-headers.rs

@@ -20,11 +20,12 @@ use dropshot::RequestContext;
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     let config_dropshot: ConfigDropshot = Default::default();
     let mut api = ApiDescription::new();

dropshot/examples/schema-with-example.rs

@@ -48,11 +48,12 @@ fn bar_example() -> Bar {
 }
 
 fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     let mut api = ApiDescription::new();
     api.register(get_foo).unwrap();

dropshot/examples/self-referential.rs

@@ -18,11 +18,12 @@ use std::sync::Arc;
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     let config_dropshot: ConfigDropshot = Default::default();
 

dropshot/examples/websocket.rs

@@ -16,11 +16,12 @@ use tokio_tungstenite::tungstenite::Message;
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // We must specify a configuration with a bind address.  We'll use 127.0.0.1
     // since it's available and won't expose this server outside the host.  We

dropshot/examples/well-tagged.rs

@@ -45,11 +45,12 @@ async fn get_fryism(
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    tracing_subscriber::fmt()
-        .with_max_level(tracing::Level::TRACE)
-        .with_target(false)
-        .compact()
-        .init();
+    // Uncomment for logs
+    // tracing_subscriber::fmt()
+    //     .with_max_level(tracing::Level::INFO)
+    //     .with_target(false)
+    //     .compact()
+    //     .init();
 
     // We must specify a configuration with a bind address.  We'll use 127.0.0.1
     // since it's available and won't expose this server outside the host.  We