lib.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

use std::collections::BTreeMap;

use anyhow::anyhow;
use dropshot::Body;
use dropshot::{
    EmptyScanParams, EndpointTagPolicy, Header, HttpError,
    HttpResponseAccepted, HttpResponseCreated, HttpResponseDeleted,
    HttpResponseFound, HttpResponseHeaders, HttpResponseOk,
    HttpResponseSeeOther, HttpResponseUpdatedNoContent, PaginationParams, Path,
    Query, RequestContext, ResultsPage, StreamingBody, TypedBody,
    WebsocketChannelResult, WebsocketConnection,
};
use dropshot_api_manager_types::{ValidationContext, api_versions};
use http::Response;
use ipnetwork::IpNetwork;
use nexus_types::{
    authn::cookies::Cookies,
    external_api::{
        headers, params, shared,
        views::{self, MulticastGroupMember, RackMembershipStatus},
    },
};
use omicron_common::api::external::{
    http_pagination::{
        PaginatedById, PaginatedByName, PaginatedByNameOrId,
        PaginatedByTimeAndId, PaginatedByVersion,
    },
    *,
};
use openapiv3::OpenAPI;

/// Copies of data types that changed between versions
mod v2025112000;
mod v2025120300;
pub mod v2025121200;
mod v2025122300;
mod v2026010100;
mod v2026010300;
mod v2026010500;
mod v2026011600;

#[cfg(test)]
mod test_utils;

api_versions!([
    // API versions are in the format YYYYMMDDNN.0.0, defined below as
    // YYYYMMDDNN. Here, NN is a two-digit number starting at 00 for a
    // particular date.
    //
    // WHEN CHANGING THE API (part 1 of 2):
    //
    // +- First, determine the next API version number to use.
    // |
    // |  * On the main branch: Take today's date in YYYYMMDD format, e.g. 20251112.
    // |    Find the smallest NN that isn't already defined in the list below. In
    // |    most cases, that is 00, but if 00 is already taken, use 01, 02, etc.
    // |
    // |  * On a release branch, don't alter the date. Instead, always bump the NN.
    // |
    // |  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.
    // |
    // |  If there's a merge conflict, update the version number to the current
    // |  date. Otherwise, it is okay to leave the version number unchanged even
    // |  if you land your change on a different day from the one you make it on.
    // |
    // |  Ensure that version numbers are sorted in descending order. (This macro
    // |  will panic at runtime if they're not in descending order.) The newest
    // |  date-based version should be at the top of the list.
    // v
    // (next_yyyymmddnn, IDENT),
    (2026012200, FLOATING_IP_ALLOCATOR_UPDATE),
    (2026012100, TRUST_QUORUM_ADD_SLEDS_AND_GET_LATEST_CONFIG),
    (2026011601, EXTERNAL_SUBNET_ATTACHMENT),
    (2026011600, RENAME_ADDRESS_SELECTOR_TO_ADDRESS_ALLOCATOR),
    (2026011501, AUDIT_LOG_CREDENTIAL_ID),
    (2026011500, AUDIT_LOG_AUTH_METHOD_ENUM),
    (2026011300, DOC_LINT_SUMMARY_TRAILING_PERIOD),
    (2026011100, MULTICAST_JOIN_LEAVE_DOCS),
    (2026010800, MULTICAST_IMPLICIT_LIFECYCLE_UPDATES),
    (2026010500, POOL_SELECTION_ENUMS),
    (2026010300, DUAL_STACK_NICS),
    (2026010100, SILO_PROJECT_IP_VERSION_AND_POOL_TYPE),
    (2025122300, IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS),
    (2025121200, BGP_PEER_COLLISION_STATE),
    (2025120300, LOCAL_STORAGE),
    (2025112000, 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:
//
//     (2025120100, ADD_FOOBAR)
//
// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
// were added or removed.

const MIB: usize = 1024 * 1024;
const GIB: usize = 1024 * MIB;
const DISK_BULK_WRITE_MAX_BYTES: usize = 8 * MIB;
// Full release repositories are currently (Dec 2024) 1.8 GiB and are likely to
// continue growing.
const PUT_UPDATE_REPOSITORY_MAX_BYTES: usize = 4 * GIB;

// API ENDPOINT FUNCTION NAMING CONVENTIONS
//
// Generally, HTTP resources are grouped within some collection. For a
// relatively simple example:
//
//   GET    v1/projects                (list the projects in the collection)
//   POST   v1/projects                (create a project in the collection)
//   GET    v1/projects/{project}      (look up a project in the collection)
//   DELETE v1/projects/{project}      (delete a project in the collection)
//   PUT    v1/projects/{project}      (update a project in the collection)
//
// We pick a name for the function that implements a given API entrypoint
// based on how we expect it to appear in the CLI subcommand hierarchy. For
// example:
//
//   GET    v1/projects                 -> project_list()
//   POST   v1/projects                 -> project_create()
//   GET    v1/projects/{project}       -> project_view()
//   DELETE v1/projects/{project}       -> project_delete()
//   PUT    v1/projects/{project}       -> project_update()
//
// Note that the path typically uses the entity's plural form while the
// function name uses its singular.
//
// Operations beyond list, create, view, delete, and update should use a
// descriptive noun or verb, again bearing in mind that this will be
// transcribed into the CLI and SDKs:
//
//   POST   -> instance_reboot
//   POST   -> instance_stop
//   GET    -> instance_serial_console
//
// Note that these function names end up in generated OpenAPI spec as the
// operationId for each endpoint, and therefore represent a contract with
// clients. Client generators use operationId to name API methods, so changing
// a function name is a breaking change from a client perspective.

#[dropshot::api_description {
    tag_config = {
        allow_other_tags = false,
        policy = EndpointTagPolicy::ExactlyOne,
        tags = {
            "affinity" = {
                description = "Anti-affinity groups give control over instance placement.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/affinity"
                }

            },
            "console-auth" = {
                description = "API for console authentication",
                external_docs = {
                    url = "http://docs.oxide.computer/api/console-auth"
                }
            },
            "current-user" = {
                description = "Information pertaining to the current user.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/current-user"
                }
            },
            "disks" = {
                description = "Virtual disks are used to store instance-local data which includes the operating system.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/disks"
                }
            },
            "experimental" = {
                description = "Experimental, unstable interfaces, primarily for use by Oxide personnel",
                external_docs = {
                    url = "http://docs.oxide.computer/api/experimental"
                }
            },
            "floating-ips" = {
                description = "Floating IPs allow a project to allocate well-known IPs to instances.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/floating-ips"
                }
            },
            "external-subnets" = {
                description = "External subnets that can be attached to instances.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/external-subnets"
                }
            },
            "images" = {
                description = "Images are read-only virtual disks that may be used to boot virtual machines.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/images"
                }
            },
            "instances" = {
                description = "Virtual machine instances are the basic unit of computation. These operations are used for provisioning, controlling, and destroying instances.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/instances"
                }
            },
            "login" = {
                description = "Authentication endpoints",
                external_docs = {
                    url = "http://docs.oxide.computer/api/login"
                }
            },
            "metrics" = {
                description = "Silo-scoped metrics",
                external_docs = {
                    url = "http://docs.oxide.computer/api/metrics"
                }
            },
            "multicast-groups" = {
                description = "Multicast groups provide efficient one-to-many network communication.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/multicast-groups"
                }
            },
            "policy" = {
                description = "System-wide IAM policy",
                external_docs = {
                    url = "http://docs.oxide.computer/api/policy"
                }
            },
            "projects" = {
                description = "Projects are a grouping of associated resources such as instances and disks within a silo for purposes of billing and access control.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/projects"
                }
            },
            "silos" = {
                description = "Silos represent a logical partition of users and resources.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/silos"
                }
            },
            "snapshots" = {
                description = "Snapshots of virtual disks at a particular point in time.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/snapshots"
                }
            },
            "tokens" = {
                description = "API clients use device access tokens for authentication.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/tokens"
                }
            },
            "vpcs" = {
                description = "Virtual Private Clouds (VPCs) provide isolated network environments for managing and deploying services.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/vpcs"
                }
            },
            "system/alerts" = {
                description = "Alerts deliver notifications for events that occur on the Oxide rack",
                external_docs = {
                    url = "http://docs.oxide.computer/api/alerts"
                }
            },
            "system/audit-log" = {
                description = "These endpoints relate to audit logs.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-audit-log"
                }
            },
            "system/probes" = {
                description = "Probes for testing network connectivity",
                external_docs = {
                    url = "http://docs.oxide.computer/api/probes"
                }
            },
            "system/status" = {
                description = "Endpoints related to system health",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-status"
                }
            },
            "system/hardware" = {
                description = "These operations pertain to hardware inventory and management. Racks are the unit of expansion of an Oxide deployment. Racks are in turn composed of sleds, switches, power supplies, and a cabled backplane.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-hardware"
                }
            },
            "system/metrics" = {
                description = "Metrics provide insight into the operation of the Oxide deployment. These include telemetry on hardware and software components that can be used to understand the current state as well as to diagnose issues.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-metrics"
                }
            },
            "system/ip-pools" = {
                description = "IP pools are collections of external IPs that can be assigned to silos. When a pool is linked to a silo, users in that silo can allocate IPs from the pool for their instances.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-ip-pools"
                }
            },
            "system/subnet-pools" = {
                description = "Subnet pools are collections of IP subnets \
                    that can be assigned to silos. When a pool is linked to \
                    a silo, users in that silo can allocate external subnets \
                    from the pool.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-subnet-pools"
                }
            },
            "system/networking" = {
                description = "This provides rack-level network configuration.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-networking"
                }
            },
            "system/silos" = {
                description = "Silos represent a logical partition of users and resources.",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-silos"
                }
            },
            "system/update" = {
                description = "Upload and manage system updates",
                external_docs = {
                    url = "http://docs.oxide.computer/api/system-update"
                }
            },
        }
    }
}]
pub trait NexusExternalApi {
    type Context;

    /// Ping API
    ///
    /// Always responds with Ok if it responds at all.
    #[endpoint {
        method = GET,
        path = "/v1/ping",
        tags = ["system/status"],
    }]
    async fn ping(
        _rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<views::Ping>, HttpError> {
        Ok(HttpResponseOk(views::Ping { status: views::PingStatus::Ok }))
    }

    /// Fetch top-level IAM policy
    #[endpoint {
        method = GET,
        path = "/v1/system/policy",
        tags = ["policy"],
    }]
    async fn system_policy_view(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<shared::Policy<shared::FleetRole>>, HttpError>;

    /// Update top-level IAM policy
    #[endpoint {
        method = PUT,
        path = "/v1/system/policy",
        tags = ["policy"],
    }]
    async fn system_policy_update(
        rqctx: RequestContext<Self::Context>,
        new_policy: TypedBody<shared::Policy<shared::FleetRole>>,
    ) -> Result<HttpResponseOk<shared::Policy<shared::FleetRole>>, HttpError>;

    /// Fetch current silo's IAM policy
    #[endpoint {
        method = GET,
        path = "/v1/policy",
        tags = ["silos"],
    }]
    async fn policy_view(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<shared::Policy<shared::SiloRole>>, HttpError>;

    /// Update current silo's IAM policy
    #[endpoint {
        method = PUT,
        path = "/v1/policy",
        tags = ["silos"],
    }]
    async fn policy_update(
        rqctx: RequestContext<Self::Context>,
        new_policy: TypedBody<shared::Policy<shared::SiloRole>>,
    ) -> Result<HttpResponseOk<shared::Policy<shared::SiloRole>>, HttpError>;

    /// Fetch current silo's auth settings
    #[endpoint {
        method = GET,
        path = "/v1/auth-settings",
        tags = ["silos"],
    }]
    async fn auth_settings_view(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<views::SiloAuthSettings>, HttpError>;

    /// Update current silo's auth settings
    #[endpoint {
        method = PUT,
        path = "/v1/auth-settings",
        tags = ["silos"],
    }]
    async fn auth_settings_update(
        rqctx: RequestContext<Self::Context>,
        new_settings: TypedBody<params::SiloAuthSettingsUpdate>,
    ) -> Result<HttpResponseOk<views::SiloAuthSettings>, HttpError>;

    /// Fetch resource utilization for user's current silo
    #[endpoint {
        method = GET,
        path = "/v1/utilization",
        tags = ["silos"],
    }]
    async fn utilization_view(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<views::Utilization>, HttpError>;

    /// Fetch current utilization for given silo
    #[endpoint {
        method = GET,
        path = "/v1/system/utilization/silos/{silo}",
        tags = ["system/silos"],
    }]
    async fn silo_utilization_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
    ) -> Result<HttpResponseOk<views::SiloUtilization>, HttpError>;

    /// List current utilization state for all silos
    #[endpoint {
        method = GET,
        path = "/v1/system/utilization/silos",
        tags = ["system/silos"],
    }]
    async fn silo_utilization_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SiloUtilization>>, HttpError>;

    /// Lists resource quotas for all silos
    #[endpoint {
        method = GET,
        path = "/v1/system/silo-quotas",
        tags = ["system/silos"],
    }]
    async fn system_quotas_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SiloQuotas>>, HttpError>;

    /// Fetch resource quotas for silo
    #[endpoint {
        method = GET,
        path = "/v1/system/silos/{silo}/quotas",
        tags = ["system/silos"],
    }]
    async fn silo_quotas_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
    ) -> Result<HttpResponseOk<views::SiloQuotas>, HttpError>;

    /// Update resource quotas for silo
    ///
    /// If a quota value is not specified, it will remain unchanged.
    #[endpoint {
        method = PUT,
        path = "/v1/system/silos/{silo}/quotas",
        tags = ["system/silos"],
    }]
    async fn silo_quotas_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
        new_quota: TypedBody<params::SiloQuotasUpdate>,
    ) -> Result<HttpResponseOk<views::SiloQuotas>, HttpError>;

    /// List silos
    ///
    /// Lists silos that are discoverable based on the current permissions.
    #[endpoint {
        method = GET,
        path = "/v1/system/silos",
        tags = ["system/silos"],
    }]
    async fn silo_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Silo>>, HttpError>;

    /// Create silo
    #[endpoint {
        method = POST,
        path = "/v1/system/silos",
        tags = ["system/silos"],
    }]
    async fn silo_create(
        rqctx: RequestContext<Self::Context>,
        new_silo_params: TypedBody<params::SiloCreate>,
    ) -> Result<HttpResponseCreated<views::Silo>, HttpError>;

    /// Fetch silo
    ///
    /// Fetch silo by name or ID.
    #[endpoint {
        method = GET,
        path = "/v1/system/silos/{silo}",
        tags = ["system/silos"],
    }]
    async fn silo_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
    ) -> Result<HttpResponseOk<views::Silo>, HttpError>;

    /// List IP pools linked to silo
    ///
    /// Linked IP pools are available to users in the specified silo. A silo
    /// can have at most one default pool. IPs are allocated from the default
    /// pool when users ask for one without specifying a pool.
    #[endpoint {
        operation_id = "silo_ip_pool_list",
        method = GET,
        path = "/v1/system/silos/{silo}/ip-pools",
        tags = ["system/silos"],
        versions = ..VERSION_SILO_PROJECT_IP_VERSION_AND_POOL_TYPE,
    }]
    async fn v2025122300_silo_ip_pool_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<v2025122300::SiloIpPool>>, HttpError>
    {
        let page =
            Self::silo_ip_pool_list(rqctx, path_params, query_params).await?.0;
        Ok(HttpResponseOk(ResultsPage {
            items: page.items.into_iter().map(Into::into).collect(),
            next_page: page.next_page,
        }))
    }

    /// List IP pools linked to silo
    ///
    /// Linked IP pools are available to users in the specified silo. A silo
    /// can have at most one default pool. IPs are allocated from the default
    /// pool when users ask for one without specifying a pool.
    #[endpoint {
        method = GET,
        path = "/v1/system/silos/{silo}/ip-pools",
        tags = ["system/silos"],
        versions = VERSION_SILO_PROJECT_IP_VERSION_AND_POOL_TYPE..,
    }]
    async fn silo_ip_pool_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SiloIpPool>>, HttpError>;

    /// Delete silo
    ///
    /// Delete a silo by name or ID.
    #[endpoint {
        method = DELETE,
        path = "/v1/system/silos/{silo}",
        tags = ["system/silos"],
    }]
    async fn silo_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Fetch silo IAM policy
    #[endpoint {
        method = GET,
        path = "/v1/system/silos/{silo}/policy",
        tags = ["system/silos"],
    }]
    async fn silo_policy_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
    ) -> Result<HttpResponseOk<shared::Policy<shared::SiloRole>>, HttpError>;

    /// Update silo IAM policy
    #[endpoint {
        method = PUT,
        path = "/v1/system/silos/{silo}/policy",
        tags = ["system/silos"],
    }]
    async fn silo_policy_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SiloPath>,
        new_policy: TypedBody<shared::Policy<shared::SiloRole>>,
    ) -> Result<HttpResponseOk<shared::Policy<shared::SiloRole>>, HttpError>;

    // Silo-specific user endpoints

    /// List built-in (system) users in silo
    #[endpoint {
        method = GET,
        path = "/v1/system/users",
        tags = ["system/silos"],
    }]
    async fn silo_user_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById<params::SiloSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::User>>, HttpError>;

    /// Fetch built-in (system) user
    #[endpoint {
        method = GET,
        path = "/v1/system/users/{user_id}",
        tags = ["system/silos"],
    }]
    async fn silo_user_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UserParam>,
        query_params: Query<params::SiloSelector>,
    ) -> Result<HttpResponseOk<views::User>, HttpError>;

    // Silo identity providers

    /// List identity providers for silo
    ///
    /// List identity providers for silo by silo name or ID.
    #[endpoint {
        method = GET,
        path = "/v1/system/identity-providers",
        tags = ["system/silos"],
    }]
    async fn silo_identity_provider_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::SiloSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::IdentityProvider>>, HttpError>;

    // Silo SAML identity providers

    /// Create SAML identity provider
    #[endpoint {
        method = POST,
        path = "/v1/system/identity-providers/saml",
        tags = ["system/silos"],
    }]
    async fn saml_identity_provider_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::SiloSelector>,
        new_provider: TypedBody<params::SamlIdentityProviderCreate>,
    ) -> Result<HttpResponseCreated<views::SamlIdentityProvider>, HttpError>;

    /// Fetch SAML identity provider
    #[endpoint {
        method = GET,
        path = "/v1/system/identity-providers/saml/{provider}",
        tags = ["system/silos"],
    }]
    async fn saml_identity_provider_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ProviderPath>,
        query_params: Query<params::OptionalSiloSelector>,
    ) -> Result<HttpResponseOk<views::SamlIdentityProvider>, HttpError>;

    // TODO: no DELETE for identity providers?

    // "Local" Identity Provider

    /// Create user
    ///
    /// Users can only be created in Silos with `provision_type` == `Fixed`.
    /// Otherwise, Silo users are just-in-time (JIT) provisioned when a user
    /// first logs in using an external Identity Provider.
    #[endpoint {
        method = POST,
        path = "/v1/system/identity-providers/local/users",
        tags = ["system/silos"],
    }]
    async fn local_idp_user_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::SiloSelector>,
        new_user_params: TypedBody<params::UserCreate>,
    ) -> Result<HttpResponseCreated<views::User>, HttpError>;

    /// Delete user
    #[endpoint {
        method = DELETE,
        path = "/v1/system/identity-providers/local/users/{user_id}",
        tags = ["system/silos"],
    }]
    async fn local_idp_user_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UserParam>,
        query_params: Query<params::SiloSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Set or invalidate user's password
    ///
    /// Passwords can only be updated for users in Silos with identity mode
    /// `LocalOnly`.
    #[endpoint {
        method = POST,
        path = "/v1/system/identity-providers/local/users/{user_id}/set-password",
        tags = ["system/silos"],
    }]
    async fn local_idp_user_set_password(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UserParam>,
        query_params: Query<params::SiloPath>,
        update: TypedBody<params::UserPassword>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    // SAML+SCIM Identity Provider

    /// List SCIM tokens
    ///
    /// Specify the silo by name or ID using the `silo` query parameter.
    #[endpoint {
        method = GET,
        path = "/v1/system/scim/tokens",
        tags = ["system/silos"],
    }]
    async fn scim_token_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::SiloSelector>,
    ) -> Result<HttpResponseOk<Vec<views::ScimClientBearerToken>>, HttpError>;

    /// Create SCIM token
    ///
    /// Specify the silo by name or ID using the `silo` query parameter. Be sure
    /// to save the bearer token in the response. It will not be retrievable
    /// later through the token view and list endpoints.
    #[endpoint {
        method = POST,
        path = "/v1/system/scim/tokens",
        tags = ["system/silos"],
    }]
    async fn scim_token_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::SiloSelector>,
    ) -> Result<HttpResponseCreated<views::ScimClientBearerTokenValue>, HttpError>;

    /// Fetch SCIM token
    ///
    /// Specify the silo by name or ID using the `silo` query parameter.
    #[endpoint {
        method = GET,
        path = "/v1/system/scim/tokens/{token_id}",
        tags = ["system/silos"],
    }]
    async fn scim_token_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2TokenPathParam>,
        query_params: Query<params::SiloSelector>,
    ) -> Result<HttpResponseOk<views::ScimClientBearerToken>, HttpError>;

    /// Delete SCIM token
    ///
    /// Specify the silo by name or ID using the `silo` query parameter.
    #[endpoint {
        method = DELETE,
        path = "/v1/system/scim/tokens/{token_id}",
        tags = ["system/silos"],
    }]
    async fn scim_token_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2TokenPathParam>,
        query_params: Query<params::SiloSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // SCIM user endpoints
    // XXX is "silos" the correct tag?

    #[endpoint {
        method = GET,
        path = "/scim/v2/Users",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_list_users(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<scim2_rs::QueryParams>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/scim/v2/Users/{user_id}",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_get_user(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2UserPathParam>,
        query_params: Query<scim2_rs::QueryParams>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = POST,
        path = "/scim/v2/Users",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_create_user(
        rqctx: RequestContext<Self::Context>,
        body: TypedBody<scim2_rs::CreateUserRequest>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = PUT,
        path = "/scim/v2/Users/{user_id}",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_put_user(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2UserPathParam>,
        body: TypedBody<scim2_rs::CreateUserRequest>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = PATCH,
        path = "/scim/v2/Users/{user_id}",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_patch_user(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2UserPathParam>,
        body: TypedBody<scim2_rs::PatchRequest>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = DELETE,
        path = "/scim/v2/Users/{user_id}",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_delete_user(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2UserPathParam>,
    ) -> Result<Response<Body>, HttpError>;

    // SCIM group endpoints

    #[endpoint {
        method = GET,
        path = "/scim/v2/Groups",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_list_groups(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<scim2_rs::QueryParams>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/scim/v2/Groups/{group_id}",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_get_group(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2GroupPathParam>,
        query_params: Query<scim2_rs::QueryParams>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = POST,
        path = "/scim/v2/Groups",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_create_group(
        rqctx: RequestContext<Self::Context>,
        body: TypedBody<scim2_rs::CreateGroupRequest>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = PUT,
        path = "/scim/v2/Groups/{group_id}",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_put_group(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2GroupPathParam>,
        body: TypedBody<scim2_rs::CreateGroupRequest>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = PATCH,
        path = "/scim/v2/Groups/{group_id}",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_patch_group(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2GroupPathParam>,
        body: TypedBody<scim2_rs::PatchRequest>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = DELETE,
        path = "/scim/v2/Groups/{group_id}",
        tags = ["silos"],
        unpublished = true,
    }]
    async fn scim_v2_delete_group(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ScimV2GroupPathParam>,
    ) -> Result<Response<Body>, HttpError>;

    // Projects

    /// List projects
    #[endpoint {
        method = GET,
        path = "/v1/projects",
        tags = ["projects"],
    }]
    async fn project_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Project>>, HttpError>;

    /// Create project
    #[endpoint {
        method = POST,
        path = "/v1/projects",
        tags = ["projects"],
    }]
    async fn project_create(
        rqctx: RequestContext<Self::Context>,
        new_project: TypedBody<params::ProjectCreate>,
    ) -> Result<HttpResponseCreated<views::Project>, HttpError>;

    /// Fetch project
    #[endpoint {
        method = GET,
        path = "/v1/projects/{project}",
        tags = ["projects"],
    }]
    async fn project_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ProjectPath>,
    ) -> Result<HttpResponseOk<views::Project>, HttpError>;

    /// Delete project
    #[endpoint {
        method = DELETE,
        path = "/v1/projects/{project}",
        tags = ["projects"],
    }]
    async fn project_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ProjectPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // TODO-correctness: Is it valid for PUT to accept application/json that's
    // a subset of what the resource actually represents?  If not, is that a
    // problem? (HTTP may require that this be idempotent.)  If so, can we get
    // around that having this be a slightly different content-type (e.g.,
    // "application/json-patch")?  We should see what other APIs do.
    /// Update project
    #[endpoint {
        method = PUT,
        path = "/v1/projects/{project}",
        tags = ["projects"],
    }]
    async fn project_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ProjectPath>,
        updated_project: TypedBody<params::ProjectUpdate>,
    ) -> Result<HttpResponseOk<views::Project>, HttpError>;

    /// Fetch project's IAM policy
    #[endpoint {
        method = GET,
        path = "/v1/projects/{project}/policy",
        tags = ["projects"],
    }]
    async fn project_policy_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ProjectPath>,
    ) -> Result<HttpResponseOk<shared::Policy<shared::ProjectRole>>, HttpError>;

    /// Update project's IAM policy
    #[endpoint {
        method = PUT,
        path = "/v1/projects/{project}/policy",
        tags = ["projects"],
    }]
    async fn project_policy_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ProjectPath>,
        new_policy: TypedBody<shared::Policy<shared::ProjectRole>>,
    ) -> Result<HttpResponseOk<shared::Policy<shared::ProjectRole>>, HttpError>;

    // IP Pools

    /// List IP pools
    #[endpoint {
        operation_id = "project_ip_pool_list",
        method = GET,
        path = "/v1/ip-pools",
        tags = ["projects"],
        versions = ..VERSION_SILO_PROJECT_IP_VERSION_AND_POOL_TYPE,
    }]
    async fn v2025122300_project_ip_pool_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<v2025122300::SiloIpPool>>, HttpError>
    {
        let page = Self::project_ip_pool_list(rqctx, query_params).await?.0;
        Ok(HttpResponseOk(ResultsPage {
            items: page.items.into_iter().map(Into::into).collect(),
            next_page: page.next_page,
        }))
    }

    /// List IP pools
    #[endpoint {
        method = GET,
        path = "/v1/ip-pools",
        tags = ["projects"],
        versions = VERSION_SILO_PROJECT_IP_VERSION_AND_POOL_TYPE..,
    }]
    async fn project_ip_pool_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SiloIpPool>>, HttpError>;

    /// Fetch IP pool
    #[endpoint {
        operation_id = "project_ip_pool_view",
        method = GET,
        path = "/v1/ip-pools/{pool}",
        tags = ["projects"],
        versions = ..VERSION_SILO_PROJECT_IP_VERSION_AND_POOL_TYPE,
    }]
    async fn v2025122300_project_ip_pool_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
    ) -> Result<HttpResponseOk<v2025122300::SiloIpPool>, HttpError> {
        match Self::project_ip_pool_view(rqctx, path_params).await {
            Ok(HttpResponseOk(pool)) => Ok(HttpResponseOk(pool.into())),
            Err(e) => Err(e),
        }
    }

    /// Fetch IP pool
    #[endpoint {
        method = GET,
        path = "/v1/ip-pools/{pool}",
        tags = ["projects"],
        versions = VERSION_SILO_PROJECT_IP_VERSION_AND_POOL_TYPE..,
    }]
    async fn project_ip_pool_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
    ) -> Result<HttpResponseOk<views::SiloIpPool>, HttpError>;

    /// List IP pools
    #[endpoint {
        method = GET,
        path = "/v1/system/ip-pools",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::IpPool>>, HttpError>;

    /// Create IP pool
    ///
    /// IPv6 is not yet supported for unicast pools.
    #[endpoint {
        method = POST,
        path = "/v1/system/ip-pools",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_create(
        rqctx: RequestContext<Self::Context>,
        pool_params: TypedBody<params::IpPoolCreate>,
    ) -> Result<HttpResponseCreated<views::IpPool>, HttpError>;

    /// Fetch IP pool
    #[endpoint {
        method = GET,
        path = "/v1/system/ip-pools/{pool}",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
    ) -> Result<HttpResponseOk<views::IpPool>, HttpError>;

    /// Delete IP pool
    #[endpoint {
        method = DELETE,
        path = "/v1/system/ip-pools/{pool}",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Update IP pool
    #[endpoint {
        method = PUT,
        path = "/v1/system/ip-pools/{pool}",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
        updates: TypedBody<params::IpPoolUpdate>,
    ) -> Result<HttpResponseOk<views::IpPool>, HttpError>;

    /// Fetch IP pool utilization
    #[endpoint {
        method = GET,
        path = "/v1/system/ip-pools/{pool}/utilization",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_utilization_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
    ) -> Result<HttpResponseOk<views::IpPoolUtilization>, HttpError>;

    /// List IP pool's linked silos
    #[endpoint {
        method = GET,
        path = "/v1/system/ip-pools/{pool}/silos",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_silo_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
        // paginating by resource_id because they're unique per pool. most robust
        // option would be to paginate by a composite key representing the (pool,
        // resource_type, resource)
        query_params: Query<PaginatedById>,
        // TODO: this could just list views::Silo -- it's not like knowing silo_id
        // and nothing else is particularly useful -- except we also want to say
        // whether the pool is marked default on each silo. So one option would
        // be  to do the same as we did with SiloIpPool -- include is_default on
        // whatever the thing is. Still... all we'd have to do to make this usable
        // in both places would be to make it { ...IpPool, silo_id, silo_name,
        // is_default }
    ) -> Result<HttpResponseOk<ResultsPage<views::IpPoolSiloLink>>, HttpError>;

    /// Link IP pool to silo
    ///
    /// Users in linked silos can allocate external IPs from this pool for their
    /// instances. A silo can have at most one default pool. IPs are allocated
    /// from the default pool when users ask for one without specifying a pool.
    #[endpoint {
        method = POST,
        path = "/v1/system/ip-pools/{pool}/silos",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_silo_link(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
        resource_assoc: TypedBody<params::IpPoolLinkSilo>,
    ) -> Result<HttpResponseCreated<views::IpPoolSiloLink>, HttpError>;

    /// Unlink IP pool from silo
    ///
    /// Will fail if there are any outstanding IPs allocated in the silo.
    #[endpoint {
        method = DELETE,
        path = "/v1/system/ip-pools/{pool}/silos/{silo}",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_silo_unlink(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolSiloPath>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Make IP pool default for silo
    ///
    /// When a user asks for an IP (e.g., at instance create time) without
    /// specifying a pool, the IP comes from the default pool if a default is
    /// configured. When a pool is made the default for a silo, any existing
    /// default will remain linked to the silo, but will no longer be the
    /// default.
    #[endpoint {
        method = PUT,
        path = "/v1/system/ip-pools/{pool}/silos/{silo}",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_silo_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolSiloPath>,
        update: TypedBody<params::IpPoolSiloUpdate>,
    ) -> Result<HttpResponseOk<views::IpPoolSiloLink>, HttpError>;

    /// Fetch Oxide service IP pool
    #[endpoint {
        method = GET,
        path = "/v1/system/ip-pools-service",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_service_view(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<views::IpPool>, HttpError>;

    /// List ranges for IP pool
    ///
    /// Ranges are ordered by their first address.
    #[endpoint {
        method = GET,
        path = "/v1/system/ip-pools/{pool}/ranges",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_range_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
        query_params: Query<IpPoolRangePaginationParams>,
    ) -> Result<HttpResponseOk<ResultsPage<views::IpPoolRange>>, HttpError>;

    /// Add range to an IP pool
    ///
    /// IPv6 ranges are not allowed yet for unicast pools.
    ///
    /// For multicast pools, all ranges must be either Any-Source Multicast (ASM)
    /// or Source-Specific Multicast (SSM), but not both. Mixing ASM and SSM
    /// ranges in the same pool is not allowed.
    ///
    /// ASM: IPv4 addresses outside 232.0.0.0/8, IPv6 addresses with flag field != 3
    /// SSM: IPv4 addresses in 232.0.0.0/8, IPv6 addresses with flag field = 3
    #[endpoint {
        method = POST,
        path = "/v1/system/ip-pools/{pool}/ranges/add",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_range_add(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
        range_params: TypedBody<shared::IpRange>,
    ) -> Result<HttpResponseCreated<views::IpPoolRange>, HttpError>;

    /// Remove range from IP pool
    #[endpoint {
        method = POST,
        path = "/v1/system/ip-pools/{pool}/ranges/remove",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_range_remove(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
        range_params: TypedBody<shared::IpRange>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// List IP ranges for the Oxide service pool
    ///
    /// Ranges are ordered by their first address.
    #[endpoint {
        method = GET,
        path = "/v1/system/ip-pools-service/ranges",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_service_range_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<IpPoolRangePaginationParams>,
    ) -> Result<HttpResponseOk<ResultsPage<views::IpPoolRange>>, HttpError>;

    /// Add IP range to Oxide service pool
    ///
    /// IPv6 ranges are not allowed yet.
    #[endpoint {
        method = POST,
        path = "/v1/system/ip-pools-service/ranges/add",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_service_range_add(
        rqctx: RequestContext<Self::Context>,
        range_params: TypedBody<shared::IpRange>,
    ) -> Result<HttpResponseCreated<views::IpPoolRange>, HttpError>;

    /// Remove IP range from Oxide service pool
    #[endpoint {
        method = POST,
        path = "/v1/system/ip-pools-service/ranges/remove",
        tags = ["system/ip-pools"],
    }]
    async fn ip_pool_service_range_remove(
        rqctx: RequestContext<Self::Context>,
        range_params: TypedBody<shared::IpRange>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    // Subnet Pools

    /// List subnet pools
    #[endpoint {
        method = GET,
        path = "/v1/system/subnet-pools",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SubnetPool>>, HttpError>;

    /// Create a subnet pool
    #[endpoint {
        method = POST,
        path = "/v1/system/subnet-pools",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_create(
        rqctx: RequestContext<Self::Context>,
        pool_params: TypedBody<params::SubnetPoolCreate>,
    ) -> Result<HttpResponseCreated<views::SubnetPool>, HttpError>;

    /// Fetch a subnet pool
    #[endpoint {
        method = GET,
        path = "/v1/system/subnet-pools/{pool}",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
    ) -> Result<HttpResponseOk<views::SubnetPool>, HttpError>;

    /// Update a subnet pool
    #[endpoint {
        method = PUT,
        path = "/v1/system/subnet-pools/{pool}",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
        updates: TypedBody<params::SubnetPoolUpdate>,
    ) -> Result<HttpResponseOk<views::SubnetPool>, HttpError>;

    /// Delete a subnet pool
    #[endpoint {
        method = DELETE,
        path = "/v1/system/subnet-pools/{pool}",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List members in a subnet pool
    #[endpoint {
        method = GET,
        path = "/v1/system/subnet-pools/{pool}/members",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_member_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SubnetPoolMember>>, HttpError>;

    /// Add a member to a subnet pool
    #[endpoint {
        method = POST,
        path = "/v1/system/subnet-pools/{pool}/members/add",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_member_add(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
        subnet_params: TypedBody<params::SubnetPoolMemberAdd>,
    ) -> Result<HttpResponseCreated<views::SubnetPoolMember>, HttpError>;

    /// Remove a member from a subnet pool
    #[endpoint {
        method = POST,
        path = "/v1/system/subnet-pools/{pool}/members/remove",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_member_remove(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
        subnet_params: TypedBody<params::SubnetPoolMemberRemove>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// List silos linked to a subnet pool
    #[endpoint {
        method = GET,
        path = "/v1/system/subnet-pools/{pool}/silos",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_silo_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SubnetPoolSiloLink>>, HttpError>;

    /// Link a subnet pool to a silo
    #[endpoint {
        method = POST,
        path = "/v1/system/subnet-pools/{pool}/silos",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_silo_link(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
        silo_link: TypedBody<params::SubnetPoolLinkSilo>,
    ) -> Result<HttpResponseCreated<views::SubnetPoolSiloLink>, HttpError>;

    /// Update a subnet pool's link to a silo
    #[endpoint {
        method = PUT,
        path = "/v1/system/subnet-pools/{pool}/silos/{silo}",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_silo_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolSiloPath>,
        update: TypedBody<params::SubnetPoolSiloUpdate>,
    ) -> Result<HttpResponseOk<views::SubnetPoolSiloLink>, HttpError>;

    /// Unlink a subnet pool from a silo
    #[endpoint {
        method = DELETE,
        path = "/v1/system/subnet-pools/{pool}/silos/{silo}",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_silo_unlink(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolSiloPath>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Fetch subnet pool utilization
    #[endpoint {
        method = GET,
        path = "/v1/system/subnet-pools/{pool}/utilization",
        tags = ["system/subnet-pools"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn subnet_pool_utilization_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPoolPath>,
    ) -> Result<HttpResponseOk<views::SubnetPoolUtilization>, HttpError>;

    // External Subnets

    /// List external subnets in a project
    #[endpoint {
        method = GET,
        path = "/v1/external-subnets",
        tags = ["external-subnets"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn external_subnet_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::ExternalSubnet>>, HttpError>;

    /// Create an external subnet
    #[endpoint {
        method = POST,
        path = "/v1/external-subnets",
        tags = ["external-subnets"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn external_subnet_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        subnet_params: TypedBody<params::ExternalSubnetCreate>,
    ) -> Result<HttpResponseCreated<views::ExternalSubnet>, HttpError>;

    /// Fetch an external subnet
    #[endpoint {
        method = GET,
        path = "/v1/external-subnets/{external_subnet}",
        tags = ["external-subnets"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn external_subnet_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ExternalSubnetPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseOk<views::ExternalSubnet>, HttpError>;

    /// Update an external subnet
    #[endpoint {
        method = PUT,
        path = "/v1/external-subnets/{external_subnet}",
        tags = ["external-subnets"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn external_subnet_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ExternalSubnetPath>,
        query_params: Query<params::OptionalProjectSelector>,
        subnet_params: TypedBody<params::ExternalSubnetUpdate>,
    ) -> Result<HttpResponseOk<views::ExternalSubnet>, HttpError>;

    /// Delete an external subnet
    #[endpoint {
        method = DELETE,
        path = "/v1/external-subnets/{external_subnet}",
        tags = ["external-subnets"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn external_subnet_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ExternalSubnetPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Attach an external subnet to an instance
    ///
    /// Begins an asynchronous attach operation. Returns the subnet with
    /// `instance_id` set to the target instance. The attach completes
    /// asynchronously; poll the subnet to check completion.
    #[endpoint {
        method = POST,
        path = "/v1/external-subnets/{external_subnet}/attach",
        tags = ["external-subnets"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn external_subnet_attach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ExternalSubnetPath>,
        query_params: Query<params::OptionalProjectSelector>,
        attach_params: TypedBody<params::ExternalSubnetAttach>,
    ) -> Result<HttpResponseAccepted<views::ExternalSubnet>, HttpError>;

    /// Detach an external subnet from an instance
    ///
    /// Begins an asynchronous detach operation. Returns the subnet with
    /// `instance_id` cleared. The detach completes asynchronously.
    #[endpoint {
        method = POST,
        path = "/v1/external-subnets/{external_subnet}/detach",
        tags = ["external-subnets"],
        versions = VERSION_EXTERNAL_SUBNET_ATTACHMENT..,
    }]
    async fn external_subnet_detach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ExternalSubnetPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseAccepted<views::ExternalSubnet>, HttpError>;

    // Floating IP Addresses

    /// List floating IPs
    #[endpoint {
        method = GET,
        path = "/v1/floating-ips",
        tags = ["floating-ips"],
    }]
    async fn floating_ip_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::FloatingIp>>, HttpError>;

    /// Create a floating IP
    ///
    /// A specific IP address can be reserved, or an IP can be auto-allocated
    /// from a specific pool or the silo's default pool.
    #[endpoint {
        method = POST,
        path = "/v1/floating-ips",
        tags = ["floating-ips"],
        versions = VERSION_FLOATING_IP_ALLOCATOR_UPDATE..,
    }]
    async fn floating_ip_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        floating_params: TypedBody<params::FloatingIpCreate>,
    ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError>;

    /// Create floating IP
    #[endpoint {
        operation_id = "floating_ip_create",
        method = POST,
        path = "/v1/floating-ips",
        tags = ["floating-ips"],
        versions = VERSION_RENAME_ADDRESS_SELECTOR_TO_ADDRESS_ALLOCATOR..VERSION_FLOATING_IP_ALLOCATOR_UPDATE,
    }]
    async fn v2026011600_floating_ip_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        floating_params: TypedBody<v2026011600::FloatingIpCreate>,
    ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
        Self::floating_ip_create(
            rqctx,
            query_params,
            floating_params.map(Into::into),
        )
        .await
    }

    /// Create floating IP
    #[endpoint {
        operation_id = "floating_ip_create",
        method = POST,
        path = "/v1/floating-ips",
        tags = ["floating-ips"],
        versions = ..VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS,
    }]
    async fn v2025121200_floating_ip_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        floating_params: TypedBody<v2025121200::FloatingIpCreate>,
    ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
        let floating_params =
            floating_params.map(v2026010300::FloatingIpCreate::from);
        Self::v2026010300_floating_ip_create(
            rqctx,
            query_params,
            floating_params,
        )
        .await
    }

    /// Create floating IP
    #[endpoint {
        operation_id = "floating_ip_create",
        method = POST,
        path = "/v1/floating-ips",
        tags = ["floating-ips"],
        versions = VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS
            ..VERSION_POOL_SELECTION_ENUMS,
    }]
    async fn v2026010300_floating_ip_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        floating_params: TypedBody<v2026010300::FloatingIpCreate>,
    ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
        let floating_params =
            floating_params.try_map(v2026010500::FloatingIpCreate::try_from)?;
        Self::v2026010500_floating_ip_create(
            rqctx,
            query_params,
            floating_params,
        )
        .await
    }

    /// Create floating IP
    #[endpoint {
        operation_id = "floating_ip_create",
        method = POST,
        path = "/v1/floating-ips",
        tags = ["floating-ips"],
        versions = VERSION_POOL_SELECTION_ENUMS..VERSION_RENAME_ADDRESS_SELECTOR_TO_ADDRESS_ALLOCATOR,
    }]
    async fn v2026010500_floating_ip_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        floating_params: TypedBody<v2026010500::FloatingIpCreate>,
    ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
        Self::v2026011600_floating_ip_create(
            rqctx,
            query_params,
            floating_params.map(Into::into),
        )
        .await
    }

    /// Update floating IP
    #[endpoint {
        method = PUT,
        path = "/v1/floating-ips/{floating_ip}",
        tags = ["floating-ips"],
    }]
    async fn floating_ip_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::FloatingIpPath>,
        query_params: Query<params::OptionalProjectSelector>,
        updated_floating_ip: TypedBody<params::FloatingIpUpdate>,
    ) -> Result<HttpResponseOk<views::FloatingIp>, HttpError>;

    /// Delete floating IP
    #[endpoint {
        method = DELETE,
        path = "/v1/floating-ips/{floating_ip}",
        tags = ["floating-ips"],
    }]
    async fn floating_ip_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::FloatingIpPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Fetch floating IP
    #[endpoint {
        method = GET,
        path = "/v1/floating-ips/{floating_ip}",
        tags = ["floating-ips"]
    }]
    async fn floating_ip_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::FloatingIpPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseOk<views::FloatingIp>, HttpError>;

    /// Attach floating IP
    ///
    /// Attach floating IP to an instance or other resource.
    #[endpoint {
        method = POST,
        path = "/v1/floating-ips/{floating_ip}/attach",
        tags = ["floating-ips"],
    }]
    async fn floating_ip_attach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::FloatingIpPath>,
        query_params: Query<params::OptionalProjectSelector>,
        target: TypedBody<params::FloatingIpAttach>,
    ) -> Result<HttpResponseAccepted<views::FloatingIp>, HttpError>;

    /// Detach floating IP
    ///
    // Detach floating IP from instance or other resource.
    #[endpoint {
        method = POST,
        path = "/v1/floating-ips/{floating_ip}/detach",
        tags = ["floating-ips"],
    }]
    async fn floating_ip_detach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::FloatingIpPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseAccepted<views::FloatingIp>, HttpError>;

    // Multicast Groups
    //
    // TODO: Consider adding `.map()` to dropshot's `Path<T>` (like `TypedBody`)
    // to enable inline delegation when path types differ between API versions.

    /// List multicast groups
    #[endpoint {
        method = GET,
        path = "/v1/multicast-groups",
        tags = ["experimental"],
        operation_id = "multicast_group_list",
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_multicast_group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<
        HttpResponseOk<ResultsPage<v2025121200::MulticastGroup>>,
        HttpError,
    > {
        match Self::multicast_group_list(rqctx, query_params).await {
            Ok(HttpResponseOk(page)) => Ok(HttpResponseOk(ResultsPage {
                items: page.items.into_iter().map(|g| g.into()).collect(),
                next_page: page.next_page,
            })),
            Err(e) => Err(e),
        }
    }

    /// List multicast groups
    #[endpoint {
        method = GET,
        path = "/v1/multicast-groups",
        tags = ["experimental"],
        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
    }]
    async fn multicast_group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::MulticastGroup>>, HttpError>;

    /// Create a multicast group
    ///
    /// Deprecated: Groups are created implicitly when adding members in newer
    /// API versions.
    #[endpoint {
        method = POST,
        path = "/v1/multicast-groups",
        tags = ["experimental"],
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_multicast_group_create(
        _rqctx: RequestContext<Self::Context>,
        _new_group: TypedBody<v2025121200::MulticastGroupCreate>,
    ) -> Result<HttpResponseCreated<v2025121200::MulticastGroup>, HttpError>
    {
        Err(HttpError::for_client_error(
            None,
            dropshot::ClientErrorStatusCode::GONE,
            "multicast group creation is deprecated; groups are created \
             implicitly when instances join via: \
             PUT /v1/instances/{instance}/multicast-groups/{group}"
                .to_string(),
        ))
    }

    /// Fetch a multicast group
    ///
    /// The group can be specified by name or UUID.
    #[endpoint {
        method = GET,
        path = "/v1/multicast-groups/{multicast_group}",
        tags = ["experimental"],
        operation_id = "multicast_group_view",
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    // Cannot delegate inline: path types differ (NameOrId vs MulticastGroupIdentifier)
    // and can't construct Path<T> (Dropshot extractor with private fields).
    async fn v2025121200_multicast_group_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<v2025121200::MulticastGroupPath>,
    ) -> Result<HttpResponseOk<v2025121200::MulticastGroup>, HttpError>;

    /// Fetch multicast group
    ///
    /// The group can be specified by name, UUID, or multicast IP address.
    /// (e.g., "224.1.2.3" or "ff38::1").
    #[endpoint {
        method = GET,
        path = "/v1/multicast-groups/{multicast_group}",
        tags = ["experimental"],
        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
    }]
    async fn multicast_group_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::MulticastGroupPath>,
    ) -> Result<HttpResponseOk<views::MulticastGroup>, HttpError>;

    /// Update a multicast group
    ///
    /// Deprecated: groups are managed implicitly through member operations.
    #[endpoint {
        method = PUT,
        path = "/v1/multicast-groups/{multicast_group}",
        tags = ["experimental"],
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_multicast_group_update(
        _rqctx: RequestContext<Self::Context>,
        _path_params: Path<v2025121200::MulticastGroupPath>,
        _update_params: TypedBody<v2025121200::MulticastGroupUpdate>,
    ) -> Result<HttpResponseOk<v2025121200::MulticastGroup>, HttpError> {
        Err(HttpError::for_client_error(
            None,
            dropshot::ClientErrorStatusCode::GONE,
            "multicast group update is deprecated; groups are managed \
             implicitly through member operations"
                .to_string(),
        ))
    }

    /// Delete multicast group
    ///
    /// Deprecated: groups are deleted automatically when the last member leaves.
    #[endpoint {
        method = DELETE,
        path = "/v1/multicast-groups/{multicast_group}",
        tags = ["experimental"],
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_multicast_group_delete(
        _rqctx: RequestContext<Self::Context>,
        _path_params: Path<v2025121200::MulticastGroupPath>,
    ) -> Result<HttpResponseDeleted, HttpError> {
        Err(HttpError::for_client_error(
            None,
            dropshot::ClientErrorStatusCode::GONE,
            "multicast group deletion is deprecated; groups are \
             automatically deleted when all members leave"
                .to_string(),
        ))
    }

    /// List members of multicast group
    ///
    /// The group can be specified by name or UUID.
    #[endpoint {
        method = GET,
        path = "/v1/multicast-groups/{multicast_group}/members",
        tags = ["experimental"],
        operation_id = "multicast_group_member_list",
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    // Cannot delegate inline: path types differ (NameOrId vs MulticastGroupIdentifier)
    // and can't construct Path<T> (Dropshot extractor with private fields).
    async fn v2025121200_multicast_group_member_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<v2025121200::MulticastGroupPath>,
        query_params: Query<PaginatedById>,
    ) -> Result<
        HttpResponseOk<ResultsPage<v2025121200::MulticastGroupMember>>,
        HttpError,
    >;

    /// List members of multicast group
    ///
    /// The group can be specified by name, UUID, or multicast IP address.
    #[endpoint {
        method = GET,
        path = "/v1/multicast-groups/{multicast_group}/members",
        tags = ["experimental"],
        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
    }]
    async fn multicast_group_member_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::MulticastGroupPath>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<MulticastGroupMember>>, HttpError>;

    /// Add instance to multicast group
    ///
    /// Deprecated: use the instance join endpoint which supports implicit group
    /// creation and accepts group by name, UUID, or IP address.
    #[endpoint {
        method = POST,
        path = "/v1/multicast-groups/{multicast_group}/members",
        tags = ["experimental"],
        operation_id = "multicast_group_member_add",
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_multicast_group_member_add(
        _rqctx: RequestContext<Self::Context>,
        _path_params: Path<v2025121200::MulticastGroupPath>,
        _query_params: Query<params::OptionalProjectSelector>,
        _member_params: TypedBody<v2025121200::MulticastGroupMemberAdd>,
    ) -> Result<HttpResponseCreated<v2025121200::MulticastGroupMember>, HttpError>
    {
        Err(HttpError::for_client_error(
            None,
            dropshot::ClientErrorStatusCode::GONE,
            "multicast group member add is deprecated; use the instance \
             join endpoint: PUT /v1/instances/{instance}/multicast-groups/{group}"
                .to_string(),
        ))
    }

    /// Remove instance from multicast group
    ///
    /// Deprecated: use the instance leave endpoint which accepts group by name,
    /// UUID, or IP address.
    #[endpoint {
        method = DELETE,
        path = "/v1/multicast-groups/{multicast_group}/members/{instance}",
        tags = ["experimental"],
        operation_id = "multicast_group_member_remove",
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_multicast_group_member_remove(
        _rqctx: RequestContext<Self::Context>,
        _path_params: Path<v2025121200::MulticastGroupMemberPath>,
        _query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError> {
        Err(HttpError::for_client_error(
            None,
            dropshot::ClientErrorStatusCode::GONE,
            "multicast group member remove is deprecated; use the instance \
             leave endpoint: DELETE /v1/instances/{instance}/multicast-groups/{group}"
                .to_string(),
        ))
    }

    /// Look up multicast group by IP address
    ///
    /// Deprecated: use the main view endpoint which accepts IP addresses directly.
    #[endpoint {
        method = GET,
        path = "/v1/system/multicast-groups/by-ip/{address}",
        tags = ["experimental"],
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_lookup_multicast_group_by_ip(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<v2025121200::MulticastGroupByIpPath>,
    ) -> Result<HttpResponseOk<v2025121200::MulticastGroup>, HttpError>;

    // Disks

    /// List disks
    #[endpoint {
        operation_id = "disk_list",
        method = GET,
        path = "/v1/disks",
        tags = ["disks"],
        versions = ..VERSION_LOCAL_STORAGE,
    }]
    async fn v2025112000_disk_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<v2025112000::Disk>>, HttpError> {
        match Self::disk_list(rqctx, query_params).await {
            Ok(page) => {
                let new_page = ResultsPage {
                    next_page: page.0.next_page,
                    items: {
                        let mut items = Vec::with_capacity(page.0.items.len());
                        for item in page.0.items {
                            items.push(item.try_into()?);
                        }
                        items
                    },
                };

                Ok(HttpResponseOk(new_page))
            }
            Err(e) => Err(e),
        }
    }

    /// List disks
    #[endpoint {
        method = GET,
        path = "/v1/disks",
        tags = ["disks"],
        versions = VERSION_LOCAL_STORAGE..,
    }]
    async fn disk_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<Disk>>, HttpError>;

    // TODO-correctness See note about instance create.  This should be async.
    /// Create a disk
    #[endpoint {
        operation_id = "disk_create",
        method = POST,
        path = "/v1/disks",
        tags = ["disks"],
        versions = ..VERSION_LOCAL_STORAGE,
    }]
    async fn v2025112000_disk_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_disk: TypedBody<v2025112000::DiskCreate>,
    ) -> Result<HttpResponseCreated<v2025112000::Disk>, HttpError> {
        match Self::disk_create(rqctx, query_params, new_disk.map(Into::into))
            .await
        {
            Ok(HttpResponseCreated(disk)) => {
                Ok(HttpResponseCreated(disk.try_into()?))
            }
            Err(e) => Err(e),
        }
    }

    // TODO-correctness See note about instance create.  This should be async.
    /// Create disk
    #[endpoint {
        method = POST,
        path = "/v1/disks",
        tags = ["disks"],
        versions = VERSION_LOCAL_STORAGE..,
    }]
    async fn disk_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_disk: TypedBody<params::DiskCreate>,
    ) -> Result<HttpResponseCreated<Disk>, HttpError>;

    /// Fetch disk
    #[endpoint {
        operation_id = "disk_view",
        method = GET,
        path = "/v1/disks/{disk}",
        tags = ["disks"],
        versions = ..VERSION_LOCAL_STORAGE,
    }]
    async fn v2025112000_disk_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::DiskPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseOk<v2025112000::Disk>, HttpError> {
        match Self::disk_view(rqctx, path_params, query_params).await {
            Ok(HttpResponseOk(disk)) => Ok(HttpResponseOk(disk.try_into()?)),
            Err(e) => Err(e),
        }
    }

    /// Fetch disk
    #[endpoint {
        method = GET,
        path = "/v1/disks/{disk}",
        tags = ["disks"],
        versions = VERSION_LOCAL_STORAGE..,
    }]
    async fn disk_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::DiskPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseOk<Disk>, HttpError>;

    /// Delete disk
    #[endpoint {
        method = DELETE,
        path = "/v1/disks/{disk}",
        tags = ["disks"],
    }]
    async fn disk_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::DiskPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Start importing blocks into disk
    ///
    /// Start the process of importing blocks into a disk
    #[endpoint {
        method = POST,
        path = "/v1/disks/{disk}/bulk-write-start",
        tags = ["disks"],
    }]
    async fn disk_bulk_write_import_start(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::DiskPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Import blocks into disk
    #[endpoint {
        method = POST,
        path = "/v1/disks/{disk}/bulk-write",
        tags = ["disks"],
        request_body_max_bytes = DISK_BULK_WRITE_MAX_BYTES,
    }]
    async fn disk_bulk_write_import(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::DiskPath>,
        query_params: Query<params::OptionalProjectSelector>,
        import_params: TypedBody<params::ImportBlocksBulkWrite>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Stop importing blocks into disk
    ///
    /// Stop the process of importing blocks into a disk
    #[endpoint {
        method = POST,
        path = "/v1/disks/{disk}/bulk-write-stop",
        tags = ["disks"],
    }]
    async fn disk_bulk_write_import_stop(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::DiskPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Confirm disk block import completion
    #[endpoint {
        method = POST,
        path = "/v1/disks/{disk}/finalize",
        tags = ["disks"],
    }]
    async fn disk_finalize_import(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::DiskPath>,
        query_params: Query<params::OptionalProjectSelector>,
        finalize_params: TypedBody<params::FinalizeDisk>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    // Instances

    /// List instances
    #[endpoint {
        method = GET,
        path = "/v1/instances",
        tags = ["instances"],
    }]
    async fn instance_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<Instance>>, HttpError>;

    /// Create instance
    #[endpoint {
        method = POST,
        path = "/v1/instances",
        tags = ["instances"],
        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
    }]
    async fn instance_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_instance: TypedBody<params::InstanceCreate>,
    ) -> Result<HttpResponseCreated<Instance>, HttpError>;

    /// Create instance
    #[endpoint {
        operation_id = "instance_create",
        method = POST,
        path = "/v1/instances",
        tags = ["instances"],
        versions = VERSION_POOL_SELECTION_ENUMS..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2026010500_instance_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_instance: TypedBody<v2026010500::InstanceCreate>,
    ) -> Result<HttpResponseCreated<Instance>, HttpError> {
        Self::instance_create(rqctx, query_params, new_instance.map(Into::into))
            .await
    }

    /// Create instance
    #[endpoint {
        operation_id = "instance_create",
        method = POST,
        path = "/v1/instances",
        tags = ["instances"],
        versions = VERSION_DUAL_STACK_NICS..VERSION_POOL_SELECTION_ENUMS,
    }]
    async fn v2026010300_instance_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_instance: TypedBody<v2026010300::InstanceCreate>,
    ) -> Result<HttpResponseCreated<Instance>, HttpError> {
        Self::v2026010500_instance_create(
            rqctx,
            query_params,
            new_instance.try_map(TryInto::try_into)?,
        )
        .await
    }

    /// Create instance
    #[endpoint {
        operation_id = "instance_create",
        method = POST,
        path = "/v1/instances",
        tags = ["instances"],
        versions =
            VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS..VERSION_DUAL_STACK_NICS,
    }]
    async fn v2025122300_instance_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_instance: TypedBody<v2025122300::InstanceCreate>,
    ) -> Result<HttpResponseCreated<Instance>, HttpError> {
        Self::v2026010300_instance_create(
            rqctx,
            query_params,
            new_instance.try_map(TryInto::try_into)?,
        )
        .await
    }

    /// Create instance
    #[endpoint {
        operation_id = "instance_create",
        method = POST,
        path = "/v1/instances",
        tags = ["instances"],
        versions = VERSION_LOCAL_STORAGE..VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS,
    }]
    async fn v2025120300_instance_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_instance: TypedBody<v2025120300::InstanceCreate>,
    ) -> Result<HttpResponseCreated<Instance>, HttpError> {
        Self::v2025122300_instance_create(
            rqctx,
            query_params,
            new_instance.map(Into::into),
        )
        .await
    }

    /// Create instance
    #[endpoint {
        operation_id = "instance_create",
        method = POST,
        path = "/v1/instances",
        tags = ["instances"],
        versions = ..VERSION_LOCAL_STORAGE,
    }]
    async fn v2025112000_instance_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_instance: TypedBody<v2025112000::InstanceCreate>,
    ) -> Result<HttpResponseCreated<Instance>, HttpError> {
        Self::v2025120300_instance_create(
            rqctx,
            query_params,
            new_instance.map(Into::into),
        )
        .await
    }

    /// Fetch instance
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}",
        tags = ["instances"],
    }]
    async fn instance_view(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseOk<Instance>, HttpError>;

    /// Delete instance
    #[endpoint {
        method = DELETE,
        path = "/v1/instances/{instance}",
        tags = ["instances"],
    }]
    async fn instance_delete(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Update instance
    #[endpoint {
        method = PUT,
        path = "/v1/instances/{instance}",
        tags = ["instances"],
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025120300_instance_update(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::InstancePath>,
        instance_config: TypedBody<v2025121200::InstanceUpdate>,
    ) -> Result<HttpResponseOk<Instance>, HttpError> {
        Self::instance_update(
            rqctx,
            query_params,
            path_params,
            instance_config.map(Into::into),
        )
        .await
    }

    /// Update instance
    #[endpoint {
        method = PUT,
        path = "/v1/instances/{instance}",
        tags = ["instances"],
        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
    }]
    async fn instance_update(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::InstancePath>,
        instance_config: TypedBody<params::InstanceUpdate>,
    ) -> Result<HttpResponseOk<Instance>, HttpError>;

    /// Reboot instance
    #[endpoint {
        method = POST,
        path = "/v1/instances/{instance}/reboot",
        tags = ["instances"],
    }]
    async fn instance_reboot(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseAccepted<Instance>, HttpError>;

    /// Boot instance
    #[endpoint {
        method = POST,
        path = "/v1/instances/{instance}/start",
        tags = ["instances"],
    }]
    async fn instance_start(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseAccepted<Instance>, HttpError>;

    /// Stop instance
    #[endpoint {
        method = POST,
        path = "/v1/instances/{instance}/stop",
        tags = ["instances"],
    }]
    async fn instance_stop(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseAccepted<Instance>, HttpError>;

    /// Fetch instance serial console
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}/serial-console",
        tags = ["instances"],
    }]
    async fn instance_serial_console(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::InstanceSerialConsoleRequest>,
    ) -> Result<HttpResponseOk<params::InstanceSerialConsoleData>, HttpError>;

    /// Stream instance serial console
    #[channel {
        protocol = WEBSOCKETS,
        path = "/v1/instances/{instance}/serial-console/stream",
        tags = ["instances"],
    }]
    async fn instance_serial_console_stream(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::InstanceSerialConsoleStreamRequest>,
        conn: WebsocketConnection,
    ) -> WebsocketChannelResult;

    /// List SSH public keys for instance
    ///
    /// List SSH public keys injected via cloud-init during instance creation.
    /// Note that this list is a snapshot in time and will not reflect updates
    /// made after the instance is created.
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}/ssh-public-keys",
        tags = ["instances"],
    }]
    async fn instance_ssh_public_key_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<
            PaginatedByNameOrId<params::OptionalProjectSelector>,
        >,
    ) -> Result<HttpResponseOk<ResultsPage<views::SshKey>>, HttpError>;

    /// List disks for instance
    #[endpoint {
        operation_id = "instance_disk_list",
        method = GET,
        path = "/v1/instances/{instance}/disks",
        tags = ["instances"],
        versions = ..VERSION_LOCAL_STORAGE,
    }]
    async fn v2025112000_instance_disk_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::OptionalProjectSelector>,
        >,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseOk<ResultsPage<v2025112000::Disk>>, HttpError> {
        match Self::instance_disk_list(rqctx, query_params, path_params).await {
            Ok(page) => {
                let page = ResultsPage {
                    next_page: page.0.next_page,
                    items: {
                        let mut items = Vec::with_capacity(page.0.items.len());
                        for item in page.0.items {
                            items.push(item.try_into()?);
                        }
                        items
                    },
                };

                Ok(HttpResponseOk(page))
            }

            Err(e) => Err(e),
        }
    }

    /// List disks for instance
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}/disks",
        tags = ["instances"],
        versions = VERSION_LOCAL_STORAGE..,
    }]
    async fn instance_disk_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::OptionalProjectSelector>,
        >,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseOk<ResultsPage<Disk>>, HttpError>;

    /// Attach disk to instance
    #[endpoint {
        operation_id = "instance_disk_attach",
        method = POST,
        path = "/v1/instances/{instance}/disks/attach",
        tags = ["instances"],
        versions = ..VERSION_LOCAL_STORAGE,
    }]
    async fn v2025112000_instance_disk_attach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::OptionalProjectSelector>,
        disk_to_attach: TypedBody<params::DiskPath>,
    ) -> Result<HttpResponseAccepted<v2025112000::Disk>, HttpError> {
        match Self::instance_disk_attach(
            rqctx,
            path_params,
            query_params,
            disk_to_attach,
        )
        .await
        {
            Ok(HttpResponseAccepted(disk)) => {
                Ok(HttpResponseAccepted(disk.try_into()?))
            }

            Err(e) => Err(e),
        }
    }

    /// Attach disk to instance
    #[endpoint {
        method = POST,
        path = "/v1/instances/{instance}/disks/attach",
        tags = ["instances"],
        versions = VERSION_LOCAL_STORAGE..,
    }]
    async fn instance_disk_attach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::OptionalProjectSelector>,
        disk_to_attach: TypedBody<params::DiskPath>,
    ) -> Result<HttpResponseAccepted<Disk>, HttpError>;

    /// Detach disk from instance
    #[endpoint {
        operation_id = "instance_disk_detach",
        method = POST,
        path = "/v1/instances/{instance}/disks/detach",
        tags = ["instances"],
        versions = ..VERSION_LOCAL_STORAGE,
    }]
    async fn v2025112000_instance_disk_detach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::OptionalProjectSelector>,
        disk_to_detach: TypedBody<params::DiskPath>,
    ) -> Result<HttpResponseAccepted<v2025112000::Disk>, HttpError> {
        match Self::instance_disk_detach(
            rqctx,
            path_params,
            query_params,
            disk_to_detach,
        )
        .await
        {
            Ok(HttpResponseAccepted(disk)) => {
                Ok(HttpResponseAccepted(disk.try_into()?))
            }

            Err(e) => Err(e),
        }
    }

    /// Detach disk from instance
    #[endpoint {
        method = POST,
        path = "/v1/instances/{instance}/disks/detach",
        tags = ["instances"],
        versions = VERSION_LOCAL_STORAGE..,
    }]
    async fn instance_disk_detach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::OptionalProjectSelector>,
        disk_to_detach: TypedBody<params::DiskPath>,
    ) -> Result<HttpResponseAccepted<Disk>, HttpError>;

    /// List affinity groups containing instance
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}/affinity-groups",
        tags = ["experimental"],
    }]
    async fn instance_affinity_group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::OptionalProjectSelector>,
        >,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseOk<ResultsPage<views::AffinityGroup>>, HttpError>;

    /// List anti-affinity groups containing instance
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}/anti-affinity-groups",
        tags = ["instances"],
    }]
    async fn instance_anti_affinity_group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::OptionalProjectSelector>,
        >,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseOk<ResultsPage<views::AntiAffinityGroup>>, HttpError>;

    // Affinity Groups

    /// List affinity groups
    #[endpoint {
        method = GET,
        path = "/v1/affinity-groups",
        tags = ["experimental"],
    }]
    async fn affinity_group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::AffinityGroup>>, HttpError>;

    /// Fetch affinity group
    #[endpoint {
        method = GET,
        path = "/v1/affinity-groups/{affinity_group}",
        tags = ["experimental"],
    }]
    async fn affinity_group_view(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AffinityGroupPath>,
    ) -> Result<HttpResponseOk<views::AffinityGroup>, HttpError>;

    /// List affinity group members
    #[endpoint {
        method = GET,
        path = "/v1/affinity-groups/{affinity_group}/members",
        tags = ["experimental"],
    }]
    async fn affinity_group_member_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::OptionalProjectSelector>,
        >,
        path_params: Path<params::AffinityGroupPath>,
    ) -> Result<HttpResponseOk<ResultsPage<AffinityGroupMember>>, HttpError>;

    /// Fetch affinity group member
    #[endpoint {
        method = GET,
        path = "/v1/affinity-groups/{affinity_group}/members/instance/{instance}",
        tags = ["experimental"],
    }]
    async fn affinity_group_member_instance_view(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AffinityInstanceGroupMemberPath>,
    ) -> Result<HttpResponseOk<AffinityGroupMember>, HttpError>;

    /// Add member to affinity group
    #[endpoint {
        method = POST,
        path = "/v1/affinity-groups/{affinity_group}/members/instance/{instance}",
        tags = ["experimental"],
    }]
    async fn affinity_group_member_instance_add(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AffinityInstanceGroupMemberPath>,
    ) -> Result<HttpResponseCreated<AffinityGroupMember>, HttpError>;

    /// Remove member from affinity group
    #[endpoint {
        method = DELETE,
        path = "/v1/affinity-groups/{affinity_group}/members/instance/{instance}",
        tags = ["experimental"],
    }]
    async fn affinity_group_member_instance_delete(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AffinityInstanceGroupMemberPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Create affinity group
    #[endpoint {
        method = POST,
        path = "/v1/affinity-groups",
        tags = ["experimental"],
    }]
    async fn affinity_group_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_affinity_group_params: TypedBody<params::AffinityGroupCreate>,
    ) -> Result<HttpResponseCreated<views::AffinityGroup>, HttpError>;

    /// Update affinity group
    #[endpoint {
        method = PUT,
        path = "/v1/affinity-groups/{affinity_group}",
        tags = ["experimental"],
    }]
    async fn affinity_group_update(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AffinityGroupPath>,
        updated_group: TypedBody<params::AffinityGroupUpdate>,
    ) -> Result<HttpResponseOk<views::AffinityGroup>, HttpError>;

    /// Delete affinity group
    #[endpoint {
        method = DELETE,
        path = "/v1/affinity-groups/{affinity_group}",
        tags = ["experimental"],
    }]
    async fn affinity_group_delete(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AffinityGroupPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List anti-affinity groups
    #[endpoint {
        method = GET,
        path = "/v1/anti-affinity-groups",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::AntiAffinityGroup>>, HttpError>;

    /// Fetch anti-affinity group
    #[endpoint {
        method = GET,
        path = "/v1/anti-affinity-groups/{anti_affinity_group}",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_view(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AntiAffinityGroupPath>,
    ) -> Result<HttpResponseOk<views::AntiAffinityGroup>, HttpError>;

    /// List anti-affinity group members
    #[endpoint {
        method = GET,
        path = "/v1/anti-affinity-groups/{anti_affinity_group}/members",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_member_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::OptionalProjectSelector>,
        >,
        path_params: Path<params::AntiAffinityGroupPath>,
    ) -> Result<HttpResponseOk<ResultsPage<AntiAffinityGroupMember>>, HttpError>;

    /// Fetch anti-affinity group member
    #[endpoint {
        method = GET,
        path = "/v1/anti-affinity-groups/{anti_affinity_group}/members/instance/{instance}",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_member_instance_view(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AntiAffinityInstanceGroupMemberPath>,
    ) -> Result<HttpResponseOk<AntiAffinityGroupMember>, HttpError>;

    /// Add member to anti-affinity group
    #[endpoint {
        method = POST,
        path = "/v1/anti-affinity-groups/{anti_affinity_group}/members/instance/{instance}",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_member_instance_add(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AntiAffinityInstanceGroupMemberPath>,
    ) -> Result<HttpResponseCreated<AntiAffinityGroupMember>, HttpError>;

    /// Remove member from anti-affinity group
    #[endpoint {
        method = DELETE,
        path = "/v1/anti-affinity-groups/{anti_affinity_group}/members/instance/{instance}",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_member_instance_delete(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AntiAffinityInstanceGroupMemberPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Create anti-affinity group
    #[endpoint {
        method = POST,
        path = "/v1/anti-affinity-groups",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_affinity_group_params: TypedBody<params::AntiAffinityGroupCreate>,
    ) -> Result<HttpResponseCreated<views::AntiAffinityGroup>, HttpError>;

    /// Update anti-affinity group
    #[endpoint {
        method = PUT,
        path = "/v1/anti-affinity-groups/{anti_affinity_group}",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_update(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AntiAffinityGroupPath>,
        updated_group: TypedBody<params::AntiAffinityGroupUpdate>,
    ) -> Result<HttpResponseOk<views::AntiAffinityGroup>, HttpError>;

    /// Delete anti-affinity group
    #[endpoint {
        method = DELETE,
        path = "/v1/anti-affinity-groups/{anti_affinity_group}",
        tags = ["affinity"],
    }]
    async fn anti_affinity_group_delete(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::AntiAffinityGroupPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // Certificates

    /// List certificates for external endpoints
    ///
    /// Returns a list of TLS certificates used for the external API (for the
    /// current Silo).  These are sorted by creation date, with the most recent
    /// certificates appearing first.
    #[endpoint {
        method = GET,
        path = "/v1/certificates",
        tags = ["silos"],
    }]
    async fn certificate_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Certificate>>, HttpError>;

    /// Create new system-wide x.509 certificate
    ///
    /// This certificate is automatically used by the Oxide Control plane to serve
    /// external connections.
    #[endpoint {
        method = POST,
        path = "/v1/certificates",
        tags = ["silos"]
    }]
    async fn certificate_create(
        rqctx: RequestContext<Self::Context>,
        new_cert: TypedBody<params::CertificateCreate>,
    ) -> Result<HttpResponseCreated<views::Certificate>, HttpError>;

    /// Fetch certificate
    ///
    /// Returns the details of a specific certificate
    #[endpoint {
        method = GET,
        path = "/v1/certificates/{certificate}",
        tags = ["silos"],
    }]
    async fn certificate_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::CertificatePath>,
    ) -> Result<HttpResponseOk<views::Certificate>, HttpError>;

    /// Delete certificate
    ///
    /// Permanently delete a certificate. This operation cannot be undone.
    #[endpoint {
        method = DELETE,
        path = "/v1/certificates/{certificate}",
        tags = ["silos"],
    }]
    async fn certificate_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::CertificatePath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Create address lot
    #[endpoint {
        method = POST,
        path = "/v1/system/networking/address-lot",
        tags = ["system/networking"],
    }]
    async fn networking_address_lot_create(
        rqctx: RequestContext<Self::Context>,
        new_address_lot: TypedBody<params::AddressLotCreate>,
    ) -> Result<HttpResponseCreated<AddressLotCreateResponse>, HttpError>;

    /// Delete address lot
    #[endpoint {
        method = DELETE,
        path = "/v1/system/networking/address-lot/{address_lot}",
        tags = ["system/networking"],
    }]
    async fn networking_address_lot_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AddressLotPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List address lots
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/address-lot",
        tags = ["system/networking"],
    }]
    async fn networking_address_lot_list(
        rqctx: RequestContext<Self::Context>,
        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,
        path = "/v1/system/networking/address-lot/{address_lot}/blocks",
        tags = ["system/networking"],
    }]
    async fn networking_address_lot_block_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AddressLotPath>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<AddressLotBlock>>, HttpError>;

    /// Create loopback address
    #[endpoint {
        method = POST,
        path = "/v1/system/networking/loopback-address",
        tags = ["system/networking"],
    }]
    async fn networking_loopback_address_create(
        rqctx: RequestContext<Self::Context>,
        new_loopback_address: TypedBody<params::LoopbackAddressCreate>,
    ) -> Result<HttpResponseCreated<LoopbackAddress>, HttpError>;

    /// Delete loopback address
    #[endpoint {
        method = DELETE,
        path = "/v1/system/networking/loopback-address/{rack_id}/{switch_location}/{address}/{subnet_mask}",
        tags = ["system/networking"],
    }]
    async fn networking_loopback_address_delete(
        rqctx: RequestContext<Self::Context>,
        path: Path<params::LoopbackAddressPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List loopback addresses
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/loopback-address",
        tags = ["system/networking"],
    }]
    async fn networking_loopback_address_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<LoopbackAddress>>, HttpError>;

    /// Create switch port settings
    #[endpoint {
        method = POST,
        path = "/v1/system/networking/switch-port-settings",
        tags = ["system/networking"],
    }]
    async fn networking_switch_port_settings_create(
        rqctx: RequestContext<Self::Context>,
        new_settings: TypedBody<params::SwitchPortSettingsCreate>,
    ) -> Result<HttpResponseCreated<SwitchPortSettings>, HttpError>;

    /// Delete switch port settings
    #[endpoint {
        method = DELETE,
        path = "/v1/system/networking/switch-port-settings",
        tags = ["system/networking"],
    }]
    async fn networking_switch_port_settings_delete(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::SwitchPortSettingsSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List switch port settings
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/switch-port-settings",
        tags = ["system/networking"],
    }]
    async fn networking_switch_port_settings_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::SwitchPortSettingsSelector>,
        >,
    ) -> Result<
        HttpResponseOk<ResultsPage<SwitchPortSettingsIdentity>>,
        HttpError,
    >;

    /// Get information about switch port
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/switch-port-settings/{port}",
        tags = ["system/networking"],
    }]
    async fn networking_switch_port_settings_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SwitchPortSettingsInfoSelector>,
    ) -> Result<HttpResponseOk<SwitchPortSettings>, HttpError>;

    /// List switch ports
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/switch-port",
        tags = ["system/hardware"],
    }]
    async fn networking_switch_port_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById<params::SwitchPortPageSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<SwitchPort>>, HttpError>;

    /// Get switch port status
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/switch-port/{port}/status",
        tags = ["system/hardware"],
    }]
    async fn networking_switch_port_status(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SwitchPortPathSelector>,
        query_params: Query<params::SwitchPortSelector>,
    ) -> Result<HttpResponseOk<shared::SwitchLinkState>, HttpError>;

    /// Apply switch port settings
    #[endpoint {
        method = POST,
        path = "/v1/system/hardware/switch-port/{port}/settings",
        tags = ["system/hardware"],
    }]
    async fn networking_switch_port_apply_settings(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SwitchPortPathSelector>,
        query_params: Query<params::SwitchPortSelector>,
        settings_body: TypedBody<params::SwitchPortApplySettings>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Clear switch port settings
    #[endpoint {
        method = DELETE,
        path = "/v1/system/hardware/switch-port/{port}/settings",
        tags = ["system/hardware"],
    }]
    async fn networking_switch_port_clear_settings(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SwitchPortPathSelector>,
        query_params: Query<params::SwitchPortSelector>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Fetch the LLDP configuration for a switch port
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/switch-port/{port}/lldp/config",
        tags = ["system/networking"],
    }]
    async fn networking_switch_port_lldp_config_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SwitchPortPathSelector>,
        query_params: Query<params::SwitchPortSelector>,
    ) -> Result<HttpResponseOk<LldpLinkConfig>, HttpError>;

    /// Update the LLDP configuration for a switch port
    #[endpoint {
        method = POST,
        path = "/v1/system/hardware/switch-port/{port}/lldp/config",
        tags = ["system/networking"],
    }]
    async fn networking_switch_port_lldp_config_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SwitchPortPathSelector>,
        query_params: Query<params::SwitchPortSelector>,
        config: TypedBody<LldpLinkConfig>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Fetch the LLDP neighbors seen on a switch port
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/rack-switch-port/{rack_id}/{switch_location}/{port}/lldp/neighbors",
        tags = ["system/networking"],
    }]
    async fn networking_switch_port_lldp_neighbors(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::LldpPortPathSelector>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<LldpNeighbor>>, HttpError>;

    /// Create new BGP configuration
    #[endpoint {
        method = POST,
        path = "/v1/system/networking/bgp",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_config_create(
        rqctx: RequestContext<Self::Context>,
        config: TypedBody<params::BgpConfigCreate>,
    ) -> Result<HttpResponseCreated<BgpConfig>, HttpError>;

    /// List BGP configurations
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bgp",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_config_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<BgpConfig>>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bgp-status",
        tags = ["system/networking"],
        versions = ..VERSION_BGP_PEER_COLLISION_STATE,
    }]
    async fn v2025120300_networking_bgp_status(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<Vec<v2025120300::BgpPeerStatus>>, HttpError>
    {
        let result = Self::networking_bgp_status(rqctx).await?.0;
        Ok(HttpResponseOk(
            result
                .into_iter()
                .map(|x| v2025120300::BgpPeerStatus {
                    addr: x.addr,
                    local_asn: x.local_asn,
                    remote_asn: x.remote_asn,
                    state: match x.state {
                        BgpPeerState::Idle => v2025120300::BgpPeerState::Idle,
                        BgpPeerState::Connect => {
                            v2025120300::BgpPeerState::Connect
                        }
                        BgpPeerState::Active => {
                            v2025120300::BgpPeerState::Active
                        }
                        BgpPeerState::OpenSent => {
                            v2025120300::BgpPeerState::OpenSent
                        }
                        BgpPeerState::OpenConfirm => {
                            v2025120300::BgpPeerState::OpenConfirm
                        }
                        BgpPeerState::ConnectionCollision
                        | BgpPeerState::SessionSetup => {
                            v2025120300::BgpPeerState::SessionSetup
                        }
                        BgpPeerState::Established => {
                            v2025120300::BgpPeerState::Established
                        }
                    },
                    state_duration_millis: x.state_duration_millis,
                    switch: x.switch,
                })
                .collect(),
        ))
    }

    //TODO pagination? the normal by-name/by-id stuff does not work here
    /// Get BGP peer status
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bgp-status",
        tags = ["system/networking"],
        versions = VERSION_BGP_PEER_COLLISION_STATE..,
    }]
    async fn networking_bgp_status(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<Vec<BgpPeerStatus>>, HttpError>;

    //TODO pagination? the normal by-name/by-id stuff does not work here
    /// Get BGP exported routes
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bgp-exported",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_exported(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<BgpExported>, HttpError>;

    /// Get BGP router message history
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bgp-message-history",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_message_history(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::BgpRouteSelector>,
    ) -> Result<HttpResponseOk<AggregateBgpMessageHistory>, HttpError>;

    //TODO pagination? the normal by-name/by-id stuff does not work here
    /// Get imported IPv4 BGP routes
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bgp-routes-ipv4",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_imported_routes_ipv4(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::BgpRouteSelector>,
    ) -> Result<HttpResponseOk<Vec<BgpImportedRouteIpv4>>, HttpError>;

    /// Delete BGP configuration
    #[endpoint {
        method = DELETE,
        path = "/v1/system/networking/bgp",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_config_delete(
        rqctx: RequestContext<Self::Context>,
        sel: Query<params::BgpConfigSelector>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Update BGP announce set
    ///
    /// If the announce set exists, this endpoint replaces the existing announce
    /// set with the one specified.
    #[endpoint {
        method = PUT,
        path = "/v1/system/networking/bgp-announce-set",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_announce_set_update(
        rqctx: RequestContext<Self::Context>,
        config: TypedBody<params::BgpAnnounceSetCreate>,
    ) -> Result<HttpResponseOk<BgpAnnounceSet>, HttpError>;

    /// List BGP announce sets
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bgp-announce-set",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_announce_set_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<Vec<BgpAnnounceSet>>, HttpError>;

    /// Delete BGP announce set
    #[endpoint {
        method = DELETE,
        path = "/v1/system/networking/bgp-announce-set/{announce_set}",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_announce_set_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::BgpAnnounceSetSelector>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    // TODO: is pagination necessary here? How large do we expect the list of
    // announcements to become in real usage?
    /// Get originated routes for a specified BGP announce set
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bgp-announce-set/{announce_set}/announcement",
        tags = ["system/networking"],
    }]
    async fn networking_bgp_announcement_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::BgpAnnounceSetSelector>,
    ) -> Result<HttpResponseOk<Vec<BgpAnnouncement>>, HttpError>;

    /// Enable BFD session
    #[endpoint {
        method = POST,
        path = "/v1/system/networking/bfd-enable",
        tags = ["system/networking"],
    }]
    async fn networking_bfd_enable(
        rqctx: RequestContext<Self::Context>,
        session: TypedBody<params::BfdSessionEnable>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Disable BFD session
    #[endpoint {
        method = POST,
        path = "/v1/system/networking/bfd-disable",
        tags = ["system/networking"],
    }]
    async fn networking_bfd_disable(
        rqctx: RequestContext<Self::Context>,
        session: TypedBody<params::BfdSessionDisable>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Get BFD status
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/bfd-status",
        tags = ["system/networking"],
    }]
    async fn networking_bfd_status(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<Vec<shared::BfdStatus>>, HttpError>;

    /// Get user-facing services IP allowlist
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/allow-list",
        tags = ["system/networking"],
    }]
    async fn networking_allow_list_view(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<views::AllowList>, HttpError>;

    /// Update user-facing services IP allowlist
    #[endpoint {
        method = PUT,
        path = "/v1/system/networking/allow-list",
        tags = ["system/networking"],
    }]
    async fn networking_allow_list_update(
        rqctx: RequestContext<Self::Context>,
        params: TypedBody<params::AllowListUpdate>,
    ) -> Result<HttpResponseOk<views::AllowList>, HttpError>;

    /// Return whether API services can receive limited ICMP traffic
    #[endpoint {
        method = GET,
        path = "/v1/system/networking/inbound-icmp",
        tags = ["system/networking"],
    }]
    async fn networking_inbound_icmp_view(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<ServiceIcmpConfig>, HttpError>;

    /// Set whether API services can receive limited ICMP traffic
    #[endpoint {
        method = PUT,
        path = "/v1/system/networking/inbound-icmp",
        tags = ["system/networking"],
    }]
    async fn networking_inbound_icmp_update(
        rqctx: RequestContext<Self::Context>,
        params: TypedBody<ServiceIcmpConfig>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    // Images

    /// List images
    ///
    /// List images which are global or scoped to the specified project. The images
    /// are returned sorted by creation date, with the most recent images appearing first.
    #[endpoint {
        method = GET,
        path = "/v1/images",
        tags = ["images"],
    }]
    async fn image_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::OptionalProjectSelector>,
        >,
    ) -> Result<HttpResponseOk<ResultsPage<views::Image>>, HttpError>;

    /// Create image
    ///
    /// Create a new image in a project.
    #[endpoint {
        method = POST,
        path = "/v1/images",
        tags = ["images"]
    }]
    async fn image_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        new_image: TypedBody<params::ImageCreate>,
    ) -> Result<HttpResponseCreated<views::Image>, HttpError>;

    /// Fetch image
    ///
    /// Fetch the details for a specific image in a project.
    #[endpoint {
        method = GET,
        path = "/v1/images/{image}",
        tags = ["images"],
    }]
    async fn image_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ImagePath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseOk<views::Image>, HttpError>;

    /// Delete image
    ///
    /// Permanently delete an image from a project. This operation cannot be undone.
    /// Any instances in the project using the image will continue to run, however
    /// new instances can not be created with this image.
    #[endpoint {
        method = DELETE,
        path = "/v1/images/{image}",
        tags = ["images"],
    }]
    async fn image_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ImagePath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Promote project image
    ///
    /// Promote project image to be visible to all projects in the silo
    #[endpoint {
        method = POST,
        path = "/v1/images/{image}/promote",
        tags = ["images"]
    }]
    async fn image_promote(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ImagePath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseAccepted<views::Image>, HttpError>;

    /// Demote silo image
    ///
    /// Demote silo image to be visible only to a specified project
    #[endpoint {
        method = POST,
        path = "/v1/images/{image}/demote",
        tags = ["images"]
    }]
    async fn image_demote(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ImagePath>,
        query_params: Query<params::ProjectSelector>,
    ) -> Result<HttpResponseAccepted<views::Image>, HttpError>;

    /// List network interfaces
    #[endpoint {
        operation_id = "instance_network_interface_list",
        method = GET,
        path = "/v1/network-interfaces",
        tags = ["instances"],
        versions = ..VERSION_DUAL_STACK_NICS,
    }]
    async fn v2026010100_instance_network_interface_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::InstanceSelector>>,
    ) -> Result<
        HttpResponseOk<ResultsPage<v2026010100::InstanceNetworkInterface>>,
        HttpError,
    > {
        let HttpResponseOk(ResultsPage { next_page, items }) =
            Self::instance_network_interface_list(rqctx, query_params).await?;
        items
            .into_iter()
            .map(TryInto::try_into)
            .collect::<Result<_, _>>()
            .map(|items| HttpResponseOk(ResultsPage { next_page, items }))
            .map_err(HttpError::from)
    }

    /// List network interfaces
    #[endpoint {
        method = GET,
        path = "/v1/network-interfaces",
        tags = ["instances"],
        versions = VERSION_DUAL_STACK_NICS..,
    }]
    async fn instance_network_interface_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::InstanceSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<InstanceNetworkInterface>>, HttpError>;

    /// Create network interface
    #[endpoint {
        operation_id = "instance_network_interface_create",
        method = POST,
        path = "/v1/network-interfaces",
        tags = ["instances"],
        versions = ..VERSION_DUAL_STACK_NICS,
    }]
    async fn v2026010100_instance_network_interface_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::InstanceSelector>,
        interface_params: TypedBody<
            v2026010100::InstanceNetworkInterfaceCreate,
        >,
    ) -> Result<
        HttpResponseCreated<v2026010100::InstanceNetworkInterface>,
        HttpError,
    > {
        let interface_params = interface_params.try_map(TryInto::try_into)?;
        let HttpResponseCreated(nic) = Self::instance_network_interface_create(
            rqctx,
            query_params,
            interface_params,
        )
        .await?;
        nic.try_into().map(HttpResponseCreated).map_err(HttpError::from)
    }

    /// Create network interface
    #[endpoint {
        method = POST,
        path = "/v1/network-interfaces",
        tags = ["instances"],
        versions = VERSION_DUAL_STACK_NICS..,
    }]
    async fn instance_network_interface_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::InstanceSelector>,
        interface_params: TypedBody<params::InstanceNetworkInterfaceCreate>,
    ) -> Result<HttpResponseCreated<InstanceNetworkInterface>, HttpError>;

    /// Delete network interface
    ///
    /// Note that the primary interface for an instance cannot be deleted if there
    /// are any secondary interfaces. A new primary interface must be designated
    /// first. The primary interface can be deleted if there are no secondary
    /// interfaces.
    #[endpoint {
        method = DELETE,
        path = "/v1/network-interfaces/{interface}",
        tags = ["instances"],
    }]
    async fn instance_network_interface_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::NetworkInterfacePath>,
        query_params: Query<params::OptionalInstanceSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Fetch network interface
    #[endpoint {
        operation_id = "instance_network_interface_view",
        method = GET,
        path = "/v1/network-interfaces/{interface}",
        tags = ["instances"],
        versions = ..VERSION_DUAL_STACK_NICS,
    }]
    async fn v2026010100_instance_network_interface_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::NetworkInterfacePath>,
        query_params: Query<params::OptionalInstanceSelector>,
    ) -> Result<HttpResponseOk<v2026010100::InstanceNetworkInterface>, HttpError>
    {
        let HttpResponseOk(nic) = Self::instance_network_interface_view(
            rqctx,
            path_params,
            query_params,
        )
        .await?;
        nic.try_into().map(HttpResponseOk).map_err(HttpError::from)
    }

    /// Fetch network interface
    #[endpoint {
        method = GET,
        path = "/v1/network-interfaces/{interface}",
        tags = ["instances"],
        versions = VERSION_DUAL_STACK_NICS..,
    }]
    async fn instance_network_interface_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::NetworkInterfacePath>,
        query_params: Query<params::OptionalInstanceSelector>,
    ) -> Result<HttpResponseOk<InstanceNetworkInterface>, HttpError>;

    /// Update network interface
    #[endpoint {
        operation_id = "instance_network_interface_update",
        method = PUT,
        path = "/v1/network-interfaces/{interface}",
        tags = ["instances"],
        versions = ..VERSION_DUAL_STACK_NICS,
    }]
    async fn v2026010100_instance_network_interface_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::NetworkInterfacePath>,
        query_params: Query<params::OptionalInstanceSelector>,
        updated_iface: TypedBody<params::InstanceNetworkInterfaceUpdate>,
    ) -> Result<HttpResponseOk<v2026010100::InstanceNetworkInterface>, HttpError>
    {
        let HttpResponseOk(nic) = Self::instance_network_interface_update(
            rqctx,
            path_params,
            query_params,
            updated_iface,
        )
        .await?;
        nic.try_into().map(HttpResponseOk).map_err(HttpError::from)
    }

    /// Update network interface
    #[endpoint {
        method = PUT,
        path = "/v1/network-interfaces/{interface}",
        tags = ["instances"],
        versions = VERSION_DUAL_STACK_NICS..,
    }]
    async fn instance_network_interface_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::NetworkInterfacePath>,
        query_params: Query<params::OptionalInstanceSelector>,
        updated_iface: TypedBody<params::InstanceNetworkInterfaceUpdate>,
    ) -> Result<HttpResponseOk<InstanceNetworkInterface>, HttpError>;

    // External IP addresses for instances

    /// List external IP addresses
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}/external-ips",
        tags = ["instances"],
    }]
    async fn instance_external_ip_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::OptionalProjectSelector>,
        path_params: Path<params::InstancePath>,
    ) -> Result<HttpResponseOk<ResultsPage<views::ExternalIp>>, HttpError>;

    /// Allocate and attach ephemeral IP to instance
    #[endpoint {
        operation_id = "instance_ephemeral_ip_attach",
        method = POST,
        path = "/v1/instances/{instance}/external-ips/ephemeral",
        tags = ["instances"],
        versions = ..VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS,
    }]
    async fn v2025121200_instance_ephemeral_ip_attach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::OptionalProjectSelector>,
        ip_to_create: TypedBody<v2025121200::EphemeralIpCreate>,
    ) -> Result<HttpResponseAccepted<views::ExternalIp>, HttpError> {
        Self::instance_ephemeral_ip_attach(
            rqctx,
            path_params,
            query_params,
            ip_to_create.map(Into::into),
        )
        .await
    }

    /// Allocate and attach ephemeral IP to instance
    #[endpoint {
        operation_id = "instance_ephemeral_ip_attach",
        method = POST,
        path = "/v1/instances/{instance}/external-ips/ephemeral",
        tags = ["instances"],
        versions = VERSION_IP_VERSION_AND_MULTIPLE_DEFAULT_POOLS
            ..VERSION_POOL_SELECTION_ENUMS,
    }]
    async fn v2026010300_instance_ephemeral_ip_attach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::OptionalProjectSelector>,
        ip_to_create: TypedBody<v2026010300::EphemeralIpCreate>,
    ) -> Result<HttpResponseAccepted<views::ExternalIp>, HttpError> {
        let ip_to_create = ip_to_create.try_map(TryInto::try_into)?;
        Self::instance_ephemeral_ip_attach(
            rqctx,
            path_params,
            query_params,
            ip_to_create,
        )
        .await
    }

    /// Allocate and attach ephemeral IP to instance
    #[endpoint {
        method = POST,
        path = "/v1/instances/{instance}/external-ips/ephemeral",
        tags = ["instances"],
        versions = VERSION_POOL_SELECTION_ENUMS..,
    }]
    async fn instance_ephemeral_ip_attach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::OptionalProjectSelector>,
        ip_to_create: TypedBody<params::EphemeralIpCreate>,
    ) -> Result<HttpResponseAccepted<views::ExternalIp>, HttpError>;

    /// Detach and deallocate ephemeral IP from instance
    #[endpoint {
        method = DELETE,
        path = "/v1/instances/{instance}/external-ips/ephemeral",
        tags = ["instances"],
    }]
    async fn instance_ephemeral_ip_detach(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstancePath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // Instance Multicast Groups

    /// List multicast groups for an instance
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}/multicast-groups",
        tags = ["experimental"],
        operation_id = "instance_multicast_group_list",
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_instance_multicast_group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById<params::OptionalProjectSelector>>,
        path_params: Path<params::InstancePath>,
    ) -> Result<
        HttpResponseOk<ResultsPage<v2025121200::MulticastGroupMember>>,
        HttpError,
    > {
        match Self::instance_multicast_group_list(
            rqctx,
            query_params,
            path_params,
        )
        .await
        {
            Ok(page) => {
                let new_page = ResultsPage {
                    next_page: page.0.next_page,
                    items: page.0.items.into_iter().map(Into::into).collect(),
                };
                Ok(HttpResponseOk(new_page))
            }
            Err(e) => Err(e),
        }
    }

    /// List multicast groups for an instance
    #[endpoint {
        method = GET,
        path = "/v1/instances/{instance}/multicast-groups",
        tags = ["experimental"],
        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
    }]
    async fn instance_multicast_group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById<params::OptionalProjectSelector>>,
        path_params: Path<params::InstancePath>,
    ) -> Result<
        HttpResponseOk<ResultsPage<views::MulticastGroupMember>>,
        HttpError,
    >;

    /// Join multicast group
    ///
    /// Deprecated: newer version supports implicit group creation, accepts group
    /// by name/UUID/IP and allows specifying source IPs (optional for ASM,
    /// required for SSM).
    #[endpoint {
        method = PUT,
        path = "/v1/instances/{instance}/multicast-groups/{multicast_group}",
        tags = ["experimental"],
        operation_id = "instance_multicast_group_join",
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    async fn v2025121200_instance_multicast_group_join(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<v2025121200::InstanceMulticastGroupPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseCreated<v2025121200::MulticastGroupMember>, HttpError>;

    /// Join multicast group by name, IP address, or UUID
    ///
    /// Groups can be referenced by name, IP address, or UUID. If the group
    /// doesn't exist, it's implicitly created with an auto-allocated IP from a
    /// multicast pool linked to the caller's silo. When referencing by UUID,
    /// the group must already exist.
    ///
    /// Source IPs are optional for ASM addresses but required for SSM addresses
    /// (232.0.0.0/8 for IPv4, ff3x::/32 for IPv6). Duplicate IPs in the request
    /// are automatically deduplicated, with a maximum of 64 source IPs allowed.
    #[endpoint {
        method = PUT,
        path = "/v1/instances/{instance}/multicast-groups/{multicast_group}",
        tags = ["experimental"],
        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
    }]
    async fn instance_multicast_group_join(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstanceMulticastGroupPath>,
        query_params: Query<params::OptionalProjectSelector>,
        body_params: TypedBody<params::InstanceMulticastGroupJoin>,
    ) -> Result<HttpResponseCreated<views::MulticastGroupMember>, HttpError>;

    /// Leave multicast group
    ///
    /// Deprecated: newer version accepts group by name, UUID, or IP address.
    #[endpoint {
        method = DELETE,
        path = "/v1/instances/{instance}/multicast-groups/{multicast_group}",
        tags = ["experimental"],
        operation_id = "instance_multicast_group_leave",
        versions = ..VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES,
    }]
    // Cannot delegate inline: path types differ (NameOrId vs MulticastGroupIdentifier)
    // and can't construct Path<T> (Dropshot extractor with private fields).
    async fn v2025121200_instance_multicast_group_leave(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<v2025121200::InstanceMulticastGroupPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Leave multicast group by name, IP address, or UUID
    #[endpoint {
        method = DELETE,
        path = "/v1/instances/{instance}/multicast-groups/{multicast_group}",
        tags = ["experimental"],
        versions = VERSION_MULTICAST_IMPLICIT_LIFECYCLE_UPDATES..,
    }]
    async fn instance_multicast_group_leave(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InstanceMulticastGroupPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // Snapshots

    /// List snapshots
    #[endpoint {
        method = GET,
        path = "/v1/snapshots",
        tags = ["snapshots"],
    }]
    async fn snapshot_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Snapshot>>, HttpError>;

    /// Create snapshot
    ///
    /// Creates a point-in-time snapshot from a disk.
    #[endpoint {
        method = POST,
        path = "/v1/snapshots",
        tags = ["snapshots"],
    }]
    async fn snapshot_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_snapshot: TypedBody<params::SnapshotCreate>,
    ) -> Result<HttpResponseCreated<views::Snapshot>, HttpError>;

    /// Fetch snapshot
    #[endpoint {
        method = GET,
        path = "/v1/snapshots/{snapshot}",
        tags = ["snapshots"],
    }]
    async fn snapshot_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SnapshotPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseOk<views::Snapshot>, HttpError>;

    /// Delete snapshot
    #[endpoint {
        method = DELETE,
        path = "/v1/snapshots/{snapshot}",
        tags = ["snapshots"],
    }]
    async fn snapshot_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SnapshotPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // VPCs

    /// List VPCs
    #[endpoint {
        method = GET,
        path = "/v1/vpcs",
        tags = ["vpcs"],
    }]
    async fn vpc_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Vpc>>, HttpError>;

    /// Create VPC
    #[endpoint {
        method = POST,
        path = "/v1/vpcs",
        tags = ["vpcs"],
    }]
    async fn vpc_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        body: TypedBody<params::VpcCreate>,
    ) -> Result<HttpResponseCreated<views::Vpc>, HttpError>;

    /// Fetch VPC
    #[endpoint {
        method = GET,
        path = "/v1/vpcs/{vpc}",
        tags = ["vpcs"],
    }]
    async fn vpc_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::VpcPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseOk<views::Vpc>, HttpError>;

    /// Update VPC
    #[endpoint {
        method = PUT,
        path = "/v1/vpcs/{vpc}",
        tags = ["vpcs"],
    }]
    async fn vpc_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::VpcPath>,
        query_params: Query<params::OptionalProjectSelector>,
        updated_vpc: TypedBody<params::VpcUpdate>,
    ) -> Result<HttpResponseOk<views::Vpc>, HttpError>;

    /// Delete VPC
    #[endpoint {
        method = DELETE,
        path = "/v1/vpcs/{vpc}",
        tags = ["vpcs"],
    }]
    async fn vpc_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::VpcPath>,
        query_params: Query<params::OptionalProjectSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List subnets
    #[endpoint {
        method = GET,
        path = "/v1/vpc-subnets",
        tags = ["vpcs"],
    }]
    async fn vpc_subnet_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::VpcSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::VpcSubnet>>, HttpError>;

    /// Create subnet
    #[endpoint {
        method = POST,
        path = "/v1/vpc-subnets",
        tags = ["vpcs"],
    }]
    async fn vpc_subnet_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::VpcSelector>,
        create_params: TypedBody<params::VpcSubnetCreate>,
    ) -> Result<HttpResponseCreated<views::VpcSubnet>, HttpError>;

    /// Fetch subnet
    #[endpoint {
        method = GET,
        path = "/v1/vpc-subnets/{subnet}",
        tags = ["vpcs"],
    }]
    async fn vpc_subnet_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPath>,
        query_params: Query<params::OptionalVpcSelector>,
    ) -> Result<HttpResponseOk<views::VpcSubnet>, HttpError>;

    /// Delete subnet
    #[endpoint {
        method = DELETE,
        path = "/v1/vpc-subnets/{subnet}",
        tags = ["vpcs"],
    }]
    async fn vpc_subnet_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPath>,
        query_params: Query<params::OptionalVpcSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Update subnet
    #[endpoint {
        method = PUT,
        path = "/v1/vpc-subnets/{subnet}",
        tags = ["vpcs"],
    }]
    async fn vpc_subnet_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPath>,
        query_params: Query<params::OptionalVpcSelector>,
        subnet_params: TypedBody<params::VpcSubnetUpdate>,
    ) -> Result<HttpResponseOk<views::VpcSubnet>, HttpError>;

    // This endpoint is likely temporary. We would rather list all IPs allocated in
    // a subnet whether they come from NICs or something else. See
    // https://github.com/oxidecomputer/omicron/issues/2476

    /// List network interfaces
    #[endpoint {
        operation_id = "vpc_subnet_list_network_interfaces",
        method = GET,
        path = "/v1/vpc-subnets/{subnet}/network-interfaces",
        tags = ["vpcs"],
        versions = ..VERSION_DUAL_STACK_NICS,
    }]
    async fn v2026010100_vpc_subnet_list_network_interfaces(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPath>,
        query_params: Query<PaginatedByNameOrId<params::OptionalVpcSelector>>,
    ) -> Result<
        HttpResponseOk<ResultsPage<v2026010100::InstanceNetworkInterface>>,
        HttpError,
    > {
        let HttpResponseOk(ResultsPage { items, next_page }) =
            Self::vpc_subnet_list_network_interfaces(
                rqctx,
                path_params,
                query_params,
            )
            .await?;
        items
            .into_iter()
            .map(TryInto::try_into)
            .collect::<Result<_, _>>()
            .map(|items| HttpResponseOk(ResultsPage { items, next_page }))
            .map_err(HttpError::from)
    }

    /// List network interfaces
    #[endpoint {
        method = GET,
        path = "/v1/vpc-subnets/{subnet}/network-interfaces",
        tags = ["vpcs"],
        versions = VERSION_DUAL_STACK_NICS..,
    }]
    async fn vpc_subnet_list_network_interfaces(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SubnetPath>,
        query_params: Query<PaginatedByNameOrId<params::OptionalVpcSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<InstanceNetworkInterface>>, HttpError>;

    // VPC Firewalls

    /// List firewall rules
    #[endpoint {
        method = GET,
        path = "/v1/vpc-firewall-rules",
        tags = ["vpcs"],
    }]
    async fn vpc_firewall_rules_view(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::VpcSelector>,
    ) -> Result<HttpResponseOk<VpcFirewallRules>, HttpError>;

    // Note: the limits in the below comment come from the firewall rules model
    // file, nexus/db-model/src/vpc_firewall_rule.rs.

    /// Replace firewall rules
    ///
    /// The maximum number of rules per VPC is 1024.
    ///
    /// Targets are used to specify the set of instances to which a firewall rule
    /// applies. You can target instances directly by name, or specify a VPC, VPC
    /// subnet, IP, or IP subnet, which will apply the rule to traffic going to
    /// all matching instances. Targets are additive: the rule applies to instances
    /// matching ANY target. The maximum number of targets is 256.
    ///
    /// Filters reduce the scope of a firewall rule. Without filters, the rule
    /// applies to all packets to the targets (or from the targets, if it's an
    /// outbound rule). With multiple filters, the rule applies only to packets
    /// matching ALL filters. The maximum number of each type of filter is 256.
    #[endpoint {
        method = PUT,
        path = "/v1/vpc-firewall-rules",
        tags = ["vpcs"],
    }]
    async fn vpc_firewall_rules_update(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::VpcSelector>,
        router_params: TypedBody<VpcFirewallRuleUpdateParams>,
    ) -> Result<HttpResponseOk<VpcFirewallRules>, HttpError>;

    // VPC Routers

    /// List routers
    #[endpoint {
        method = GET,
        path = "/v1/vpc-routers",
        tags = ["vpcs"],
    }]
    async fn vpc_router_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::VpcSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::VpcRouter>>, HttpError>;

    /// Fetch router
    #[endpoint {
        method = GET,
        path = "/v1/vpc-routers/{router}",
        tags = ["vpcs"],
    }]
    async fn vpc_router_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RouterPath>,
        query_params: Query<params::OptionalVpcSelector>,
    ) -> Result<HttpResponseOk<views::VpcRouter>, HttpError>;

    /// Create VPC router
    #[endpoint {
        method = POST,
        path = "/v1/vpc-routers",
        tags = ["vpcs"],
    }]
    async fn vpc_router_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::VpcSelector>,
        create_params: TypedBody<params::VpcRouterCreate>,
    ) -> Result<HttpResponseCreated<views::VpcRouter>, HttpError>;

    /// Delete router
    #[endpoint {
        method = DELETE,
        path = "/v1/vpc-routers/{router}",
        tags = ["vpcs"],
    }]
    async fn vpc_router_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RouterPath>,
        query_params: Query<params::OptionalVpcSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Update router
    #[endpoint {
        method = PUT,
        path = "/v1/vpc-routers/{router}",
        tags = ["vpcs"],
    }]
    async fn vpc_router_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RouterPath>,
        query_params: Query<params::OptionalVpcSelector>,
        router_params: TypedBody<params::VpcRouterUpdate>,
    ) -> Result<HttpResponseOk<views::VpcRouter>, HttpError>;

    /// List routes
    ///
    /// List the routes associated with a router in a particular VPC.
    #[endpoint {
        method = GET,
        path = "/v1/vpc-router-routes",
        tags = ["vpcs"],
    }]
    async fn vpc_router_route_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::RouterSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<RouterRoute>>, HttpError>;

    // Vpc Router Routes

    /// Fetch route
    #[endpoint {
        method = GET,
        path = "/v1/vpc-router-routes/{route}",
        tags = ["vpcs"],
    }]
    async fn vpc_router_route_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RoutePath>,
        query_params: Query<params::OptionalRouterSelector>,
    ) -> Result<HttpResponseOk<RouterRoute>, HttpError>;

    /// Create route
    #[endpoint {
        method = POST,
        path = "/v1/vpc-router-routes",
        tags = ["vpcs"],
    }]
    async fn vpc_router_route_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::RouterSelector>,
        create_params: TypedBody<params::RouterRouteCreate>,
    ) -> Result<HttpResponseCreated<RouterRoute>, HttpError>;

    /// Delete route
    #[endpoint {
        method = DELETE,
        path = "/v1/vpc-router-routes/{route}",
        tags = ["vpcs"],
    }]
    async fn vpc_router_route_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RoutePath>,
        query_params: Query<params::OptionalRouterSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Update route
    #[endpoint {
        method = PUT,
        path = "/v1/vpc-router-routes/{route}",
        tags = ["vpcs"],
    }]
    async fn vpc_router_route_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RoutePath>,
        query_params: Query<params::OptionalRouterSelector>,
        router_params: TypedBody<params::RouterRouteUpdate>,
    ) -> Result<HttpResponseOk<RouterRoute>, HttpError>;

    // Internet gateways

    /// List internet gateways
    #[endpoint {
        method = GET,
        path = "/v1/internet-gateways",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::VpcSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::InternetGateway>>, HttpError>;

    /// Fetch internet gateway
    #[endpoint {
        method = GET,
        path = "/v1/internet-gateways/{gateway}",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InternetGatewayPath>,
        query_params: Query<params::OptionalVpcSelector>,
    ) -> Result<HttpResponseOk<views::InternetGateway>, HttpError>;

    /// Create VPC internet gateway
    #[endpoint {
        method = POST,
        path = "/v1/internet-gateways",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::VpcSelector>,
        create_params: TypedBody<params::InternetGatewayCreate>,
    ) -> Result<HttpResponseCreated<views::InternetGateway>, HttpError>;

    /// Delete internet gateway
    #[endpoint {
        method = DELETE,
        path = "/v1/internet-gateways/{gateway}",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::InternetGatewayPath>,
        query_params: Query<params::InternetGatewayDeleteSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List IP pools attached to internet gateway
    #[endpoint {
        method = GET,
        path = "/v1/internet-gateway-ip-pools",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_ip_pool_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::InternetGatewaySelector>,
        >,
    ) -> Result<
        HttpResponseOk<ResultsPage<views::InternetGatewayIpPool>>,
        HttpError,
    >;

    /// Attach IP pool to internet gateway
    #[endpoint {
        method = POST,
        path = "/v1/internet-gateway-ip-pools",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_ip_pool_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::InternetGatewaySelector>,
        create_params: TypedBody<params::InternetGatewayIpPoolCreate>,
    ) -> Result<HttpResponseCreated<views::InternetGatewayIpPool>, HttpError>;

    /// Detach IP pool from internet gateway
    #[endpoint {
        method = DELETE,
        path = "/v1/internet-gateway-ip-pools/{pool}",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_ip_pool_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpPoolPath>,
        query_params: Query<params::DeleteInternetGatewayElementSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List IP addresses attached to internet gateway
    #[endpoint {
        method = GET,
        path = "/v1/internet-gateway-ip-addresses",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_ip_address_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<
            PaginatedByNameOrId<params::InternetGatewaySelector>,
        >,
    ) -> Result<
        HttpResponseOk<ResultsPage<views::InternetGatewayIpAddress>>,
        HttpError,
    >;

    /// Attach IP address to internet gateway
    #[endpoint {
        method = POST,
        path = "/v1/internet-gateway-ip-addresses",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_ip_address_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::InternetGatewaySelector>,
        create_params: TypedBody<params::InternetGatewayIpAddressCreate>,
    ) -> Result<HttpResponseCreated<views::InternetGatewayIpAddress>, HttpError>;

    /// Detach IP address from internet gateway
    #[endpoint {
        method = DELETE,
        path = "/v1/internet-gateway-ip-addresses/{address}",
        tags = ["vpcs"],
    }]
    async fn internet_gateway_ip_address_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::IpAddressPath>,
        query_params: Query<params::DeleteInternetGatewayElementSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // Racks

    /// List racks
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/racks",
        tags = ["system/hardware"],
    }]
    async fn rack_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Rack>>, HttpError>;

    /// Fetch rack
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/racks/{rack_id}",
        tags = ["system/hardware"],
    }]
    async fn rack_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RackPath>,
    ) -> Result<HttpResponseOk<views::Rack>, HttpError>;

    /// List uninitialized sleds
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/sleds-uninitialized",
        tags = ["system/hardware"]
    }]
    async fn sled_list_uninitialized(
        rqctx: RequestContext<Self::Context>,
        query: Query<PaginationParams<EmptyScanParams, String>>,
    ) -> Result<HttpResponseOk<ResultsPage<shared::UninitializedSled>>, HttpError>;

    /// Add sled to initialized rack
    //
    // TODO: In the future this should really be a PUT request, once we resolve
    // https://github.com/oxidecomputer/omicron/issues/4494. It should also
    // explicitly be tied to a rack via a `rack_id` path param. For now we assume
    // we are only operating on single rack systems.
    #[endpoint {
        method = POST,
        path = "/v1/system/hardware/sleds",
        tags = ["system/hardware"]
    }]
    async fn sled_add(
        rqctx: RequestContext<Self::Context>,
        sled: TypedBody<params::UninitializedSledId>,
    ) -> Result<HttpResponseCreated<views::SledId>, HttpError>;

    /// Add new sleds to rack membership
    #[endpoint {
        method = POST,
        path = "/v1/system/hardware/racks/{rack_id}/membership/add",
        tags = ["experimental"],
        versions = VERSION_TRUST_QUORUM_ADD_SLEDS_AND_GET_LATEST_CONFIG..
    }]
    async fn rack_membership_add_sleds(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RackPath>,
        req: TypedBody<params::RackMembershipAddSledsRequest>,
    ) -> Result<HttpResponseOk<RackMembershipStatus>, HttpError>;

    /// Retrieve the rack cluster membership status
    ///
    /// Returns the status for the most recent change, or a specific version if
    /// one is specified.
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/racks/{rack_id}/membership",
        tags = ["experimental"],
        versions = VERSION_TRUST_QUORUM_ADD_SLEDS_AND_GET_LATEST_CONFIG..
    }]
    async fn rack_membership_status(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RackMembershipConfigPathParams>,
        query_params: Query<params::RackMembershipVersionParam>,
    ) -> Result<HttpResponseOk<RackMembershipStatus>, HttpError>;

    // Sleds

    /// List sleds
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/sleds",
        tags = ["system/hardware"],
    }]
    async fn sled_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Sled>>, HttpError>;

    /// Fetch sled
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/sleds/{sled_id}",
        tags = ["system/hardware"],
    }]
    async fn sled_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SledPath>,
    ) -> Result<HttpResponseOk<views::Sled>, HttpError>;

    /// Set sled provision policy
    #[endpoint {
        method = PUT,
        path = "/v1/system/hardware/sleds/{sled_id}/provision-policy",
        tags = ["system/hardware"],
    }]
    async fn sled_set_provision_policy(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SledPath>,
        new_provision_state: TypedBody<params::SledProvisionPolicyParams>,
    ) -> Result<HttpResponseOk<params::SledProvisionPolicyResponse>, HttpError>;

    /// List instances running on given sled
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/sleds/{sled_id}/instances",
        tags = ["system/hardware"],
    }]
    async fn sled_instance_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SledPath>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SledInstance>>, HttpError>;

    // Physical disks

    /// List physical disks
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/disks",
        tags = ["system/hardware"],
    }]
    async fn physical_disk_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::PhysicalDisk>>, HttpError>;

    /// Get physical disk
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/disks/{disk_id}",
        tags = ["system/hardware"],
    }]
    async fn physical_disk_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::PhysicalDiskPath>,
    ) -> Result<HttpResponseOk<views::PhysicalDisk>, HttpError>;

    // Switches

    /// List switches
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/switches",
        tags = ["system/hardware"],
    }]
    async fn switch_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Switch>>, HttpError>;

    /// Fetch switch
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/switches/{switch_id}",
        tags = ["system/hardware"],
    }]
    async fn switch_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SwitchPath>,
    ) -> Result<HttpResponseOk<views::Switch>, HttpError>;

    /// List physical disks attached to sleds
    #[endpoint {
        method = GET,
        path = "/v1/system/hardware/sleds/{sled_id}/disks",
        tags = ["system/hardware"],
    }]
    async fn sled_physical_disk_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SledPath>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::PhysicalDisk>>, HttpError>;

    // Metrics

    /// View metrics
    ///
    /// View CPU, memory, or storage utilization metrics at the fleet or silo level.
    #[endpoint {
        method = GET,
        path = "/v1/system/metrics/{metric_name}",
        tags = ["system/metrics"],
    }]
    async fn system_metric(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SystemMetricsPathParam>,
        pag_params: Query<
            PaginationParams<params::ResourceMetrics, params::ResourceMetrics>,
        >,
        other_params: Query<params::OptionalSiloSelector>,
    ) -> Result<
        HttpResponseOk<ResultsPage<oximeter_types::Measurement>>,
        HttpError,
    >;

    /// View metrics
    ///
    /// View CPU, memory, or storage utilization metrics at the silo or project level.
    #[endpoint {
        method = GET,
        path = "/v1/metrics/{metric_name}",
        tags = ["metrics"],
    }]
    async fn silo_metric(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SystemMetricsPathParam>,
        pag_params: Query<
            PaginationParams<params::ResourceMetrics, params::ResourceMetrics>,
        >,
        other_params: Query<params::OptionalProjectSelector>,
    ) -> Result<
        HttpResponseOk<ResultsPage<oximeter_types::Measurement>>,
        HttpError,
    >;

    /// List timeseries schemas
    #[endpoint {
        method = GET,
        path = "/v1/system/timeseries/schemas",
        tags = ["system/metrics"],
    }]
    async fn system_timeseries_schema_list(
        rqctx: RequestContext<Self::Context>,
        pag_params: Query<TimeseriesSchemaPaginationParams>,
    ) -> Result<
        HttpResponseOk<ResultsPage<oximeter_types::TimeseriesSchema>>,
        HttpError,
    >;

    // TODO: can we link to an OxQL reference? Do we have one? Can we even do links?

    /// Run timeseries query
    ///
    /// Queries are written in OxQL.
    #[endpoint {
        method = POST,
        path = "/v1/system/timeseries/query",
        tags = ["system/metrics"],
    }]
    async fn system_timeseries_query(
        rqctx: RequestContext<Self::Context>,
        body: TypedBody<params::TimeseriesQuery>,
    ) -> Result<HttpResponseOk<views::OxqlQueryResult>, HttpError>;

    // TODO: list endpoint for project-scoped schemas is blocked on
    // https://github.com/oxidecomputer/omicron/issues/5942: the authz scope for
    // each schema is not stored in Clickhouse yet.

    /// Run project-scoped timeseries query
    ///
    /// Queries are written in OxQL. Project must be specified by name or ID in
    /// URL query parameter. The OxQL query will only return timeseries data
    /// from the specified project.
    #[endpoint {
        method = POST,
        path = "/v1/timeseries/query",
        tags = ["experimental"],
    }]
    async fn timeseries_query(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        body: TypedBody<params::TimeseriesQuery>,
    ) -> Result<HttpResponseOk<views::OxqlQueryResult>, HttpError>;

    // Updates

    /// Upload system release repository
    ///
    /// System release repositories are verified by the updates trust store.
    #[endpoint {
        method = PUT,
        path = "/v1/system/update/repositories",
        tags = ["system/update"],
        request_body_max_bytes = PUT_UPDATE_REPOSITORY_MAX_BYTES,
    }]
    async fn system_update_repository_upload(
        rqctx: RequestContext<Self::Context>,
        query: Query<params::UpdatesPutRepositoryParams>,
        body: StreamingBody,
    ) -> Result<HttpResponseOk<views::TufRepoUpload>, HttpError>;

    /// Fetch system release repository by version
    #[endpoint {
        method = GET,
        path = "/v1/system/update/repositories/{system_version}",
        tags = ["system/update"],
    }]
    async fn system_update_repository_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UpdatesGetRepositoryParams>,
    ) -> Result<HttpResponseOk<views::TufRepo>, HttpError>;

    /// List all TUF repositories
    ///
    /// Returns a paginated list of all TUF repositories ordered by system
    /// version (newest first by default).
    #[endpoint {
        method = GET,
        path = "/v1/system/update/repositories",
        tags = ["system/update"],
    }]
    async fn system_update_repository_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByVersion>,
    ) -> Result<HttpResponseOk<ResultsPage<views::TufRepo>>, HttpError>;

    /// List root roles in the updates trust store
    ///
    /// A root role is a JSON document describing the cryptographic keys that
    /// are trusted to sign system release repositories, as described by The
    /// Update Framework. Uploading a repository requires its metadata to be
    /// signed by keys trusted by the trust store.
    #[endpoint {
        method = GET,
        path = "/v1/system/update/trust-roots",
        tags = ["system/update"],
    }]
    async fn system_update_trust_root_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::UpdatesTrustRoot>>, HttpError>;

    /// Add trusted root role to updates trust store
    #[endpoint {
        method = POST,
        path = "/v1/system/update/trust-roots",
        tags = ["system/update"],
    }]
    async fn system_update_trust_root_create(
        rqctx: RequestContext<Self::Context>,
        body: TypedBody<shared::TufSignedRootRole>,
    ) -> Result<HttpResponseCreated<views::UpdatesTrustRoot>, HttpError>;

    /// Fetch trusted root role
    #[endpoint {
        method = GET,
        path = "/v1/system/update/trust-roots/{trust_root_id}",
        tags = ["system/update"],
    }]
    async fn system_update_trust_root_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::TufTrustRootPath>,
    ) -> Result<HttpResponseOk<views::UpdatesTrustRoot>, HttpError>;

    /// Delete trusted root role
    ///
    /// Note that this method does not currently check for any uploaded system
    /// release repositories that would become untrusted after deleting the
    /// root role.
    #[endpoint {
        method = DELETE,
        path = "/v1/system/update/trust-roots/{trust_root_id}",
        tags = ["system/update"],
    }]
    async fn system_update_trust_root_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::TufTrustRootPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Set target release
    ///
    /// Set the current target release of the rack's system software. The rack
    /// reconfigurator will treat the software specified here as a goal state
    /// for the rack's software, and attempt to asynchronously update to that
    /// release. Use the update status endpoint to view the current target
    /// release.
    #[endpoint {
        method = PUT,
        path = "/v1/system/update/target-release",
        tags = ["system/update"],
    }]
    async fn target_release_update(
        rqctx: RequestContext<Self::Context>,
        params: TypedBody<params::SetTargetReleaseParams>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Fetch system update status
    ///
    /// Returns information about the current target release and the
    /// progress of system software updates.
    #[endpoint {
        method = GET,
        path = "/v1/system/update/status",
        tags = ["system/update"],
    }]
    async fn system_update_status(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<views::UpdateStatus>, HttpError>;

    // Silo users

    /// List users
    #[endpoint {
        method = GET,
        path = "/v1/users",
        tags = ["silos"],
    }]
    async fn user_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById<params::OptionalGroupSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::User>>, HttpError>;

    /// Fetch user
    #[endpoint {
        method = GET,
        path = "/v1/users/{user_id}",
        tags = ["silos"],
    }]
    async fn user_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UserPath>,
    ) -> Result<HttpResponseOk<views::User>, HttpError>;

    /// List user's access tokens
    #[endpoint {
        method = GET,
        path = "/v1/users/{user_id}/access-tokens",
        tags = ["silos"],
    }]
    async fn user_token_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UserPath>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::DeviceAccessToken>>, HttpError>;

    /// List user's console sessions
    #[endpoint {
        method = GET,
        path = "/v1/users/{user_id}/sessions",
        tags = ["silos"],
    }]
    async fn user_session_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UserPath>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::ConsoleSession>>, HttpError>;

    /// Log user out
    ///
    /// Silo admins can use this endpoint to log the specified user out by
    /// deleting all of their tokens AND sessions. This cannot be undone.
    #[endpoint {
        method = POST,
        path = "/v1/users/{user_id}/logout",
        tags = ["silos"],
    }]
    async fn user_logout(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UserPath>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    // Silo groups

    /// List groups
    #[endpoint {
        method = GET,
        path = "/v1/groups",
        tags = ["silos"],
    }]
    async fn group_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Group>>, HttpError>;

    /// Fetch group
    #[endpoint {
        method = GET,
        path = "/v1/groups/{group_id}",
        tags = ["silos"],
    }]
    async fn group_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::GroupPath>,
    ) -> Result<HttpResponseOk<views::Group>, HttpError>;

    // Built-in (system) users

    /// List built-in users
    #[endpoint {
        method = GET,
        path = "/v1/system/users-builtin",
        tags = ["system/silos"],
    }]
    async fn user_builtin_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByName>,
    ) -> Result<HttpResponseOk<ResultsPage<views::UserBuiltin>>, HttpError>;

    /// Fetch built-in user
    #[endpoint {
        method = GET,
        path = "/v1/system/users-builtin/{user}",
        tags = ["system/silos"],
    }]
    async fn user_builtin_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::UserBuiltinSelector>,
    ) -> Result<HttpResponseOk<views::UserBuiltin>, HttpError>;

    // Current user

    /// Fetch user for current session
    #[endpoint {
        method = GET,
        path = "/v1/me",
        tags = ["current-user"],
    }]
    async fn current_user_view(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<HttpResponseOk<views::CurrentUser>, HttpError>;

    /// Fetch current user's groups
    #[endpoint {
        method = GET,
        path = "/v1/me/groups",
        tags = ["current-user"],
    }]
    async fn current_user_groups(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::Group>>, HttpError>;

    // Per-user SSH public keys

    /// List SSH public keys
    ///
    /// Lists SSH public keys for the currently authenticated user.
    #[endpoint {
        method = GET,
        path = "/v1/me/ssh-keys",
        tags = ["current-user"],
    }]
    async fn current_user_ssh_key_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::SshKey>>, HttpError>;

    /// Create SSH public key
    ///
    /// Create an SSH public key for the currently authenticated user.
    #[endpoint {
        method = POST,
        path = "/v1/me/ssh-keys",
        tags = ["current-user"],
    }]
    async fn current_user_ssh_key_create(
        rqctx: RequestContext<Self::Context>,
        new_key: TypedBody<params::SshKeyCreate>,
    ) -> Result<HttpResponseCreated<views::SshKey>, HttpError>;

    /// Fetch SSH public key
    ///
    /// Fetch SSH public key associated with the currently authenticated user.
    #[endpoint {
        method = GET,
        path = "/v1/me/ssh-keys/{ssh_key}",
        tags = ["current-user"],
    }]
    async fn current_user_ssh_key_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SshKeyPath>,
    ) -> Result<HttpResponseOk<views::SshKey>, HttpError>;

    /// Delete SSH public key
    ///
    /// Delete an SSH public key associated with the currently authenticated user.
    #[endpoint {
        method = DELETE,
        path = "/v1/me/ssh-keys/{ssh_key}",
        tags = ["current-user"],
    }]
    async fn current_user_ssh_key_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SshKeyPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List access tokens
    ///
    /// List device access tokens for the currently authenticated user.
    #[endpoint {
        method = GET,
        path = "/v1/me/access-tokens",
        tags = ["tokens"],
    }]
    async fn current_user_access_token_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedById>,
    ) -> Result<HttpResponseOk<ResultsPage<views::DeviceAccessToken>>, HttpError>;

    /// Delete access token
    ///
    /// Delete a device access token for the currently authenticated user.
    #[endpoint {
        method = DELETE,
        path = "/v1/me/access-tokens/{token_id}",
        tags = ["tokens"],
    }]
    async fn current_user_access_token_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::TokenPath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // Support bundles (experimental)

    /// List all support bundles
    #[endpoint {
        method = GET,
        path = "/experimental/v1/system/support-bundles",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByTimeAndId>,
    ) -> Result<HttpResponseOk<ResultsPage<shared::SupportBundleInfo>>, HttpError>;

    /// View support bundle
    #[endpoint {
        method = GET,
        path = "/experimental/v1/system/support-bundles/{bundle_id}",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SupportBundlePath>,
    ) -> Result<HttpResponseOk<shared::SupportBundleInfo>, HttpError>;

    /// Download the index of a support bundle
    #[endpoint {
        method = GET,
        path = "/experimental/v1/system/support-bundles/{bundle_id}/index",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_index(
        rqctx: RequestContext<Self::Context>,
        headers: Header<headers::RangeRequest>,
        path_params: Path<params::SupportBundlePath>,
    ) -> Result<Response<Body>, HttpError>;

    /// Download the contents of a support bundle
    #[endpoint {
        method = GET,
        path = "/experimental/v1/system/support-bundles/{bundle_id}/download",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_download(
        rqctx: RequestContext<Self::Context>,
        headers: Header<headers::RangeRequest>,
        path_params: Path<params::SupportBundlePath>,
    ) -> Result<Response<Body>, HttpError>;

    /// Download a file within a support bundle
    #[endpoint {
        method = GET,
        path = "/experimental/v1/system/support-bundles/{bundle_id}/download/{file}",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_download_file(
        rqctx: RequestContext<Self::Context>,
        headers: Header<headers::RangeRequest>,
        path_params: Path<params::SupportBundleFilePath>,
    ) -> Result<Response<Body>, HttpError>;

    /// Download the metadata of a support bundle
    #[endpoint {
        method = HEAD,
        path = "/experimental/v1/system/support-bundles/{bundle_id}/download",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_head(
        rqctx: RequestContext<Self::Context>,
        headers: Header<headers::RangeRequest>,
        path_params: Path<params::SupportBundlePath>,
    ) -> Result<Response<Body>, HttpError>;

    /// Download the metadata of a file within the support bundle
    #[endpoint {
        method = HEAD,
        path = "/experimental/v1/system/support-bundles/{bundle_id}/download/{file}",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_head_file(
        rqctx: RequestContext<Self::Context>,
        headers: Header<headers::RangeRequest>,
        path_params: Path<params::SupportBundleFilePath>,
    ) -> Result<Response<Body>, HttpError>;

    /// Create a new support bundle
    #[endpoint {
        method = POST,
        path = "/experimental/v1/system/support-bundles",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_create(
        rqctx: RequestContext<Self::Context>,
        body: TypedBody<params::SupportBundleCreate>,
    ) -> Result<HttpResponseCreated<shared::SupportBundleInfo>, HttpError>;

    /// Delete an existing support bundle
    ///
    /// May also be used to cancel a support bundle which is currently being
    /// collected, or to remove metadata for a support bundle that has failed.
    #[endpoint {
        method = DELETE,
        path = "/experimental/v1/system/support-bundles/{bundle_id}",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SupportBundlePath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Update a support bundle
    #[endpoint {
        method = PUT,
        path = "/experimental/v1/system/support-bundles/{bundle_id}",
        tags = ["experimental"], // system/support-bundles: only one tag is allowed
    }]
    async fn support_bundle_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::SupportBundlePath>,
        body: TypedBody<params::SupportBundleUpdate>,
    ) -> Result<HttpResponseOk<shared::SupportBundleInfo>, HttpError>;

    // Probes (experimental)

    /// List instrumentation probes
    #[endpoint {
        operation_id = "probe_list",
        method = GET,
        path = "/experimental/v1/probes",
        tags = ["experimental"], // system/probes: only one tag is allowed
        versions = ..VERSION_DUAL_STACK_NICS,
    }]
    async fn v2026010100_probe_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<v2026010100::ProbeInfo>>, HttpError>
    {
        let HttpResponseOk(ResultsPage { items, next_page }) =
            Self::probe_list(rqctx, query_params).await?;
        items
            .into_iter()
            .map(TryInto::try_into)
            .collect::<Result<_, _>>()
            .map(|items| HttpResponseOk(ResultsPage { items, next_page }))
            .map_err(HttpError::from)
    }

    /// List instrumentation probes
    #[endpoint {
        method = GET,
        path = "/experimental/v1/probes",
        tags = ["experimental"], // system/probes: only one tag is allowed
        versions = VERSION_DUAL_STACK_NICS..,
    }]
    async fn probe_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId<params::ProjectSelector>>,
    ) -> Result<HttpResponseOk<ResultsPage<shared::ProbeInfo>>, HttpError>;

    /// View instrumentation probe
    #[endpoint {
        operation_id = "probe_view",
        method = GET,
        path = "/experimental/v1/probes/{probe}",
        tags = ["experimental"], // system/probes: only one tag is allowed
        versions = ..VERSION_DUAL_STACK_NICS,
    }]
    async fn v2026010100_probe_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ProbePath>,
        query_params: Query<params::ProjectSelector>,
    ) -> Result<HttpResponseOk<v2026010100::ProbeInfo>, HttpError> {
        let HttpResponseOk(info) =
            Self::probe_view(rqctx, path_params, query_params).await?;
        info.try_into().map(HttpResponseOk).map_err(HttpError::from)
    }

    /// View instrumentation probe
    #[endpoint {
        method = GET,
        path = "/experimental/v1/probes/{probe}",
        tags = ["experimental"], // system/probes: only one tag is allowed
        versions = VERSION_DUAL_STACK_NICS..,
    }]
    async fn probe_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::ProbePath>,
        query_params: Query<params::ProjectSelector>,
    ) -> Result<HttpResponseOk<shared::ProbeInfo>, HttpError>;

    /// Create instrumentation probe
    #[endpoint {
        operation_id = "probe_create",
        method = POST,
        path = "/experimental/v1/probes",
        tags = ["experimental"], // system/probes: only one tag is allowed
        versions = ..VERSION_POOL_SELECTION_ENUMS,
    }]
    async fn v2026010300_probe_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_probe: TypedBody<v2026010300::ProbeCreate>,
    ) -> Result<HttpResponseCreated<Probe>, HttpError> {
        Self::probe_create(rqctx, query_params, new_probe.map(Into::into)).await
    }

    /// Create instrumentation probe
    #[endpoint {
        method = POST,
        path = "/experimental/v1/probes",
        tags = ["experimental"], // system/probes: only one tag is allowed
        versions = VERSION_POOL_SELECTION_ENUMS..,
    }]
    async fn probe_create(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        new_probe: TypedBody<params::ProbeCreate>,
    ) -> Result<HttpResponseCreated<Probe>, HttpError>;

    /// Delete instrumentation probe
    #[endpoint {
        method = DELETE,
        path = "/experimental/v1/probes/{probe}",
        tags = ["experimental"], // system/probes: only one tag is allowed
    }]
    async fn probe_delete(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::ProjectSelector>,
        path_params: Path<params::ProbePath>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    // Audit logging

    // See datastore/audit_log.rs for a more detailed explanation of why we sort
    // by time_completed.

    /// View audit log
    ///
    /// A single item in the audit log represents both the beginning and
    /// end of the logged operation (represented by `time_started` and
    /// `time_completed`) so that clients do not have to find multiple entries
    /// and match them up by request ID to get the full picture of an operation.
    /// Because timestamps may not be unique, entries have also have a unique
    /// `id` that can be used to deduplicate items fetched from overlapping
    /// time intervals.
    ///
    /// Audit log entries are designed to be immutable: once you see an entry,
    /// fetching it again will never get you a different result. The list is
    /// ordered by `time_completed`, not `time_started`. If you fetch the audit
    /// log for a time range that is fully in the past, the resulting list is
    /// guaranteed to be complete, i.e., fetching the same timespan again later
    /// will always produce the same set of entries.
    #[endpoint {
        method = GET,
        path = "/v1/system/audit-log",
        tags = ["system/audit-log"],
    }]
    async fn audit_log_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByTimeAndId<params::AuditLog>>,
    ) -> Result<HttpResponseOk<ResultsPage<views::AuditLogEntry>>, HttpError>;

    // Console API: logins

    /// SAML login console page (just a link to the IdP)
    #[endpoint {
        method = GET,
        path = "/login/{silo_name}/saml/{provider_name}",
        tags = ["login"],
        unpublished = true,
    }]
    async fn login_saml_begin(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::LoginToProviderPathParam>,
        query_params: Query<params::LoginUrlQuery>,
    ) -> Result<Response<Body>, HttpError>;

    /// Get a redirect straight to the IdP
    ///
    /// Console uses this to avoid having to ask the API anything about the IdP. It
    /// already knows the IdP name from the path, so it can just link to this path
    /// and rely on Nexus to redirect to the actual IdP.
    #[endpoint {
        method = GET,
        path = "/login/{silo_name}/saml/{provider_name}/redirect",
        tags = ["login"],
        unpublished = true,
    }]
    async fn login_saml_redirect(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::LoginToProviderPathParam>,
        query_params: Query<params::LoginUrlQuery>,
    ) -> Result<HttpResponseFound, HttpError>;

    /// Authenticate a user via SAML
    #[endpoint {
        method = POST,
        path = "/login/{silo_name}/saml/{provider_name}",
        tags = ["login"],
    }]
    async fn login_saml(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::LoginToProviderPathParam>,
        body_bytes: dropshot::UntypedBody,
    ) -> Result<HttpResponseSeeOther, HttpError>;

    #[endpoint {
        method = GET,
        path = "/login/{silo_name}/local",
        tags = ["login"],
        unpublished = true,
    }]
    async fn login_local_begin(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::LoginPath>,
        query_params: Query<params::LoginUrlQuery>,
    ) -> Result<Response<Body>, HttpError>;

    /// Authenticate a user via username and password
    #[endpoint {
        method = POST,
        path = "/v1/login/{silo_name}/local",
        tags = ["login"],
    }]
    async fn login_local(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::LoginPath>,
        credentials: TypedBody<params::UsernamePasswordCredentials>,
    ) -> Result<HttpResponseHeaders<HttpResponseUpdatedNoContent>, HttpError>;

    /// Log user out of web console by deleting session on client and server
    #[endpoint {
        // important for security that this be a POST despite the empty req body
        method = POST,
        path = "/v1/logout",
        tags = ["console-auth"],
    }]
    async fn logout(
        rqctx: RequestContext<Self::Context>,
        cookies: Cookies,
    ) -> Result<HttpResponseHeaders<HttpResponseUpdatedNoContent>, HttpError>;

    /// Redirect to a login page for the current Silo (if that can be determined)
    #[endpoint {
        method = GET,
        path = "/login",
        unpublished = true,
    }]
    async fn login_begin(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::LoginUrlQuery>,
    ) -> Result<HttpResponseFound, HttpError>;

    // Console API: Pages
    //
    // Dropshot does not have route match ranking and does not allow overlapping
    // route definitions, so we cannot use a catchall `/*` route for console pages
    // because it would overlap with the API routes definitions. So instead we have
    // to manually define more specific routes.
    #[endpoint {
        method = GET,
        path = "/projects/{path:.*}",
        unpublished = true,
    }]
    async fn console_projects(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RestPathParam>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/settings/{path:.*}",
        unpublished = true,
    }]
    async fn console_settings_page(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RestPathParam>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/system/{path:.*}",
        unpublished = true,
    }]
    async fn console_system_page(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RestPathParam>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/lookup/{path:.*}",
        unpublished = true,
    }]
    async fn console_lookup(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RestPathParam>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/",
        unpublished = true,
    }]
    async fn console_root(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/projects-new",
        unpublished = true,
    }]
    async fn console_projects_new(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/images",
        unpublished = true,
    }]
    async fn console_silo_images(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/utilization",
        unpublished = true,
    }]
    async fn console_silo_utilization(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/access",
        unpublished = true,
    }]
    async fn console_silo_access(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<Response<Body>, HttpError>;

    /// Serve a static asset
    #[endpoint {
        method = GET,
        path = "/assets/{path:.*}",
        unpublished = true,
    }]
    async fn asset(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::RestPathParam>,
    ) -> Result<Response<Body>, HttpError>;

    /// Start an OAuth 2.0 Device Authorization Grant
    ///
    /// This endpoint is designed to be accessed from an *unauthenticated*
    /// API client. It generates and records a `device_code` and `user_code`
    /// which must be verified and confirmed prior to a token being granted.
    #[endpoint {
        method = POST,
        path = "/device/auth",
        content_type = "application/x-www-form-urlencoded",
        tags = ["console-auth"],
    }]
    async fn device_auth_request(
        rqctx: RequestContext<Self::Context>,
        params: TypedBody<params::DeviceAuthRequest>,
    ) -> Result<Response<Body>, HttpError>;

    /// Verify an OAuth 2.0 Device Authorization Grant
    ///
    /// This endpoint should be accessed in a full user agent (e.g.,
    /// a browser). If the user is not logged in, we redirect them to
    /// the login page and use the `state` parameter to get them back
    /// here on completion. If they are logged in, serve up the console
    /// verification page so they can verify the user code.
    #[endpoint {
        method = GET,
        path = "/device/verify",
        unpublished = true,
    }]
    async fn device_auth_verify(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<Response<Body>, HttpError>;

    #[endpoint {
        method = GET,
        path = "/device/success",
        unpublished = true,
    }]
    async fn device_auth_success(
        rqctx: RequestContext<Self::Context>,
    ) -> Result<Response<Body>, HttpError>;

    /// Confirm an OAuth 2.0 Device Authorization Grant
    ///
    /// This endpoint is designed to be accessed by the user agent (browser),
    /// not the client requesting the token. So we do not actually return the
    /// token here; it will be returned in response to the poll on `/device/token`.
    ///
    /// Some special logic applies when authenticating this request with an
    /// existing device token instead of a console session: the requested
    /// TTL must not produce an expiration time later than the authenticating
    /// token's expiration. If no TTL was specified in the initial grant
    /// request, the expiration will be the lesser of the silo max and the
    /// authenticating token's expiration time. To get the longest allowed
    /// lifetime, omit the TTL and authenticate with a web console session.
    #[endpoint {
        method = POST,
        path = "/device/confirm",
        tags = ["console-auth"],
    }]
    async fn device_auth_confirm(
        rqctx: RequestContext<Self::Context>,
        params: TypedBody<params::DeviceAuthVerify>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// Request a device access token
    ///
    /// This endpoint should be polled by the client until the user code
    /// is verified and the grant is confirmed.
    #[endpoint {
        method = POST,
        path = "/device/token",
        content_type = "application/x-www-form-urlencoded",
        tags = ["console-auth"],
    }]
    async fn device_access_token(
        rqctx: RequestContext<Self::Context>,
        params: TypedBody<params::DeviceAccessTokenRequest>,
    ) -> Result<Response<Body>, HttpError>;

    // Alerts

    /// List alert classes
    #[endpoint {
        method = GET,
        path = "/v1/alert-classes",
        tags = ["system/alerts"],
    }]
    async fn alert_class_list(
        rqctx: RequestContext<Self::Context>,
        pag_params: Query<
            PaginationParams<EmptyScanParams, params::AlertClassPage>,
        >,
        filter: Query<params::AlertClassFilter>,
    ) -> Result<HttpResponseOk<ResultsPage<views::AlertClass>>, HttpError>;

    /// List alert receivers
    #[endpoint {
        method = GET,
        path = "/v1/alert-receivers",
        tags = ["system/alerts"],
    }]
    async fn alert_receiver_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<PaginatedByNameOrId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::AlertReceiver>>, HttpError>;

    /// Fetch alert receiver
    #[endpoint {
        method = GET,
        path = "/v1/alert-receivers/{receiver}",
        tags = ["system/alerts"],
    }]
    async fn alert_receiver_view(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AlertReceiverSelector>,
    ) -> Result<HttpResponseOk<views::AlertReceiver>, HttpError>;

    /// Delete alert receiver
    #[endpoint {
        method = DELETE,
        path = "/v1/alert-receivers/{receiver}",
        tags = ["system/alerts"],
    }]
    async fn alert_receiver_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AlertReceiverSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// Add alert receiver subscription
    #[endpoint {
        method = POST,
        path = "/v1/alert-receivers/{receiver}/subscriptions",
        tags = ["system/alerts"],
    }]
    async fn alert_receiver_subscription_add(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AlertReceiverSelector>,
        params: TypedBody<params::AlertSubscriptionCreate>,
    ) -> Result<HttpResponseCreated<views::AlertSubscriptionCreated>, HttpError>;

    /// Remove alert receiver subscription
    #[endpoint {
        method = DELETE,
        path = "/v1/alert-receivers/{receiver}/subscriptions/{subscription}",
        tags = ["system/alerts"],
    }]
    async fn alert_receiver_subscription_remove(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AlertSubscriptionSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;

    /// List delivery attempts to alert receiver
    ///
    /// Optional query parameters to this endpoint may be used to filter
    /// deliveries by state. If none of the `failed`, `pending` or `delivered`
    /// query parameters are present, all deliveries are returned. If one or
    /// more of these parameters are provided, only those which are set to
    /// "true" are included in the response.
    #[endpoint {
        method = GET,
        path = "/v1/alert-receivers/{receiver}/deliveries",
        tags = ["system/alerts"],
    }]
    async fn alert_delivery_list(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AlertReceiverSelector>,
        state_filter: Query<params::AlertDeliveryStateFilter>,
        pagination: Query<PaginatedByTimeAndId>,
    ) -> Result<HttpResponseOk<ResultsPage<views::AlertDelivery>>, HttpError>;

    /// Send liveness probe to alert receiver
    ///
    /// This endpoint synchronously sends a liveness probe to the selected alert
    /// receiver. The response message describes the outcome of the probe:
    /// either the successful response (as appropriate), or indication of why
    /// the probe failed.
    ///
    /// The result of the probe is represented as an `AlertDelivery` model.
    /// Details relating to the status of the probe depend on the alert delivery
    /// mechanism, and are included in the `AlertDeliveryAttempts` model. For
    /// example, webhook receiver liveness probes include the HTTP status code
    /// returned by the receiver endpoint.
    ///
    /// Note that the response status is `200 OK` as long as a probe request was
    /// able to be sent to the receiver endpoint. If an HTTP-based receiver,
    /// such as a webhook, responds to the another status code, including an
    /// error, this will be indicated by the response body, *not* the status of
    /// the response.
    ///
    /// The `resend` query parameter can be used to request re-delivery of
    /// failed events if the liveness probe succeeds. If it is set to true and
    /// the liveness probe succeeds, any alerts for which delivery to this
    /// receiver has failed will be queued for re-delivery.
    #[endpoint {
        method = POST,
        path = "/v1/alert-receivers/{receiver}/probe",
        tags = ["system/alerts"],
    }]
    async fn alert_receiver_probe(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AlertReceiverSelector>,
        query_params: Query<params::AlertReceiverProbe>,
    ) -> Result<HttpResponseOk<views::AlertProbeResult>, HttpError>;

    /// Request re-delivery of alert
    #[endpoint {
        method = POST,
        path = "/v1/alerts/{alert_id}/resend",
        tags = ["system/alerts"],
    }]
    async fn alert_delivery_resend(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AlertSelector>,
        receiver: Query<params::AlertReceiverSelector>,
    ) -> Result<HttpResponseCreated<views::AlertDeliveryId>, HttpError>;

    // ALERTS: WEBHOOKS

    /// Create webhook receiver
    #[endpoint {
        method = POST,
        path = "/v1/webhook-receivers",
        tags = ["system/alerts"],
    }]
    async fn webhook_receiver_create(
        rqctx: RequestContext<Self::Context>,
        params: TypedBody<params::WebhookCreate>,
    ) -> Result<HttpResponseCreated<views::WebhookReceiver>, HttpError>;

    /// Update webhook receiver
    ///
    /// Note that receiver secrets are NOT added or removed using this endpoint.
    /// Instead, use the `/v1/webhooks/{secrets}/?receiver={receiver}` endpoint
    /// to add and remove secrets.
    #[endpoint {
        method = PUT,
        path = "/v1/webhook-receivers/{receiver}",
        tags = ["system/alerts"],
    }]
    async fn webhook_receiver_update(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::AlertReceiverSelector>,
        params: TypedBody<params::WebhookReceiverUpdate>,
    ) -> Result<HttpResponseUpdatedNoContent, HttpError>;

    /// List webhook receiver secret IDs
    #[endpoint {
        method = GET,
        path = "/v1/webhook-secrets",
        tags = ["system/alerts"],
    }]
    async fn webhook_secrets_list(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::AlertReceiverSelector>,
    ) -> Result<HttpResponseOk<views::WebhookSecrets>, HttpError>;

    /// Add secret to webhook receiver
    #[endpoint {
        method = POST,
        path = "/v1/webhook-secrets",
        tags = ["system/alerts"],
    }]
    async fn webhook_secrets_add(
        rqctx: RequestContext<Self::Context>,
        query_params: Query<params::AlertReceiverSelector>,
        params: TypedBody<params::WebhookSecretCreate>,
    ) -> Result<HttpResponseCreated<views::WebhookSecret>, HttpError>;

    /// Remove secret from webhook receiver
    #[endpoint {
        method = DELETE,
        path = "/v1/webhook-secrets/{secret_id}",
        tags = ["system/alerts"],
    }]
    async fn webhook_secrets_delete(
        rqctx: RequestContext<Self::Context>,
        path_params: Path<params::WebhookSecretSelector>,
    ) -> Result<HttpResponseDeleted, HttpError>;
}

/// Perform extra validations on the OpenAPI document, and generate the
/// nexus_tags.txt file.
pub fn validate_api(spec: &OpenAPI, mut cx: ValidationContext<'_>) {
    let blessed = cx
        .is_blessed()
        .expect("this is a versioned API so is_blessed should always be Some");

    // There are two parts to this function:
    //
    // 1. Perform validation on the OpenAPI document.
    // 2. Generate the nexus_tags.txt file.
    //
    // Step 1 should only be performed on non-blessed versions. That's because
    // blessed versions are immutable, and if new checks are added in the
    // future, we don't want old API versions to be affected.
    //
    // nexus_tags.txt is unversioned, so step 2 should only be performed on the
    // latest version, whether or not it's blessed.

    if !blessed {
        validate_api_doc(spec, &mut cx);
    }

    // nexus_tags.txt is unversioned, so only write it out for the latest
    // version (whether it's blessed or not).
    if cx.is_latest() {
        generate_tags_file(spec, &mut cx);
    }
}

fn validate_api_doc(spec: &OpenAPI, cx: &mut ValidationContext<'_>) {
    if spec.openapi != "3.0.3" {
        cx.report_error(anyhow!(
            "Expected OpenAPI version to be 3.0.3, found {}",
            spec.openapi,
        ));
    }
    if spec.info.title != "Oxide Region API" {
        cx.report_error(anyhow!(
            "Expected OpenAPI version to be 'Oxide Region API', found '{}'",
            spec.info.title,
        ));
    }

    // Spot check a couple of items.
    if spec.paths.paths.is_empty() {
        cx.report_error(anyhow!("Expected at least one path in the spec"));
    }
    if spec.paths.paths.get("/v1/projects").is_none() {
        cx.report_error(anyhow!("Expected a path for /v1/projects"));
    }

    for (_path, _method, op) in spec.operations() {
        // Make sure each operation has exactly one tag. Note, we intentionally
        // do this before validating the OpenAPI output as fixing an error here
        // would necessitate refreshing the spec file again.
        if op.tags.len() != 1 {
            cx.report_error(anyhow!(
                "operation '{}' has {} tags rather than 1",
                op.operation_id.as_ref().unwrap(),
                op.tags.len()
            ));
        }

        // Every non-hidden endpoint must have a summary
        if op.tags.contains(&"console-auth".to_string()) && op.summary.is_none()
        {
            cx.report_error(anyhow!(
                "operation '{}' is missing a summary doc comment",
                op.operation_id.as_ref().unwrap()
            ));
        }
    }
}

fn generate_tags_file(spec: &OpenAPI, cx: &mut ValidationContext<'_>) {
    // Construct a string that helps us identify the organization of tags and
    // operations.
    let mut ops_by_tag =
        BTreeMap::<String, Vec<(String, String, String)>>::new();

    for (path, method, op) in spec.operations() {
        // If an operation doesn't have exactly one tag, skip generating the
        // tags file entirely. (Validation above catches this case).
        if op.tags.len() != 1 {
            return;
        }

        ops_by_tag
            .entry(op.tags.first().unwrap().to_string())
            .or_default()
            .push((
                op.operation_id.as_ref().unwrap().to_string(),
                method.to_string().to_uppercase(),
                path.to_string(),
            ));
    }

    let mut tags = String::new();
    for (tag, mut ops) in ops_by_tag {
        ops.sort();
        tags.push_str(&format!(r#"API operations found with tag "{}""#, tag));
        tags.push_str(&format!(
            "\n{:40} {:8} {}\n",
            "OPERATION ID", "METHOD", "URL PATH"
        ));
        for (operation_id, method, path) in ops {
            tags.push_str(&format!(
                "{:40} {:8} {}\n",
                operation_id, method, path
            ));
        }
        tags.push('\n');
    }

    // When this fails, verify that operations on which you're adding,
    // renaming, or changing the tags are what you intend.
    cx.record_file_contents(
        "nexus/external-api/output/nexus_tags.txt",
        tags.into_bytes(),
    );
}

pub type IpPoolRangePaginationParams =
    PaginationParams<EmptyScanParams, IpNetwork>;

/// Type used to paginate request to list timeseries schema
pub type TimeseriesSchemaPaginationParams =
    PaginationParams<EmptyScanParams, oximeter_types::TimeseriesName>;