oxidecomputer · sunshowers · Mar 4, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -13,6 +13,7 @@ members = [
     "downstairs",
     "downstairs-api",
     "downstairs-types",
+    "downstairs-types/versions",
     "dropshot-apis",
     "dsc",
     "dsc-client",
@@ -153,6 +154,7 @@ crucible-control-client = { path = "./control-client" }
 crucible-downstairs = { path = "./downstairs" }
 crucible-downstairs-api = { path = "./downstairs-api" }
 crucible-downstairs-types = { path = "./downstairs-types" }
+crucible-downstairs-types-versions = { path = "./downstairs-types/versions" }
 crucible-pantry = { path = "./pantry" }
 crucible-pantry-api = { path = "./pantry-api" }
 crucible-pantry-client = { path = "./pantry-client" }

diff --git a/downstairs-api/Cargo.toml b/downstairs-api/Cargo.toml
@@ -7,11 +7,8 @@ rust-version = "1.85"
 
 [dependencies]
 crucible-common.workspace = true
-crucible-downstairs-types.workspace = true
+crucible-downstairs-types-versions.workspace = true
 crucible-workspace-hack.workspace = true
 dropshot.workspace = true
 dropshot-api-manager-types.workspace = true
 hyper.workspace = true
-schemars.workspace = true
-serde.workspace = true
-uuid.workspace = true
diff --git a/downstairs-api/src/lib.rs b/downstairs-api/src/lib.rs
@@ -3,16 +3,13 @@
 //! API traits for Crucible downstairs operations.
 
 use crucible_common::RegionDefinition;
-use crucible_downstairs_types::{FileType, RunDownstairsForRegionParams};
+use crucible_downstairs_types_versions::latest;
 use dropshot::{
     Body, HttpError, HttpResponseCreated, HttpResponseOk, Path, RequestContext,
     TypedBody,
 };
 use dropshot_api_manager_types::api_versions;
 use hyper::Response;
-use schemars::JsonSchema;
-use serde::{Deserialize, Serialize};
-use uuid::Uuid;
 
 api_versions!([
     // WHEN CHANGING THE API (part 1 of 2):
@@ -53,9 +50,12 @@ pub trait CrucibleDownstairsAdminApi {
     }]
     async fn run_downstairs_for_region(
         rqctx: RequestContext<Self::Context>,
-        path_param: Path<RunDownstairsForRegionPath>,
-        run_params: TypedBody<RunDownstairsForRegionParams>,
-    ) -> Result<HttpResponseCreated<DownstairsRunningResponse>, HttpError>;
+        path_param: Path<latest::admin::RunDownstairsForRegionPath>,
+        run_params: TypedBody<latest::admin::RunDownstairsForRegionParams>,
+    ) -> Result<
+        HttpResponseCreated<latest::admin::DownstairsRunningResponse>,
+        HttpError,
+    >;
 }
 
 /// API trait for the downstairs repair server.
@@ -70,7 +70,7 @@ pub trait CrucibleDownstairsRepairApi {
     }]
     async fn get_extent_file(
         rqctx: RequestContext<Self::Context>,
-        path: Path<ExtentFilePath>,
+        path: Path<latest::repair::ExtentFilePath>,
     ) -> Result<Response<Body>, HttpError>;
 
     /// Return true if the provided extent is closed or the region is read only.
@@ -80,7 +80,7 @@ pub trait CrucibleDownstairsRepairApi {
     }]
     async fn extent_repair_ready(
         rqctx: RequestContext<Self::Context>,
-        path: Path<ExtentPath>,
+        path: Path<latest::repair::ExtentPath>,
     ) -> Result<HttpResponseOk<bool>, HttpError>;
 
     /// Get the list of files related to an extent.
@@ -93,7 +93,7 @@ pub trait CrucibleDownstairsRepairApi {
     }]
     async fn get_files_for_extent(
         rqctx: RequestContext<Self::Context>,
-        path: Path<ExtentPath>,
+        path: Path<latest::repair::ExtentPath>,
     ) -> Result<HttpResponseOk<Vec<String>>, HttpError>;
 
     /// Return the RegionDefinition describing our region.
@@ -123,31 +123,3 @@ pub trait CrucibleDownstairsRepairApi {
         rqctx: RequestContext<Self::Context>,
     ) -> Result<HttpResponseOk<bool>, HttpError>;
 }
-
-// Admin API types
-#[derive(Deserialize, JsonSchema)]
-pub struct RunDownstairsForRegionPath {
-    pub uuid: Uuid,
-}
-
-#[derive(Serialize, JsonSchema)]
-pub struct DownstairsRunningResponse {
-    pub uuid: Uuid,
-}
-
-// Repair API types
-#[derive(Deserialize, JsonSchema)]
-pub struct ExtentPath {
-    pub eid: u32,
-}
-
-#[derive(Deserialize, JsonSchema)]
-pub struct ExtentFilePath {
-    pub eid: u32,
-    pub file_type: FileType,
-}
-
-#[derive(Deserialize, JsonSchema)]
-pub struct JobPath {
-    pub id: String,
-}
diff --git a/downstairs-types/Cargo.toml b/downstairs-types/Cargo.toml
@@ -6,10 +6,5 @@ edition = "2024"
 rust-version = "1.85"
 
 [dependencies]
-crucible-common.workspace = true
+crucible-downstairs-types-versions.workspace = true
 crucible-workspace-hack.workspace = true
-schemars.workspace = true
-serde.workspace = true
-
-[dev-dependencies]
-serde_json.workspace = true
diff --git a/downstairs-types/src/admin.rs b/downstairs-types/src/admin.rs
@@ -0,0 +1,3 @@
+// Copyright 2026 Oxide Computer Company
+
+pub use crucible_downstairs_types_versions::latest::admin::*;
diff --git a/downstairs-types/src/lib.rs b/downstairs-types/src/lib.rs
@@ -1,44 +1,4 @@
-// Copyright 2025 Oxide Computer Company
+// Copyright 2026 Oxide Computer Company
 
-use std::net::{IpAddr, SocketAddr};
-use std::path::PathBuf;
-
-use schemars::JsonSchema;
-use serde::Deserialize;
-
-#[derive(Deserialize, JsonSchema)]
-#[serde(rename_all = "camelCase")]
-pub enum FileType {
-    #[serde(rename = "data")]
-    Data,
-    #[serde(rename = "db")]
-    Database,
-    #[serde(rename = "db_shm")]
-    DatabaseSharedMemory,
-    #[serde(rename = "db_wal")]
-    DatabaseLog,
-}
-
-#[derive(Deserialize, JsonSchema)]
-pub struct FileSpec {
-    pub eid: u32,
-    pub file_type: FileType,
-}
-
-// Admin API types
-#[derive(Deserialize, JsonSchema)]
-pub struct RunDownstairsForRegionParams {
-    pub address: IpAddr,
-    pub data: PathBuf,
-    pub oximeter: Option<SocketAddr>,
-    pub lossy: bool,
-    pub port: u16,
-    pub rport: u16,
-    pub read_errors: bool,
-    pub write_errors: bool,
-    pub flush_errors: bool,
-    pub cert_pem: Option<String>,
-    pub key_pem: Option<String>,
-    pub root_cert_pem: Option<String>,
-    pub read_only: bool,
-}
+pub mod admin;
+pub mod repair;
diff --git a/downstairs-types/src/repair.rs b/downstairs-types/src/repair.rs
@@ -0,0 +1,3 @@
+// Copyright 2026 Oxide Computer Company
+
+pub use crucible_downstairs_types_versions::latest::repair::*;
diff --git a/downstairs-types/versions/Cargo.toml b/downstairs-types/versions/Cargo.toml
@@ -0,0 +1,11 @@
+[package]
+name = "crucible-downstairs-types-versions"
+version = "0.1.0"
+license = "MPL-2.0"
+edition = "2024"
+
+[dependencies]
+crucible-workspace-hack.workspace = true
+schemars.workspace = true
+serde.workspace = true
+uuid.workspace = true
diff --git a/downstairs-types/versions/src/impls/mod.rs b/downstairs-types/versions/src/impls/mod.rs
@@ -0,0 +1,6 @@
+// Copyright 2026 Oxide Computer Company
+
+//! Functional code for the latest versions of types.
+
+// Currently a placeholder. Remove this comment when functional code is added in
+// a submodule.
diff --git a/downstairs-types/versions/src/initial/admin.rs b/downstairs-types/versions/src/initial/admin.rs
@@ -0,0 +1,35 @@
+// Copyright 2026 Oxide Computer Company
+
+use std::net::{IpAddr, SocketAddr};
+use std::path::PathBuf;
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+#[derive(Deserialize, JsonSchema)]
+pub struct RunDownstairsForRegionPath {
+    pub uuid: Uuid,
+}
+
+#[derive(Serialize, JsonSchema)]
+pub struct DownstairsRunningResponse {
+    pub uuid: Uuid,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct RunDownstairsForRegionParams {
+    pub address: IpAddr,
+    pub data: PathBuf,
+    pub oximeter: Option<SocketAddr>,
+    pub lossy: bool,
+    pub port: u16,
+    pub rport: u16,
+    pub read_errors: bool,
+    pub write_errors: bool,
+    pub flush_errors: bool,
+    pub cert_pem: Option<String>,
+    pub key_pem: Option<String>,
+    pub root_cert_pem: Option<String>,
+    pub read_only: bool,
+}
diff --git a/downstairs-types/versions/src/initial/mod.rs b/downstairs-types/versions/src/initial/mod.rs
@@ -0,0 +1,6 @@
+// Copyright 2026 Oxide Computer Company
+
+//! Version `INITIAL` of the Crucible Downstairs APIs.
+
+pub mod admin;
+pub mod repair;
diff --git a/downstairs-types/versions/src/initial/repair.rs b/downstairs-types/versions/src/initial/repair.rs
@@ -0,0 +1,39 @@
+// Copyright 2026 Oxide Computer Company
+
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+#[derive(Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+pub enum FileType {
+    #[serde(rename = "data")]
+    Data,
+    #[serde(rename = "db")]
+    Database,
+    #[serde(rename = "db_shm")]
+    DatabaseSharedMemory,
+    #[serde(rename = "db_wal")]
+    DatabaseLog,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct FileSpec {
+    pub eid: u32,
+    pub file_type: FileType,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct ExtentPath {
+    pub eid: u32,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct ExtentFilePath {
+    pub eid: u32,
+    pub file_type: FileType,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct JobPath {
+    pub id: String,
+}
diff --git a/downstairs-types/versions/src/latest.rs b/downstairs-types/versions/src/latest.rs
@@ -0,0 +1,15 @@
+// Copyright 2026 Oxide Computer Company
+
+pub mod admin {
+    pub use crate::v1::admin::DownstairsRunningResponse;
+    pub use crate::v1::admin::RunDownstairsForRegionParams;
+    pub use crate::v1::admin::RunDownstairsForRegionPath;
+}
+
+pub mod repair {
+    pub use crate::v1::repair::ExtentFilePath;
+    pub use crate::v1::repair::ExtentPath;
+    pub use crate::v1::repair::FileSpec;
+    pub use crate::v1::repair::FileType;
+    pub use crate::v1::repair::JobPath;
+}
diff --git a/downstairs-types/versions/src/lib.rs b/downstairs-types/versions/src/lib.rs
@@ -0,0 +1,33 @@
+// Copyright 2026 Oxide Computer Company
+
+//! Versioned types for the Crucible Downstairs APIs.
+//!
+//! # Adding a new API version
+//!
+//! When adding a new API version N with added or changed types:
+//!
+//! 1. Create <version_name>/mod.rs, where <version_name> is the lowercase
+//!    form of the new version's identifier, as defined in the API trait's
+//!    `api_versions!` macro.
+//!
+//! 2. Add to the end of this list:
+//!
+//!    ```rust,ignore
+//!    #[path = "<version_name>/mod.rs"]
+//!    pub mod vN;
+//!    ```
+//!
+//! 3. Add your types to the new module, mirroring the module structure from
+//!    earlier versions.
+//!
+//! 4. Update `latest.rs` with new and updated types from the new version.
+//!
+//! For more information, see the [detailed guide] and [RFD 619].
+//!
+//! [detailed guide]: https://github.com/oxidecomputer/dropshot-api-manager/blob/main/guides/new-version.md
+//! [RFD 619]: https://rfd.shared.oxide.computer/rfd/619
+
+mod impls;
+pub mod latest;
+#[path = "initial/mod.rs"]
+pub mod v1;
diff --git a/downstairs/src/admin.rs b/downstairs/src/admin.rs
@@ -3,7 +3,10 @@ use super::*;
 
 use anyhow::anyhow;
 use crucible_downstairs_api::*;
-use crucible_downstairs_types::RunDownstairsForRegionParams;
+use crucible_downstairs_types::admin::{
+    DownstairsRunningResponse, RunDownstairsForRegionParams,
+    RunDownstairsForRegionPath,
+};
 use dropshot::{
     ClientSpecifiesVersionInHeader, ConfigDropshot, HttpError,
     HttpResponseCreated, Path, RequestContext, TypedBody, VersionPolicy,

diff --git a/downstairs/src/repair.rs b/downstairs/src/repair.rs
@@ -3,7 +3,7 @@ use std::path::PathBuf;
 use std::sync::Arc;
 
 use crucible_downstairs_api::*;
-use crucible_downstairs_types::FileType;
+use crucible_downstairs_types::repair::{ExtentFilePath, ExtentPath, FileType};
 use dropshot::{
     Body, ConfigDropshot, HandlerTaskMode, HttpError, HttpResponseOk,
     HttpServerStarter, Path, RequestContext,
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		// Copyright 2026 Oxide Computer Company

		pub use crucible_downstairs_types_versions::latest::admin::*;