add builder interface for making servers

CHANGELOG.adoc

@@ -15,6 +15,37 @@
 
 https://github.com/oxidecomputer/dropshot/compare/v0.12.0\...HEAD[Full list of commits]
 
+* https://github.com/oxidecomputer/dropshot/pull/1122[#1122] Adds a new `ServerBuilder` as the primary way of constructing a Dropshot server.  This replaces `HttpServerStarter::new()` and `HttpServerStarter::new_with_tls()`.  These older functions still exist for compatibility.  They may be removed in an upcoming release, along with the `HttpServerStarter`.
++
+In this release, using the builder interface is not very different from using these older functions.  But as we look at adding new construction-time options (e.g., for API versioning), those will only be added to the builder.
++
+The builder also provides structured errors rather than the `GenericError` provided by these older functions.
++
+To switch to the new `ServerBuilder`, if you were using `HttpServerStarter::new()`, replace:
++
+```rust
+HttpServerStarter::new(config, api, private, log)
+```
++
+with:
++
+```rust
+ServerBuilder::new(api, private, log.clone()).config(config.clone())
+```
++
+To switch to the new `ServerBuilder` if you were using `HttpServerStarter::new_with_tls()`, replace:
++
+```rust
+HttpServerStarter::new_with_tls(config, api, private, log, tls)
+```
++
+with:
++
+```rust
+ServerBuilder::new(api, private, log.clone()).config(config.clone()).tls(tls)
+```
+
+
 == 0.12.0 (released 2024-09-26)
 
 https://github.com/oxidecomputer/dropshot/compare/v0.11.0\...v0.12.0[Full list of commits]

dropshot/Cargo.toml

@@ -42,6 +42,7 @@ slog-async = "2.8.0"
 slog-bunyan = "2.5.0"
 slog-json = "2.6.1"
 slog-term = "2.9.1"
+thiserror = "1.0.64"
 tokio-rustls = "0.25.0"
 toml = "0.8.19"
 waitgroup = "0.1.2"

dropshot/examples/api-trait-alternate.rs

@@ -74,7 +74,7 @@
 //! [`AsyncWrite`](tokio::io::AsyncWrite) with a blanket impl. In that case, the
 //! behavior of methods like `AsyncWriteExt::write_all` cannot be overridden.
 
-use dropshot::{ConfigLogging, ConfigLoggingLevel, HttpServerStarter};
+use dropshot::{ConfigLogging, ConfigLoggingLevel, ServerBuilder};
 
 /// The interface.
 mod api {
@@ -203,7 +203,6 @@ mod imp {
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    let config_dropshot = Default::default();
     // For simplicity, we'll configure an "info"-level logger that writes to
     // stderr assuming that it's a terminal.
     let config_logging =
@@ -218,14 +217,9 @@ async fn main() -> Result<(), String> {
 
     let my_api =
         api::counter_api_mod::api_description::<imp::CounterImpl>().unwrap();
-    let server = HttpServerStarter::new(
-        &config_dropshot,
-        my_api,
-        imp::AtomicCounter::new(),
-        &log,
-    )
-    .map_err(|error| format!("failed to create server: {}", error))?
-    .start();
+    let server = ServerBuilder::new(my_api, imp::AtomicCounter::new(), log)
+        .start()
+        .map_err(|error| format!("failed to create server: {}", error))?;
 
     server.await
 }

dropshot/examples/api-trait-websocket.rs

@@ -2,7 +2,7 @@
 
 //! Example use of `dropshot::api_description` with a WebSocket endpoint.
 
-use dropshot::{ConfigLogging, ConfigLoggingLevel, HttpServerStarter};
+use dropshot::{ConfigLogging, ConfigLoggingLevel, ServerBuilder};
 
 /// The interface.
 mod api {
@@ -133,7 +133,6 @@ mod imp {
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    let config_dropshot = Default::default();
     // For simplicity, we'll configure an "info"-level logger that writes to
     // stderr assuming that it's a terminal.
     let config_logging =
@@ -148,14 +147,9 @@ async fn main() -> Result<(), String> {
 
     let my_server =
         api::counter_api_mod::api_description::<imp::CounterImpl>().unwrap();
-    let server = HttpServerStarter::new(
-        &config_dropshot,
-        my_server,
-        imp::AtomicCounter::new(),
-        &log,
-    )
-    .map_err(|error| format!("failed to create server: {}", error))?
-    .start();
+    let server = ServerBuilder::new(my_server, imp::AtomicCounter::new(), log)
+        .start()
+        .map_err(|error| format!("failed to create server: {}", error))?;
 
     server.await
 }

dropshot/examples/api-trait.rs

@@ -15,7 +15,7 @@
 //!
 //! This example puts the interface and implementation in separate modules.
 
-use dropshot::{ConfigLogging, ConfigLoggingLevel, HttpServerStarter};
+use dropshot::{ConfigLogging, ConfigLoggingLevel, ServerBuilder};
 
 /// The interface.
 mod api {
@@ -134,7 +134,6 @@ mod imp {
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    let config_dropshot = Default::default();
     // For simplicity, we'll configure an "info"-level logger that writes to
     // stderr assuming that it's a terminal.
     let config_logging =
@@ -151,14 +150,9 @@ async fn main() -> Result<(), String> {
     // type parameter.
     let my_api =
         api::counter_api_mod::api_description::<imp::CounterImpl>().unwrap();
-    let server = HttpServerStarter::new(
-        &config_dropshot,
-        my_api,
-        imp::AtomicCounter::new(),
-        &log,
-    )
-    .map_err(|error| format!("failed to create server: {}", error))?
-    .start();
+    let server = ServerBuilder::new(my_api, imp::AtomicCounter::new(), log)
+        .start()
+        .map_err(|error| format!("failed to create server: {}", error))?;
 
     server.await
 }

dropshot/examples/basic.rs

@@ -3,14 +3,13 @@
 
 use dropshot::endpoint;
 use dropshot::ApiDescription;
-use dropshot::ConfigDropshot;
 use dropshot::ConfigLogging;
 use dropshot::ConfigLoggingLevel;
 use dropshot::HttpError;
 use dropshot::HttpResponseOk;
 use dropshot::HttpResponseUpdatedNoContent;
-use dropshot::HttpServerStarter;
 use dropshot::RequestContext;
+use dropshot::ServerBuilder;
 use dropshot::TypedBody;
 use schemars::JsonSchema;
 use serde::Deserialize;
@@ -20,12 +19,6 @@ use std::sync::atomic::Ordering;
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    // 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
-    // request port 0, which allows the operating system to pick any available
-    // port.
-    let config_dropshot: ConfigDropshot = Default::default();
-
     // For simplicity, we'll configure an "info"-level logger that writes to
     // stderr assuming that it's a terminal.
     let config_logging =
@@ -43,10 +36,14 @@ async fn main() -> Result<(), String> {
     let api_context = ExampleContext::new();
 
     // Set up the server.
-    let server =
-        HttpServerStarter::new(&config_dropshot, api, api_context, &log)
-            .map_err(|error| format!("failed to create server: {}", error))?
-            .start();
+    //
+    // We use the default configuration here, which uses 127.0.0.1 since it's
+    // always available and won't expose this server outside the host.  It also
+    // uses port 0, which allows the operating system to pick any available
+    // port.
+    let server = ServerBuilder::new(api, api_context, log)
+        .start()
+        .map_err(|error| format!("failed to create server: {}", error))?;
 
     // 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.

dropshot/examples/https.rs

@@ -4,15 +4,14 @@
 
 use dropshot::endpoint;
 use dropshot::ApiDescription;
-use dropshot::ConfigDropshot;
 use dropshot::ConfigLogging;
 use dropshot::ConfigLoggingLevel;
 use dropshot::ConfigTls;
 use dropshot::HttpError;
 use dropshot::HttpResponseOk;
 use dropshot::HttpResponseUpdatedNoContent;
-use dropshot::HttpServerStarter;
 use dropshot::RequestContext;
+use dropshot::ServerBuilder;
 use dropshot::TypedBody;
 use schemars::JsonSchema;
 use serde::Deserialize;
@@ -52,17 +51,9 @@ fn generate_keys() -> Result<(NamedTempFile, NamedTempFile), String> {
 
 #[tokio::main]
 async fn main() -> Result<(), String> {
-    // Begin by generating TLS certificates and keys. A normal application would
-    // just pass the paths to these via ConfigDropshot.
+    // Begin by generating TLS certificates and keys and stuffing them into a
+    // TLS configuration.
     let (cert_file, key_file) = generate_keys()?;
-
-    // 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
-    // request port 0, which allows the operating system to pick any available
-    // port.
-    //
-    // In addition, we'll make this an HTTPS server.
-    let config_dropshot = ConfigDropshot::default();
     let config_tls = Some(ConfigTls::AsFile {
         cert_file: cert_file.path().to_path_buf(),
         key_file: key_file.path().to_path_buf(),
@@ -85,15 +76,10 @@ async fn main() -> Result<(), String> {
     let api_context = ExampleContext::new();
 
     // Set up the server.
-    let server = HttpServerStarter::new_with_tls(
-        &config_dropshot,
-        api,
-        api_context,
-        &log,
-        config_tls,
-    )
-    .map_err(|error| format!("failed to create server: {}", error))?
-    .start();
+    let server = ServerBuilder::new(api, api_context, log)
+        .tls(config_tls)
+        .start()
+        .map_err(|error| format!("failed to create server: {}", error))?;
 
     // 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.

dropshot/src/handler.rs

@@ -567,8 +567,8 @@ impl HttpResponse for Response<Body> {
     }
 }
 
-/// Wraps a [dropshot::Body] so that it can be used with coded response types such
-/// as [HttpResponseOk].
+/// Wraps a [`Body`] so that it can be used with coded response types such as
+/// [HttpResponseOk].
 pub struct FreeformBody(pub Body);
 
 impl From<Body> for FreeformBody {

dropshot/src/lib.rs

@@ -49,7 +49,7 @@
 //! use dropshot::ConfigLogging;
 //! use dropshot::ConfigLoggingLevel;
 //! use dropshot::HandlerTaskMode;
-//! use dropshot::HttpServerStarter;
+//! use dropshot::ServerBuilder;
 //! use std::sync::Arc;
 //!
 //! #[tokio::main]
@@ -67,20 +67,9 @@
 //!     // Register API functions -- see detailed example or ApiDescription docs.
 //!
 //!     // Start the server.
-//!     let server =
-//!         HttpServerStarter::new(
-//!             &ConfigDropshot {
-//!                 bind_address: "127.0.0.1:0".parse().unwrap(),
-//!                 request_body_max_bytes: 1024,
-//!                 default_handler_task_mode: HandlerTaskMode::Detached,
-//!                 log_headers: Default::default(),
-//!             },
-//!             api,
-//!             Arc::new(()),
-//!             &log,
-//!         )
-//!         .map_err(|error| format!("failed to start server: {}", error))?
-//!         .start();
+//!     let server = ServerBuilder::new(api, Arc::new(()), log)
+//!         .start()
+//!         .map_err(|error| format!("failed to start server: {}", error))?;
 //!
 //!     server.await
 //! }
@@ -836,6 +825,8 @@ pub use pagination::PaginationOrder;
 pub use pagination::PaginationParams;
 pub use pagination::ResultsPage;
 pub use pagination::WhichPage;
+pub use server::BuildError;
+pub use server::ServerBuilder;
 pub use server::ServerContext;
 pub use server::ShutdownWaitFuture;
 pub use server::{HttpServer, HttpServerStarter};