[crucible-agent] migrate to API trait (#1766)

Part of oxidecomputer/omicron#8922.

Author: sunshowers

Cargo.lock

@@ -1,7 +1,9 @@
 [workspace]
 members = [
     "agent",
+    "agent-api",
     "agent-client",
+    "agent-types",
     "crucible-client-types",
     "common",
     "control-client",
@@ -131,8 +133,10 @@ oximeter-producer = { git = "https://github.com/oxidecomputer/omicron", branch =
 
 # local path
 crucible = { path = "./upstairs" }
-crucible-client-types = { path = "./crucible-client-types" }
+crucible-agent-api = { path = "./agent-api" }
 crucible-agent-client = { path = "./agent-client" }
+crucible-agent-types = { path = "./agent-types" }
+crucible-client-types = { path = "./crucible-client-types" }
 crucible-common = { path = "./common" }
 crucible-control-client = { path = "./control-client" }
 # importantly, don't use features = ["zfs_snapshot"] here, this will cause

Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "crucible-agent-api"
+version = "0.1.0"
+license = "MPL-2.0"
+edition = "2024"
+
+[dependencies]
+crucible-agent-types.workspace = true
+crucible-workspace-hack.workspace = true
+dropshot.workspace = true
+schemars.workspace = true
+serde.workspace = true

agent-api/Cargo.toml

@@ -0,0 +1,128 @@
+// Copyright 2025 Oxide Computer Company
+
+use std::collections::BTreeMap;
+
+use crucible_agent_types::{
+    region::{CreateRegion, Region, RegionId},
+    snapshot::{RunningSnapshot, Snapshot},
+};
+use dropshot::{
+    HttpError, HttpResponseDeleted, HttpResponseOk, Path, RequestContext,
+    TypedBody,
+};
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+#[dropshot::api_description]
+pub trait CrucibleAgentApi {
+    type Context;
+
+    #[endpoint {
+        method = GET,
+        path = "/crucible/0/regions",
+    }]
+    async fn region_list(
+        rqctx: RequestContext<Self::Context>,
+    ) -> Result<HttpResponseOk<Vec<Region>>, HttpError>;
+
+    #[endpoint {
+        method = POST,
+        path = "/crucible/0/regions",
+    }]
+    async fn region_create(
+        rqctx: RequestContext<Self::Context>,
+        body: TypedBody<CreateRegion>,
+    ) -> Result<HttpResponseOk<Region>, HttpError>;
+
+    #[endpoint {
+        method = GET,
+        path = "/crucible/0/regions/{id}",
+    }]
+    async fn region_get(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<RegionPath>,
+    ) -> Result<HttpResponseOk<Region>, HttpError>;
+
+    #[endpoint {
+        method = DELETE,
+        path = "/crucible/0/regions/{id}",
+    }]
+    async fn region_delete(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<RegionPath>,
+    ) -> Result<HttpResponseDeleted, HttpError>;
+
+    #[endpoint {
+        method = GET,
+        path = "/crucible/0/regions/{id}/snapshots",
+    }]
+    async fn region_get_snapshots(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<RegionPath>,
+    ) -> Result<HttpResponseOk<GetSnapshotResponse>, HttpError>;
+
+    #[endpoint {
+        method = GET,
+        path = "/crucible/0/regions/{id}/snapshots/{name}",
+    }]
+    async fn region_get_snapshot(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<GetSnapshotPath>,
+    ) -> Result<HttpResponseOk<Snapshot>, HttpError>;
+
+    #[endpoint {
+        method = DELETE,
+        path = "/crucible/0/regions/{id}/snapshots/{name}",
+    }]
+    async fn region_delete_snapshot(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<DeleteSnapshotPath>,
+    ) -> Result<HttpResponseDeleted, HttpError>;
+
+    #[endpoint {
+        method = POST,
+        path = "/crucible/0/regions/{id}/snapshots/{name}/run",
+    }]
+    async fn region_run_snapshot(
+        rqctx: RequestContext<Self::Context>,
+        path: Path<RunSnapshotPath>,
+    ) -> Result<HttpResponseOk<RunningSnapshot>, HttpError>;
+
+    #[endpoint {
+        method = DELETE,
+        path = "/crucible/0/regions/{id}/snapshots/{name}/run",
+    }]
+    async fn region_delete_running_snapshot(
+        rc: RequestContext<Self::Context>,
+        path: Path<RunSnapshotPath>,
+    ) -> Result<HttpResponseDeleted, HttpError>;
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct RegionPath {
+    pub id: RegionId,
+}
+
+#[derive(Serialize, JsonSchema)]
+pub struct GetSnapshotResponse {
+    pub snapshots: Vec<Snapshot>,
+    pub running_snapshots: BTreeMap<String, RunningSnapshot>,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct GetSnapshotPath {
+    pub id: RegionId,
+    pub name: String,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct DeleteSnapshotPath {
+    pub id: RegionId,
+    pub name: String,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct RunSnapshotPath {
+    pub id: RegionId,
+    pub name: String,
+}

agent-api/src/lib.rs

@@ -0,0 +1,15 @@
+[package]
+name = "crucible-agent-types"
+version = "0.1.0"
+license = "MPL-2.0"
+edition = "2024"
+
+[dependencies]
+chrono.workspace = true
+crucible-smf.workspace = true
+crucible-workspace-hack.workspace = true
+serde.workspace = true
+schemars.workspace = true
+
+[dev-dependencies]
+serde_json.workspace = true

agent-types/Cargo.toml

@@ -0,0 +1,5 @@
+// Copyright 2025 Oxide Computer Company
+
+pub mod region;
+pub mod smf;
+pub mod snapshot;

agent-types/src/lib.rs

@@ -1,13 +1,14 @@
-// Copyright 2021 Oxide Computer Company
+// Copyright 2025 Oxide Computer Company
 
 use std::net::SocketAddr;
 use std::path::Path;
 
-use chrono::prelude::*;
-use crucible_smf::scf_type_t::{self, *};
+use crucible_smf::scf_type_t::*;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+use crate::smf::SmfProperty;
+
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Serialize, Deserialize, JsonSchema, Debug, PartialEq, Clone)]
 #[serde(rename_all = "lowercase")]
@@ -58,12 +59,6 @@ pub struct Region {
     pub read_only: bool,
 }
 
-pub struct SmfProperty<'a> {
-    pub name: &'a str,
-    pub typ: scf_type_t,
-    pub val: String,
-}
-
 impl Region {
     /**
      * Given a root directory, return a list of SMF properties to ensure for
@@ -205,124 +200,6 @@ impl CreateRegion {
 )]
 pub struct RegionId(pub String);
 
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Serialize, Deserialize, JsonSchema, Debug, PartialEq, Clone)]
-pub struct Snapshot {
-    pub name: String,
-    pub created: DateTime<Utc>,
-}
-
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Serialize, Deserialize, JsonSchema, Debug, PartialEq, Clone)]
-pub struct RunningSnapshot {
-    pub id: RegionId,
-    pub name: String,
-    pub port_number: u16,
-    pub state: State,
-}
-
-impl RunningSnapshot {
-    /**
-     * Given a root directory, return a list of SMF properties to ensure for
-     * the corresponding running instance.
-     */
-    pub fn get_smf_properties(&self, dir: &Path) -> Vec<SmfProperty> {
-        let mut results = vec![
-            SmfProperty {
-                name: "directory",
-                typ: SCF_TYPE_ASTRING,
-                val: dir.to_str().unwrap().to_string(),
-            },
-            SmfProperty {
-                name: "port",
-                typ: SCF_TYPE_COUNT,
-                val: self.port_number.to_string(),
-            },
-            SmfProperty {
-                name: "mode",
-                typ: SCF_TYPE_ASTRING,
-                val: "ro".to_string(),
-            },
-        ];
-
-        // Test for X509 files in snapshot - note this means that running
-        // snapshots will use the X509 information in the snapshot, not a new
-        // set.
-        {
-            let mut path = dir.to_path_buf();
-            path.push("cert.pem");
-            let path = path.into_os_string().into_string().unwrap();
-
-            if Path::new(&path).exists() {
-                results.push(SmfProperty {
-                    name: "cert_pem_path",
-                    typ: SCF_TYPE_ASTRING,
-                    val: path,
-                });
-            }
-        }
-
-        {
-            let mut path = dir.to_path_buf();
-            path.push("key.pem");
-            let path = path.into_os_string().into_string().unwrap();
-
-            if Path::new(&path).exists() {
-                results.push(SmfProperty {
-                    name: "key_pem_path",
-                    typ: SCF_TYPE_ASTRING,
-                    val: path,
-                });
-            }
-        }
-
-        {
-            let mut path = dir.to_path_buf();
-            path.push("root.pem");
-            let path = path.into_os_string().into_string().unwrap();
-
-            if Path::new(&path).exists() {
-                results.push(SmfProperty {
-                    name: "root_pem_path",
-                    typ: SCF_TYPE_ASTRING,
-                    val: path,
-                });
-            }
-        }
-
-        results
-    }
-}
-
-pub struct CreateRunningSnapshotRequest {
-    pub id: RegionId,
-    pub name: String,
-    pub cert_pem: Option<String>,
-    pub key_pem: Option<String>,
-    pub root_pem: Option<String>,
-}
-
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Serialize, Deserialize, JsonSchema, Debug, PartialEq, Clone)]
-pub struct DeleteRunningSnapshotRequest {
-    pub id: RegionId,
-    pub name: String,
-}
-
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Serialize, Deserialize, JsonSchema, Debug, PartialEq, Clone)]
-pub struct DeleteSnapshotRequest {
-    pub id: RegionId,
-    pub name: String,
-}
-
-// The different types of resources the worker thread monitors for changes. This
-// wraps the object that has been added, or changed somehow.
-pub enum Resource {
-    Region(Region),
-    RunningSnapshot(RegionId, String, RunningSnapshot),
-}
-
 #[cfg(test)]
 mod test {
     use super::*;

agent/src/model.rs renamed to agent-types/src/region.rs

@@ -0,0 +1,9 @@
+// Copyright 2025 Oxide Computer Company
+
+use crucible_smf::scf_type_t;
+
+pub struct SmfProperty<'a> {
+    pub name: &'a str,
+    pub typ: scf_type_t,
+    pub val: String,
+}