make mg-admin and ddm-admin APIs versioned

Cargo.toml

@@ -61,8 +61,8 @@ serde = { version = "1.0.219", features = ["derive"] }
 hostname = "0.3"
 thiserror = "1.0"
 dropshot = { version = "0.16.4", features = [ "usdt-probes" ] }
-dropshot-api-manager = "0.2.1"
-dropshot-api-manager-types = "0.2.1"
+dropshot-api-manager = "0.2.2"
+dropshot-api-manager-types = "0.2.2"
 schemars = { version = "0.8", features = [ "uuid1", "chrono" ] }
 tokio = { version = "1.37", features = ["full"] }
 serde_repr = "0.1"

README.md

@@ -29,9 +29,9 @@ with support for the lower-half data planes listed below.
 
 ## APIs
 
-- [x] [DDM OpenAPI](openapi/ddm-admin.json)
+- [x] [DDM OpenAPI](openapi/ddm-admin/ddm-admin-latest.json)
 - [x] [DDM Rust Client Library](ddm-admin-client)
-- [x] [MGD OpenAPI](openapi/mg-admin.json)
+- [x] [MGD OpenAPI](openapi/mg-admin/mg-admin-latest.json)
 - [x] [MGD Rust Client Library](mg-admin-client)
 
 ## Delay Driven Multipath (DDM)

ddm-admin-client/src/lib.rs

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 progenitor::generate_api!(
-    spec = "../openapi/ddm-admin.json",
+    spec = "../openapi/ddm-admin/ddm-admin-latest.json",
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
         slog::trace!(log, "client request";

ddm-api/Cargo.toml

@@ -6,6 +6,7 @@ edition = "2024"
 [dependencies]
 ddm-types.workspace = true
 dropshot.workspace = true
+dropshot-api-manager-types.workspace = true
 mg-common.workspace = true
 oxnet.workspace = true
 schemars.workspace = true

ddm-api/src/lib.rs

@@ -11,6 +11,7 @@ use dropshot::HttpResponseUpdatedNoContent;
 use dropshot::Path;
 use dropshot::RequestContext;
 use dropshot::TypedBody;
+use dropshot_api_manager_types::api_versions;
 use mg_common::net::TunnelOrigin;
 use oxnet::Ipv6Net;
 use schemars::JsonSchema;
@@ -21,6 +22,33 @@ use uuid::Uuid;
 
 pub type PrefixMap = BTreeMap<Ipv6Addr, HashSet<PathVector>>;
 
+api_versions!([
+    // WHEN CHANGING THE API (part 1 of 2):
+    //
+    // +- Pick a new semver and define it in the list below.  The list MUST
+    // |  remain sorted, which generally means that your version should go at
+    // |  the very top.
+    // |
+    // |  Duplicate this line, uncomment the *second* copy, update that copy for
+    // |  your new API version, and leave the first copy commented out as an
+    // |  example for the next person.
+    // v
+    // (next_int, IDENT),
+    (1, INITIAL),
+]);
+
+// WHEN CHANGING THE API (part 2 of 2):
+//
+// The call to `api_versions!` above defines constants of type
+// `semver::Version` that you can use in your Dropshot API definition to specify
+// the version when a particular endpoint was added or removed.  For example, if
+// you used:
+//
+//     (1, INITIAL)
+//
+// Then you could use `VERSION_INITIAL` as the version in which endpoints were
+// added or removed.
+
 #[dropshot::api_description]
 pub trait DdmAdminApi {
     type Context;

ddm/src/admin.rs

@@ -7,21 +7,21 @@ use crate::sm::{AdminEvent, Event, PrefixSet, SmContext};
 use ddm_api::*;
 use ddm_types::db::{PeerInfo, TunnelRoute};
 use ddm_types::exchange::PathVector;
+use dropshot::ApiDescription;
+use dropshot::ApiDescriptionBuildErrors;
 use dropshot::ConfigDropshot;
 use dropshot::ConfigLogging;
 use dropshot::ConfigLoggingLevel;
 use dropshot::HttpError;
 use dropshot::HttpResponseOk;
 use dropshot::HttpResponseUpdatedNoContent;
-use dropshot::HttpServerStarter;
 use dropshot::Path;
 use dropshot::RequestContext;
 use dropshot::TypedBody;
-use dropshot::{ApiDescription, ApiDescriptionBuildErrors};
 use mg_common::lock;
 use mg_common::net::TunnelOrigin;
 use oxnet::Ipv6Net;
-use slog::{Logger, error, info, warn};
+use slog::{Logger, error, info};
 use std::collections::{HashMap, HashSet};
 use std::net::{IpAddr, SocketAddr, SocketAddrV4, SocketAddrV6};
 use std::sync::Arc;
@@ -74,16 +74,27 @@ pub fn handler(
 
     let api = api_description().map_err(|e| e.to_string())?;
 
+    let server = dropshot::ServerBuilder::new(api, context, ds_log)
+        .config(config)
+        .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+            dropshot::ClientSpecifiesVersionInHeader::new(
+                omicron_common::api::VERSION_HEADER,
+                ddm_api::latest_version(),
+            ),
+        )));
+
     info!(log, "admin: listening on {}", sa);
 
     let log = log.clone();
     spawn(async move {
-        let server = HttpServerStarter::new(&config, api, context, &ds_log)
-            .map_err(|e| format!("new admin dropshot: {}", e))
-            .unwrap();
-
-        match server.start().await {
-            Ok(_) => warn!(log, "admin: unexpected server exit"),
+        match server.start() {
+            Ok(server) => {
+                info!(log, "admin: server started");
+                match server.await {
+                    Ok(()) => info!(log, "admin: server exited"),
+                    Err(e) => error!(log, "admin: server error {:?}", e),
+                }
+            }
             Err(e) => error!(log, "admin: server start error {:?}", e),
         }
     });

dropshot-apis/src/main.rs

@@ -34,8 +34,8 @@ pub fn all_apis() -> anyhow::Result<ManagedApis> {
     let apis = vec![
         ManagedApiConfig {
             ident: "ddm-admin",
-            versions: Versions::Lockstep {
-                version: semver::Version::new(0, 1, 0),
+            versions: Versions::Versioned {
+                supported_versions: ddm_api::supported_versions(),
             },
             title: "DDM Admin",
             metadata: ManagedApiMetadata {
@@ -48,8 +48,8 @@ pub fn all_apis() -> anyhow::Result<ManagedApis> {
         },
         ManagedApiConfig {
             ident: "mg-admin",
-            versions: Versions::Lockstep {
-                version: semver::Version::new(0, 1, 0),
+            versions: Versions::Versioned {
+                supported_versions: mg_api::supported_versions(),
             },
             title: "Maghemite Admin",
             metadata: ManagedApiMetadata {

mg-admin-client/src/lib.rs

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 progenitor::generate_api!(
-    spec = "../openapi/mg-admin.json",
+    spec = "../openapi/mg-admin/mg-admin-latest.json",
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
         slog::trace!(log, "client request";

mg-api/Cargo.toml

@@ -7,6 +7,7 @@ edition = "2024"
 bfd = { path = "../bfd" }
 bgp = { path = "../bgp" }
 dropshot.workspace = true
+dropshot-api-manager-types.workspace = true
 rdb = { path = "../rdb" }
 schemars.workspace = true
 serde.workspace = true

mg-api/src/lib.rs

@@ -20,10 +20,38 @@ use dropshot::{
     HttpError, HttpResponseDeleted, HttpResponseOk,
     HttpResponseUpdatedNoContent, Path, Query, RequestContext, TypedBody,
 };
+use dropshot_api_manager_types::api_versions;
 use rdb::{BfdPeerConfig, Prefix, Prefix4, StaticRouteKey};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+api_versions!([
+    // WHEN CHANGING THE API (part 1 of 2):
+    //
+    // +- Pick a new semver and define it in the list below.  The list MUST
+    // |  remain sorted, which generally means that your version should go at
+    // |  the very top.
+    // |
+    // |  Duplicate this line, uncomment the *second* copy, update that copy for
+    // |  your new API version, and leave the first copy commented out as an
+    // |  example for the next person.
+    // v
+    // (next_int, IDENT),
+    (1, INITIAL),
+]);
+
+// WHEN CHANGING THE API (part 2 of 2):
+//
+// The call to `api_versions!` above defines constants of type
+// `semver::Version` that you can use in your Dropshot API definition to specify
+// the version when a particular endpoint was added or removed.  For example, if
+// you used:
+//
+//     (1, INITIAL)
+//
+// Then you could use `VERSION_INITIAL` as the version in which endpoints were
+// added or removed.
+
 #[dropshot::api_description]
 pub trait MgAdminApi {
     type Context;

mgd/src/admin.rs

@@ -8,14 +8,14 @@ use bgp::params::*;
 use bgp_admin::BgpContext;
 use dropshot::{
     ApiDescription, ConfigDropshot, HttpError, HttpResponseDeleted,
-    HttpResponseOk, HttpResponseUpdatedNoContent, HttpServerStarter, Path,
-    Query, RequestContext, TypedBody,
+    HttpResponseOk, HttpResponseUpdatedNoContent, Path, Query, RequestContext,
+    TypedBody,
 };
 use mg_api::*;
 use mg_common::stats::MgLowerStats;
 use rdb::{BfdPeerConfig, Db, Prefix};
 use slog::o;
-use slog::{Logger, error, info, warn};
+use slog::{Logger, error, info};
 use std::collections::HashMap;
 use std::net::{IpAddr, Ipv6Addr, SocketAddr};
 use std::sync::{Arc, Mutex};
@@ -49,14 +49,26 @@ pub fn start_server(
 
     let api = api_description();
 
-    let server = HttpServerStarter::new(&ds_config, api, context, &ds_log)
-        .map_err(|e| format!("new admin dropshot: {}", e))?;
+    let server = dropshot::ServerBuilder::new(api, context, ds_log)
+        .config(ds_config)
+        .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+            dropshot::ClientSpecifiesVersionInHeader::new(
+                omicron_common::api::VERSION_HEADER,
+                mg_api::latest_version(),
+            ),
+        )));
 
     info!(log, "admin: listening on {}", sa);
 
     Ok(tokio::spawn(async move {
-        match server.start().await {
-            Ok(_) => warn!(log, "admin: unexpected server exit"),
+        match server.start() {
+            Ok(server) => {
+                info!(log, "admin: server started");
+                match server.await {
+                    Ok(()) => info!(log, "admin: server exited"),
+                    Err(e) => error!(log, "admin: server error {:?}", e),
+                }
+            }
             Err(e) => error!(log, "admin: server start error {:?}", e),
         }
     }))

openapi/ddm-admin.json → openapi/ddm-admin/ddm-admin-1.0.0-b6eac7.json

@@ -6,7 +6,7 @@
       "url": "https://oxide.computer",
       "email": "[email protected]"
     },
-    "version": "0.1.0"
+    "version": "1.0.0"
   },
   "paths": {
     "/disable-stats": {

openapi/ddm-admin/ddm-admin-latest.json

@@ -0,0 +1 @@
+ddm-admin-1.0.0-b6eac7.json

openapi/mg-admin.json → openapi/mg-admin/mg-admin-1.0.0-69e2d5.json

@@ -6,7 +6,7 @@
       "url": "https://oxide.computer",
       "email": "[email protected]"
     },
-    "version": "0.1.0"
+    "version": "1.0.0"
   },
   "paths": {
     "/bestpath/config/fanout": {

openapi/mg-admin/mg-admin-latest.json

@@ -0,0 +1 @@
+mg-admin-1.0.0-69e2d5.json