[nexus] Add address lot view method. (#8752)

Part of
oxidecomputer/terraform-provider-oxide#468.
The terraform resource expects to be able to create/read/delete address
lots, and so far nexus only supports create/list/delete. This patch adds
a new endpoint for viewing an address lot by name or id.

This is my first attempt to work on this repo, so let me know if this is
off-base @internet-diglett.

Author: jmcarp

common/src/api/external/mod.rs

@@ -2588,6 +2588,16 @@ pub struct AddressLotCreateResponse {
     pub blocks: Vec<AddressLotBlock>,
 }
 
+/// An address lot and associated blocks resulting from viewing an address lot.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct AddressLotViewResponse {
+    /// The address lot.
+    pub lot: AddressLot,
+
+    /// The address lot blocks.
+    pub blocks: Vec<AddressLotBlock>,
+}
+
 /// Represents an address lot object, containing the id of the lot that can be
 /// used in other API calls.
 // TODO Add kind attribute to AddressLot

nexus/db-queries/src/db/datastore/address_lot.rs

@@ -248,13 +248,18 @@ impl DataStore {
         &self,
         opctx: &OpContext,
         authz_address_lot: &authz::AddressLot,
-        pagparams: &DataPageParams<'_, Uuid>,
+        pagparams: Option<&DataPageParams<'_, Uuid>>,
     ) -> ListResultVec<AddressLotBlock> {
         use nexus_db_schema::schema::address_lot_block::dsl;
 
         let conn = self.pool_connection_authorized(opctx).await?;
 
-        paginated(dsl::address_lot_block, dsl::id, &pagparams)
+        let table = match pagparams {
+            Some(params) => paginated(dsl::address_lot_block, dsl::id, &params),
+            None => dsl::address_lot_block.into_boxed(),
+        };
+
+        table
             .filter(dsl::address_lot_id.eq(authz_address_lot.id()))
             .select(AddressLotBlock::as_select())
             .load_async(&*conn)

nexus/external-api/output/nexus_tags.txt

@@ -243,6 +243,7 @@ networking_address_lot_block_list        GET      /v1/system/networking/address-
 networking_address_lot_create            POST     /v1/system/networking/address-lot
 networking_address_lot_delete            DELETE   /v1/system/networking/address-lot/{address_lot}
 networking_address_lot_list              GET      /v1/system/networking/address-lot
+networking_address_lot_view              GET      /v1/system/networking/address-lot/{address_lot}
 networking_allow_list_update             PUT      /v1/system/networking/allow-list
 networking_allow_list_view               GET      /v1/system/networking/allow-list
 networking_bfd_disable                   POST     /v1/system/networking/bfd-disable

nexus/external-api/src/lib.rs

@@ -1630,6 +1630,17 @@ pub trait NexusExternalApi {
         query_params: Query<PaginatedByNameOrId>,
     ) -> Result<HttpResponseOk<ResultsPage<AddressLot>>, HttpError>;
 
+    /// Fetch address lot
+    #[endpoint {
+        method = GET,
+        path = "/v1/system/networking/address-lot/{address_lot}",
+        tags = ["system/networking"],
+    }]
+    async fn networking_address_lot_view(
+        rqctx: RequestContext<Self::Context>,
+        path_params: Path<params::AddressLotPath>,
+    ) -> Result<HttpResponseOk<AddressLotViewResponse>, HttpError>;
+
     /// List blocks in address lot
     #[endpoint {
         method = GET,

nexus/src/app/address_lot.rs

@@ -74,7 +74,7 @@ impl super::Nexus {
         self: &Arc<Self>,
         opctx: &OpContext,
         address_lot: &lookup::AddressLot<'_>,
-        pagparams: &DataPageParams<'_, Uuid>,
+        pagparams: Option<&DataPageParams<'_, Uuid>>,
     ) -> ListResultVec<AddressLotBlock> {
         let (.., authz_address_lot) =
             address_lot.lookup_for(authz::Action::ListChildren).await?;

nexus/src/external_api/http_entrypoints.rs

@@ -58,6 +58,7 @@ use nexus_types::{
 use omicron_common::api::external::AddressLot;
 use omicron_common::api::external::AddressLotBlock;
 use omicron_common::api::external::AddressLotCreateResponse;
+use omicron_common::api::external::AddressLotViewResponse;
 use omicron_common::api::external::AffinityGroupMember;
 use omicron_common::api::external::AggregateBgpMessageHistory;
 use omicron_common::api::external::AntiAffinityGroupMember;
@@ -3479,6 +3480,36 @@ impl NexusExternalApi for NexusExternalApiImpl {
             .await
     }
 
+    async fn networking_address_lot_view(
+        rqctx: RequestContext<ApiContext>,
+        path_params: Path<params::AddressLotPath>,
+    ) -> Result<HttpResponseOk<AddressLotViewResponse>, HttpError> {
+        let apictx = rqctx.context();
+        let handler = async {
+            let opctx =
+                crate::context::op_context_for_external_api(&rqctx).await?;
+            let nexus = &apictx.context.nexus;
+            let path = path_params.into_inner();
+            let lookup = nexus.address_lot_lookup(&opctx, path.address_lot)?;
+            let (.., lot) = lookup.fetch().await?;
+            let blocks = nexus
+                .address_lot_block_list(&opctx, &lookup, None)
+                .await?
+                .into_iter()
+                .map(|p| p.into())
+                .collect();
+            Ok(HttpResponseOk(AddressLotViewResponse {
+                lot: lot.into(),
+                blocks,
+            }))
+        };
+        apictx
+            .context
+            .external_latencies
+            .instrument_dropshot_handler(&rqctx, handler)
+            .await
+    }
+
     async fn networking_address_lot_delete(
         rqctx: RequestContext<ApiContext>,
         path_params: Path<params::AddressLotPath>,
@@ -3550,7 +3581,11 @@ impl NexusExternalApi for NexusExternalApiImpl {
             let address_lot_lookup =
                 nexus.address_lot_lookup(&opctx, path.address_lot)?;
             let blocks = nexus
-                .address_lot_block_list(&opctx, &address_lot_lookup, &pagparams)
+                .address_lot_block_list(
+                    &opctx,
+                    &address_lot_lookup,
+                    Some(&pagparams),
+                )
                 .await?
                 .into_iter()
                 .map(|p| p.into())

nexus/tests/integration_tests/address_lots.rs

@@ -15,7 +15,7 @@ use nexus_types::external_api::params::{
 };
 use omicron_common::api::external::{
     AddressLot, AddressLotBlock, AddressLotCreateResponse, AddressLotKind,
-    IdentityMetadataCreateParams,
+    AddressLotViewResponse, IdentityMetadataCreateParams,
 };
 use std::net::IpAddr;
 
@@ -78,6 +78,25 @@ async fn test_address_lot_basic_crud(ctx: &ControlPlaneTestContext) {
         "203.0.113.20".parse::<IpAddr>().unwrap()
     );
 
+    // View a single lot by name
+    let view_lot = NexusRequest::object_get(
+        client,
+        "/v1/system/networking/address-lot/parkinglot",
+    )
+    .authn_as(AuthnMode::PrivilegedUser)
+    .execute_and_parse_unwrap::<AddressLotViewResponse>()
+    .await;
+    assert_eq!(view_lot.lot.identity.name, "parkinglot");
+    assert_eq!(view_lot.blocks.len(), params.blocks.len());
+    assert_eq!(
+        view_lot.blocks[0].first_address,
+        "203.0.113.10".parse::<IpAddr>().unwrap()
+    );
+    assert_eq!(
+        view_lot.blocks[0].last_address,
+        "203.0.113.20".parse::<IpAddr>().unwrap()
+    );
+
     // Verify there are lots
     let lots = NexusRequest::iter_collection_authn::<AddressLot>(
         client,

nexus/tests/integration_tests/endpoints.rs

@@ -2738,7 +2738,7 @@ pub static VERIFY_ENDPOINTS: LazyLock<Vec<VerifyEndpoint>> = LazyLock::new(
                 url: &DEMO_ADDRESS_LOT_URL,
                 visibility: Visibility::Protected,
                 unprivileged_access: UnprivilegedAccess::None,
-                allowed_methods: vec![AllowedMethod::Delete],
+                allowed_methods: vec![AllowedMethod::GetNonexistent, AllowedMethod::Delete],
             },
             VerifyEndpoint {
                 url: &DEMO_ADDRESS_LOT_BLOCKS_URL,

openapi/nexus.json

@@ -9187,6 +9187,42 @@
       }
     },
     "/v1/system/networking/address-lot/{address_lot}": {
+      "get": {
+        "tags": [
+          "system/networking"
+        ],
+        "summary": "Fetch address lot",
+        "operationId": "networking_address_lot_view",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "address_lot",
+            "description": "Name or ID of the address lot",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/NameOrId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AddressLotViewResponse"
+                }
+              }
+            }
+          },
+          "4XX": {
+            "$ref": "#/components/responses/Error"
+          },
+          "5XX": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      },
       "delete": {
         "tags": [
           "system/networking"
@@ -13671,6 +13707,31 @@
           "items"
         ]
       },
+      "AddressLotViewResponse": {
+        "description": "An address lot and associated blocks resulting from viewing an address lot.",
+        "type": "object",
+        "properties": {
+          "blocks": {
+            "description": "The address lot blocks.",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AddressLotBlock"
+            }
+          },
+          "lot": {
+            "description": "The address lot.",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/AddressLot"
+              }
+            ]
+          }
+        },
+        "required": [
+          "blocks",
+          "lot"
+        ]
+      },
       "AffinityGroup": {
         "description": "View of an Affinity Group",
         "type": "object",