Skip to content

[fix, mcast] update mcast public docs formatting #9623

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zeeshanlakhani merged 1 commit into from
Jan 12, 2026
Merged

[fix, mcast] update mcast public docs formatting #9623

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 10 additions & 35 deletions nexus/external-api/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ api_versions!([
// | date-based version should be at the top of the list.
// v
// (next_yyyymmddnn, IDENT),
(2026011100, MULTICAST_JOIN_LEAVE_DOCS),
Copy link
Contributor

@ahl ahl Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is a new version required? @sunshowers I thought a trivial change would be ... fine? or is that more of a future? thanks!

Copy link
Collaborator Author

@zeeshanlakhani zeeshanlakhani Jan 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From what I can tell, cargo xtask openapi generate doesn't pick up doc changes (even on non-versioned delegation changes), unless the version is bumped. Not sure if there's a way around this using the xtask and our blessed version approach.

Copy link
Contributor

@sunshowers sunshowers Jan 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, you need to force a version bump in this situation, because we treat blessed versions as immutable. (Either the current or an upcoming dropshot-api-manager will force you to make a bump in this situation.)

BTW RFD 634 was written in part so that people don't feel bad about adding new versions (and seeing a 30k line diff or similar)

Copy link
Collaborator Author

@zeeshanlakhani zeeshanlakhani Jan 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW RFD 634 was written in part so that people don't feel bad about adding new versions (and seeing a 30k line diff or similar)

Right. Trying not to feel bad (as I've been doing it alot :)).

Copy link
Contributor

@ahl ahl Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you. Don't we get paid based on LOC?

(2026010800, MULTICAST_IMPLICIT_LIFECYCLE_UPDATES),
(2026010500, POOL_SELECTION_ENUMS),
(2026010300, DUAL_STACK_NICS),
Expand Down Expand Up @@ -3420,32 +3421,16 @@ pub trait NexusExternalApi {
query_params: Query<params::OptionalProjectSelector>,
) -> Result<HttpResponseCreated<v2025121200::MulticastGroupMember>, HttpError>;

/// Join a multicast group.
///
/// This is functionally equivalent to adding the instance via the group's
/// member management endpoint or updating the instance's `multicast_groups`
/// field. All approaches modify the same membership and trigger reconciliation.
/// Join a multicast group by name, IP address, or UUID.
///
/// Authorization: requires Modify on the instance identified in the URL path
/// (checked first) and Read on the multicast group. Checking instance permission
/// first prevents creating orphaned groups when the instance check fails.
/// 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.
///
/// Group Identification: Groups can be referenced by name, IP address,
/// or UUID. All three are fleet-wide unique identifiers:
/// - By name: If group doesn't exist, it's implicitly created with an
/// auto-allocated IP from a multicast pool linked to the caller's silo.
/// Pool selection prefers the default pool; if none, selects alphabetically.
/// - By IP: If group doesn't exist, it's implicitly created using that
/// IP. The pool is determined by which pool contains the IP.
/// - By UUID: Group must already exist.
///
/// Source IP filtering:
/// - Duplicate IPs in the request are automatically deduplicated.
/// - Maximum of 64 source IPs allowed (per RFC 3376, IGMPv3).
/// - ASM: Sources are optional. Providing sources enables source
/// filtering via IGMPv3/MLDv2 even for ASM addresses.
/// - SSM: Sources are required. SSM addresses (232.0.0.0/8 for IPv4,
/// ff3x::/32 for IPv6) must have at least one source specified.
/// 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}",
Expand Down Expand Up @@ -3477,17 +3462,7 @@ pub trait NexusExternalApi {
query_params: Query<params::OptionalProjectSelector>,
) -> Result<HttpResponseDeleted, HttpError>;

/// Leave a multicast group.
///
/// The group can be specified by name, UUID, or multicast IP address.
/// All three are fleet-wide unique identifiers.
///
/// This is functionally equivalent to removing the instance via the group's
/// member management endpoint or updating the instance's `multicast_groups`
/// field. All approaches modify the same membership and trigger reconciliation.
///
/// Authorization: requires Modify on the instance (checked first) and Read
/// on the multicast group.
/// Leave a multicast group by name, IP address, or UUID.
#[endpoint {
method = DELETE,
path = "/v1/instances/{instance}/multicast-groups/{multicast_group}",
Expand Down
Loading
Loading