Rename params::AddressSelector to params::AddressAllocator in the external API (#9669)

From discussion in
#9638 (comment),
we decided that `AddressSelector` is a bit of a misnomer in our current
scheme, where "selector" implies filtering/fetching from existing
resources. We'll use `AddressAllocator` instead, which better describes
the action of reserving/assigning a floating IP address from a pool.

I've also done a bit of refactoring here to be more RFD 619 friendly.
Before this PR, we had a series of `FloatingIpCreate` versions that each
had `From` or `TryFrom` conversions directly to the latest API version
in "big step" style. This becomes an _O(n)^2_ problem to maintain over
time. Instead, in this PR, we convert to "small step" style, where each
older version of `FloatingIpCreate` converts to the next newer version.
In the terms of the RFD, we "[hop through intermediate
versions](https://rfd.shared.oxide.computer/rfd/0619#determinations-one-prior-version)."
This ensures that the next time we change `FloatingIpCreate`, we only
need to introduce one new conversion, rather than update all older
conversions.

I've added proptests to make our expectations of the conversion behavior
more explicit and prevent regressions.

Author: mergeconflict

Cargo.lock

@@ -31,3 +31,7 @@ scim2-rs.workspace = true
 serde.workspace = true
 tufaceous-artifact.workspace = true
 uuid.workspace = true
+
+[dev-dependencies]
+proptest.workspace = true
+test-strategy.workspace = true

nexus/external-api/Cargo.toml

@@ -41,6 +41,10 @@ mod v2025122300;
 mod v2026010100;
 mod v2026010300;
 mod v2026010500;
+mod v2026011501;
+
+#[cfg(test)]
+mod test_utils;
 
 api_versions!([
     // API versions are in the format YYYYMMDDNN.0.0, defined below as
@@ -70,6 +74,7 @@ api_versions!([
     // |  date-based version should be at the top of the list.
     // v
     // (next_yyyymmddnn, IDENT),
+    (2026011600, RENAME_ADDRESS_SELECTOR_TO_ADDRESS_ALLOCATOR),
     (2026011501, AUDIT_LOG_CREDENTIAL_ID),
     (2026011500, AUDIT_LOG_AUTH_METHOD_ENUM),
     (2026011300, DOC_LINT_SUMMARY_TRAILING_PERIOD),
@@ -1298,10 +1303,12 @@ pub trait NexusExternalApi {
         query_params: Query<params::ProjectSelector>,
         floating_params: TypedBody<v2025121200::FloatingIpCreate>,
     ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
-        Self::floating_ip_create(
+        let floating_params =
+            floating_params.map(v2026010300::FloatingIpCreate::from);
+        Self::v2026010300_floating_ip_create(
             rqctx,
             query_params,
-            floating_params.map(Into::into),
+            floating_params,
         )
         .await
     }
@@ -1320,16 +1327,43 @@ pub trait NexusExternalApi {
         query_params: Query<params::ProjectSelector>,
         floating_params: TypedBody<v2026010300::FloatingIpCreate>,
     ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
-        let floating_params = floating_params.try_map(TryInto::try_into)?;
-        Self::floating_ip_create(rqctx, query_params, floating_params).await
+        let floating_params =
+            floating_params.try_map(v2026011501::FloatingIpCreate::try_from)?;
+        Self::v2026011501_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..,
+        versions = VERSION_POOL_SELECTION_ENUMS..VERSION_RENAME_ADDRESS_SELECTOR_TO_ADDRESS_ALLOCATOR,
+    }]
+    async fn v2026011501_floating_ip_create(
+        rqctx: RequestContext<Self::Context>,
+        query_params: Query<params::ProjectSelector>,
+        floating_params: TypedBody<v2026011501::FloatingIpCreate>,
+    ) -> Result<HttpResponseCreated<views::FloatingIp>, HttpError> {
+        Self::floating_ip_create(
+            rqctx,
+            query_params,
+            floating_params.map(Into::into),
+        )
+        .await
+    }
+
+    /// Create floating IP
+    #[endpoint {
+        method = POST,
+        path = "/v1/floating-ips",
+        tags = ["floating-ips"],
+        versions = VERSION_RENAME_ADDRESS_SELECTOR_TO_ADDRESS_ALLOCATOR..,
     }]
     async fn floating_ip_create(
         rqctx: RequestContext<Self::Context>,

nexus/external-api/src/lib.rs

@@ -0,0 +1,75 @@
+// 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/.
+
+//! Common proptest strategies for versioned API type tests.
+//!
+//! This module provides reusable strategies for generating test data
+//! used in property-based tests across version modules.
+
+use nexus_types::external_api::params;
+use omicron_common::api::external::{
+    IdentityMetadataCreateParams, IpVersion, Name, NameOrId,
+};
+use proptest::prelude::*;
+use std::net::IpAddr;
+use uuid::Uuid;
+
+/// Strategy for generating valid `Name` values.
+///
+/// Per RFD 4, names must be 1-63 characters and match the regex
+/// `[a-z]([-a-z0-9]*[a-z0-9])?`. We use `{0,61}` instead of `*` to
+/// bound generation length and avoid filtering out long strings.
+pub fn name_strategy() -> impl Strategy<Value = Name> {
+    "[a-z]([-a-z0-9]{0,61}[a-z0-9])?"
+        .prop_filter_map("valid name", |s| s.parse::<Name>().ok())
+}
+
+/// Strategy for generating `NameOrId` values.
+pub fn name_or_id_strategy() -> impl Strategy<Value = NameOrId> {
+    prop_oneof![
+        name_strategy().prop_map(NameOrId::Name),
+        any::<u128>().prop_map(|n| NameOrId::Id(Uuid::from_u128(n))),
+    ]
+}
+
+/// Strategy for generating `IpVersion` values.
+pub fn ip_version_strategy() -> impl Strategy<Value = IpVersion> {
+    prop_oneof![Just(IpVersion::V4), Just(IpVersion::V6)]
+}
+
+/// Strategy for generating `PoolSelector` values.
+///
+/// Generates one of:
+/// - `Explicit { pool }`: Use a specific pool identified by name or ID
+/// - `Auto { ip_version }`: Use the silo's default pool, optionally filtered
+///   by IP version (IPv4/IPv6)
+pub fn pool_selector_strategy() -> impl Strategy<Value = params::PoolSelector> {
+    prop_oneof![
+        name_or_id_strategy()
+            .prop_map(|pool| params::PoolSelector::Explicit { pool }),
+        proptest::option::of(ip_version_strategy())
+            .prop_map(|ip_version| params::PoolSelector::Auto { ip_version }),
+    ]
+}
+
+/// Strategy for generating `IdentityMetadataCreateParams` values.
+///
+/// Description is limited to 512 characters in the database.
+pub fn identity_strategy() -> impl Strategy<Value = IdentityMetadataCreateParams>
+{
+    (name_strategy(), ".{0,512}").prop_map(|(name, description)| {
+        IdentityMetadataCreateParams { name, description }
+    })
+}
+
+/// Strategy for generating optional IP addresses.
+pub fn optional_ip_strategy() -> impl Strategy<Value = Option<IpAddr>> {
+    proptest::option::of(any::<IpAddr>())
+}
+
+/// Strategy for generating optional `NameOrId` values.
+pub fn optional_name_or_id_strategy() -> impl Strategy<Value = Option<NameOrId>>
+{
+    proptest::option::of(name_or_id_strategy())
+}

nexus/external-api/src/test_utils.rs

@@ -120,22 +120,15 @@ pub struct FloatingIpCreate {
     pub pool: Option<external::NameOrId>,
 }
 
-// Converts directly to params::FloatingIpCreate using AddressSelector
-impl From<FloatingIpCreate> for params::FloatingIpCreate {
-    fn from(old: FloatingIpCreate) -> params::FloatingIpCreate {
-        let address_selector = match (old.ip, old.pool) {
-            // Explicit IP address provided
-            (Some(ip), pool) => params::AddressSelector::Explicit { ip, pool },
-            // Allocate from specified pool
-            (None, Some(pool)) => params::AddressSelector::Auto {
-                pool_selector: params::PoolSelector::Explicit { pool },
-            },
-            // Allocate from default pool
-            (None, None) => params::AddressSelector::Auto {
-                pool_selector: params::PoolSelector::Auto { ip_version: None },
-            },
-        };
-        params::FloatingIpCreate { identity: old.identity, address_selector }
+// Converts to v2026010300::FloatingIpCreate (adds ip_version: None)
+impl From<FloatingIpCreate> for v2026010300::FloatingIpCreate {
+    fn from(old: FloatingIpCreate) -> v2026010300::FloatingIpCreate {
+        v2026010300::FloatingIpCreate {
+            identity: old.identity,
+            ip: old.ip,
+            pool: old.pool,
+            ip_version: None,
+        }
     }
 }
 
@@ -209,3 +202,46 @@ impl From<InstanceCreate> for v2026010100::InstanceCreate {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_utils::{
+        identity_strategy, optional_ip_strategy, optional_name_or_id_strategy,
+    };
+    use proptest::prelude::*;
+    use test_strategy::proptest;
+
+    fn floating_ip_create_strategy() -> impl Strategy<Value = FloatingIpCreate>
+    {
+        (
+            identity_strategy(),
+            optional_ip_strategy(),
+            optional_name_or_id_strategy(),
+        )
+            .prop_map(|(identity, ip, pool)| FloatingIpCreate {
+                identity,
+                ip,
+                pool,
+            })
+    }
+
+    /// Verifies that the conversion from v2025121200::FloatingIpCreate to
+    /// v2026010300::FloatingIpCreate preserves all existing fields, and that
+    /// the ip_version field is set to None.
+    #[proptest]
+    fn floating_ip_create_converts_correctly(
+        #[strategy(floating_ip_create_strategy())] input: FloatingIpCreate,
+    ) {
+        let output: v2026010300::FloatingIpCreate = input.clone().into();
+
+        prop_assert_eq!(input.identity.name, output.identity.name);
+        prop_assert_eq!(
+            input.identity.description,
+            output.identity.description
+        );
+        prop_assert_eq!(input.ip, output.ip);
+        prop_assert_eq!(input.pool, output.pool);
+        prop_assert_eq!(output.ip_version, None);
+    }
+}