Restructure HttpServer's API

CHANGELOG.adoc

@@ -15,6 +15,42 @@ https://github.com/oxidecomputer/dropshot/compare/v0.4.0\...HEAD[Full list of co
 // configured in release.toml.  DO NOT change the format of the headers or the
 // list of raw commits.
 
+`HttpServer` has been split into two objects, `HttpServerStarter`, and
+`HttpServer`.
+- In the old implementation, `HttpServer` represented both a pending and
+  running server. Callers were expected to invoke `run()` to begin execution of
+the old server.
+- In the new implementation, `HttpServerStarter` may be used to construct a
+  server, and `HttpServer` represents the running server. Invoking
+`HttpServerStarter::start()` creates and `HttpServer` object, which represents
+the new server.
+
+`HttpServer` now implements `Future`, and does not directly expose a
+`tokio::JoinHandle`.
+- In the old implementation, `HttpServer` returned a `tokio::JoinHandle`, and
+  callers were expected to invoke `wait_for_shutdown` to await the completion
+of a server.
+- In the new implementation, `HttpServer` implements `Future`, and may be
+  `await`-ed directly.
+
+As an example:
+
+```rust
+// 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;
+```
+
 == 0.4.0 (released 2021-02-01)
 
 https://github.com/oxidecomputer/dropshot/compare/v0.3.0\...v0.4.0[Full list of commits]

dropshot/examples/basic.rs

@@ -11,7 +11,7 @@ use dropshot::ConfigLoggingLevel;
 use dropshot::HttpError;
 use dropshot::HttpResponseOk;
 use dropshot::HttpResponseUpdatedNoContent;
-use dropshot::HttpServer;
+use dropshot::HttpServerStarter;
 use dropshot::RequestContext;
 use dropshot::TypedBody;
 use schemars::JsonSchema;
@@ -58,15 +58,16 @@ async fn main() -> Result<(), String> {
     /*
      * Set up the server.
      */
-    let mut server = HttpServer::new(&config_dropshot, api, api_context, &log)
-        .map_err(|error| format!("failed to create server: {}", error))?;
-    let server_task = server.run();
+    let server =
+        HttpServerStarter::new(&config_dropshot, api, api_context, &log)
+            .map_err(|error| format!("failed to create server: {}", error))?
+            .start();
 
     /*
      * Wait for the server to stop.  Note that there's not any code to shut down
      * this server, so we should never get past this point.
      */
-    server.wait_for_shutdown(server_task).await
+    server.await
 }
 
 /**

dropshot/examples/module-basic.rs

@@ -6,7 +6,7 @@
 use dropshot::ApiDescription;
 use dropshot::ConfigLogging;
 use dropshot::ConfigLoggingLevel;
-use dropshot::HttpServer;
+use dropshot::HttpServerStarter;
 use dropshot::RequestContext;
 use schemars::JsonSchema;
 use serde::Deserialize;
@@ -51,15 +51,16 @@ async fn main() -> Result<(), String> {
     /*
      * Set up the server.
      */
-    let mut server = HttpServer::new(&config_dropshot, api, api_context, &log)
-        .map_err(|error| format!("failed to create server: {}", error))?;
-    let server_task = server.run();
+    let server =
+        HttpServerStarter::new(&config_dropshot, api, api_context, &log)
+            .map_err(|error| format!("failed to create server: {}", error))?
+            .start();
 
     /*
      * Wait for the server to stop.  Note that there's not any code to shut down
      * this server, so we should never get past this point.
      */
-    server.wait_for_shutdown(server_task).await
+    server.await
 }
 
 /**

dropshot/examples/pagination-basic.rs

@@ -24,7 +24,7 @@ use dropshot::ConfigLoggingLevel;
 use dropshot::EmptyScanParams;
 use dropshot::HttpError;
 use dropshot::HttpResponseOk;
-use dropshot::HttpServer;
+use dropshot::HttpServerStarter;
 use dropshot::PaginationParams;
 use dropshot::Query;
 use dropshot::RequestContext;
@@ -153,8 +153,8 @@ async fn main() -> Result<(), String> {
         .map_err(|error| format!("failed to create logger: {}", error))?;
     let mut api = ApiDescription::new();
     api.register(example_list_projects).unwrap();
-    let mut server = HttpServer::new(&config_dropshot, api, ctx, &log)
-        .map_err(|error| format!("failed to create server: {}", error))?;
-    let server_task = server.run();
-    server.wait_for_shutdown(server_task).await
+    let server = HttpServerStarter::new(&config_dropshot, api, ctx, &log)
+        .map_err(|error| format!("failed to create server: {}", error))?
+        .start();
+    server.await
 }

dropshot/examples/pagination-multiple-resources.rs

@@ -12,7 +12,7 @@ use dropshot::ConfigLogging;
 use dropshot::ConfigLoggingLevel;
 use dropshot::HttpError;
 use dropshot::HttpResponseOk;
-use dropshot::HttpServer;
+use dropshot::HttpServerStarter;
 use dropshot::PaginationOrder;
 use dropshot::PaginationOrder::Ascending;
 use dropshot::PaginationOrder::Descending;
@@ -307,10 +307,11 @@ async fn main() -> Result<(), String> {
     api.register(example_list_projects).unwrap();
     api.register(example_list_disks).unwrap();
     api.register(example_list_instances).unwrap();
-    let mut server = HttpServer::new(&config_dropshot, api, ctx, &log)
-        .map_err(|error| format!("failed to create server: {}", error))?;
-    let server_task = server.run();
-    server.wait_for_shutdown(server_task).await
+    let server = HttpServerStarter::new(&config_dropshot, api, ctx, &log)
+        .map_err(|error| format!("failed to create server: {}", error))?
+        .start();
+
+    server.await
 }
 
 fn rqctx_to_data(rqctx: Arc<RequestContext>) -> Arc<DataCollection> {

dropshot/examples/pagination-multiple-sorts.rs

@@ -100,7 +100,7 @@ use dropshot::ConfigLogging;
 use dropshot::ConfigLoggingLevel;
 use dropshot::HttpError;
 use dropshot::HttpResponseOk;
-use dropshot::HttpServer;
+use dropshot::HttpServerStarter;
 use dropshot::PaginationOrder;
 use dropshot::PaginationOrder::Ascending;
 use dropshot::PaginationOrder::Descending;
@@ -326,16 +326,16 @@ async fn main() -> Result<(), String> {
         .map_err(|error| format!("failed to create logger: {}", error))?;
     let mut api = ApiDescription::new();
     api.register(example_list_projects).unwrap();
-    let mut server = HttpServer::new(&config_dropshot, api, ctx, &log)
-        .map_err(|error| format!("failed to create server: {}", error))?;
-    let server_task = server.run();
+    let server = HttpServerStarter::new(&config_dropshot, api, ctx, &log)
+        .map_err(|error| format!("failed to create server: {}", error))?
+        .start();
 
     /*
      * Print out some example requests to start with.
      */
     print_example_requests(log, &server.local_addr());
 
-    server.wait_for_shutdown(server_task).await
+    server.await
 }
 
 fn print_example_requests(log: slog::Logger, addr: &SocketAddr) {

dropshot/src/lib.rs

@@ -47,7 +47,7 @@
  * use dropshot::ConfigDropshot;
  * use dropshot::ConfigLogging;
  * use dropshot::ConfigLoggingLevel;
- * use dropshot::HttpServer;
+ * use dropshot::HttpServerStarter;
  * use std::sync::Arc;
  *
  * #[tokio::main]
@@ -61,12 +61,12 @@
  *         .map_err(|e| e.to_string())?;
  *
  *     // Describe the API.
- *     let mut api = ApiDescription::new();
+ *     let api = ApiDescription::new();
  *     // Register API functions -- see detailed example or ApiDescription docs.
  *
  *     // Start the server.
- *     let mut server =
- *         HttpServer::new(
+ *     let server =
+ *         HttpServerStarter::new(
  *             &ConfigDropshot {
  *                 bind_address: "127.0.0.1:0".parse().unwrap(),
  *                 request_body_max_bytes: 1024,
@@ -75,10 +75,10 @@
  *             Arc::new(()),
  *             &log,
  *         )
- *         .map_err(|error| format!("failed to start server: {}", error))?;
+ *         .map_err(|error| format!("failed to start server: {}", error))?
+ *         .start();
  *
- *     let server_task = server.run();
- *     server.wait_for_shutdown(server_task).await
+ *     server.await
  * }
  * ```
  *
@@ -542,7 +542,7 @@ pub use pagination::PaginationOrder;
 pub use pagination::PaginationParams;
 pub use pagination::ResultsPage;
 pub use pagination::WhichPage;
-pub use server::HttpServer;
+pub use server::{HttpServer, HttpServerStarter};
 
 /*
  * Users of the `endpoint` macro need `http::Method` available.