[lldpd] make API versioned (#40)

Last part of lldp work for oxidecomputer/omicron#8922.

Author: sunshowers

Cargo.lock

@@ -25,6 +25,7 @@ protocol = { path = "protocol" }
 
 # oxide dependencies from github
 dpd-client = { git = "https://github.com/oxidecomputer/dendrite", branch = "main" }
+omicron-common = { git = "https://github.com/oxidecomputer/omicron", branch = "main" }
 
 # public dependencies from crates.io
 anyhow = "1.0"

Cargo.toml

@@ -32,8 +32,8 @@ pub fn environment() -> anyhow::Result<Environment> {
 pub fn all_apis() -> anyhow::Result<ManagedApis> {
     let apis = vec![ManagedApiConfig {
         ident: "lldpd",
-        versions: Versions::Lockstep {
-            version: semver::Version::new(0, 0, 1),
+        versions: Versions::Versioned {
+            supported_versions: lldpd_api::supported_versions(),
         },
         title: "Oxide LLDP Daemon",
         metadata: ManagedApiMetadata {

dropshot-apis/src/main.rs

@@ -6,6 +6,7 @@ license = "MPL-2.0"
 
 [dependencies]
 dropshot.workspace = true
+dropshot-api-manager-types.workspace = true
 lldpd-types.workspace = true
 protocol.workspace = true
 schemars.workspace = true

lldpd-api/Cargo.toml

@@ -11,6 +11,7 @@ use dropshot::{
     HttpResponseOk, HttpResponseUpdatedNoContent, PaginationParams, Path,
     Query, RequestContext, ResultsPage, TypedBody,
 };
+use dropshot_api_manager_types::api_versions;
 use lldpd_types::{
     build_info::BuildInfo,
     interfaces::{Interface, InterfaceAdd},
@@ -20,6 +21,33 @@ use protocol::types::{ChassisId, PortId, SystemCapabilities};
 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:
+//
+//     (2, ADD_FOOBAR)
+//
+// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
+// were added or removed.
+
 #[dropshot::api_description]
 pub trait LldpdApi {
     type Context;

lldpd-api/src/lib.rs

@@ -15,7 +15,7 @@ pub const fn default_port() -> u16 {
 
 // Automatically generate the client bindings using Progenitor.
 progenitor::generate_api!(
-    spec = "../openapi/lldpd.json",
+    spec = "../openapi/lldpd/lldpd-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {

lldpd-client/src/lib.rs

@@ -17,6 +17,7 @@ http.workspace = true
 lldpd-api.workspace = true
 lldpd-common.workspace = true
 lldpd-types.workspace = true
+omicron-common.workspace = true
 protocol.workspace = true
 signal-hook.workspace = true
 serde.workspace = true

lldpd/Cargo.toml

@@ -12,6 +12,7 @@ use std::net::Ipv4Addr;
 use std::net::SocketAddr;
 use std::sync::Arc;
 
+use dropshot::ClientSpecifiesVersionInHeader;
 use dropshot::EmptyScanParams;
 use dropshot::HttpError;
 use dropshot::HttpResponseCreated;
@@ -24,6 +25,7 @@ use dropshot::Query;
 use dropshot::RequestContext;
 use dropshot::ResultsPage;
 use dropshot::TypedBody;
+use dropshot::VersionPolicy;
 use dropshot::WhichPage;
 use lldpd_api::*;
 use lldpd_types::build_info::BuildInfo;
@@ -573,17 +575,22 @@ fn launch_server(
         default_handler_task_mode: dropshot::HandlerTaskMode::Detached,
         log_headers: Vec::new(),
     };
-    let log = global
-        .log
-        .new(o!("unit" => "api-server", "server_id" => id.to_string()));
 
-    slog::info!(log, "starting api server {id} on {addr}");
-    dropshot::HttpServerStarter::new(
-        &config_dropshot,
+    dropshot::ServerBuilder::new(
         http_api(),
         global.clone(),
-        &log,
+        global
+            .log
+            .new(o!("unit" => "api-server", "server_id" => id.to_string())),
     )
+    .config(config_dropshot)
+    .version_policy(VersionPolicy::Dynamic(Box::new(
+        ClientSpecifiesVersionInHeader::new(
+            omicron_common::api::VERSION_HEADER,
+            lldpd_api::latest_version(),
+        ),
+    )))
+    .build_starter()
     .map(|s| s.start())
     .map_err(|e| anyhow::anyhow!(e.to_string()))
 }

lldpd/src/api_server.rs

@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/build-info": {

openapi/lldpd.json renamed to openapi/lldpd/lldpd-1.0.0-c4e95f.json

@@ -0,0 +1 @@
+lldpd-1.0.0-c4e95f.json