docs: MASQUE Gateway Architecture Design - #3
Draft
scotwells wants to merge 1 commit into
Draft
Conversation
This document describes the MASQUE Gateway architecture for bridging external clients to the SRv6-based Galactic VPC fabric. Key concepts: - MASQUE as the protocol standard (IETF RFC 9484 CONNECT-IP) - Iroh for connectivity (NAT traversal, hole punching, relays) - SRv6 as the VPC underlay - Convergence path: Iroh relays evolving to speak MASQUE Aligns with the Datum Connectors proposal, extending it with: - ConnectorAttachment for VPC binding - VPCIngressPoint for gateway configuration - VPCAccessPolicy for authorization Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
0xmc
reviewed
May 27, 2026
|
|
||
| ## Resource Model | ||
|
|
||
| Aligned with the [Datum Connectors proposal](../../../enhancements/enhancements/networking/connectors/initial-proposal/README.md). |
Contributor
There was a problem hiding this comment.
This comment was marked as low quality.
This comment was marked as low quality.
privateip
added a commit
that referenced
this pull request
Aug 17, 2026
Open Decision 4 (Phase 4's rollback-risk callout) offered three candidate fixes for the BGPAdvertisement wrongful-deletion hole and left the pick open. Resolved: fix #1, narrowing advertisementCreated's assignment (bgp.go:412) to gate on op == controllerutil.OperationResultCreated, mirroring vrfInstanceCreated's existing pattern (bgp.go:353-362) exactly. Verified by reading the actual code, not just the two candidates in isolation: - advertisementCreated has exactly one setter (bgp.go:412) and one reader (resourceTracker.cleanup, resource.go:92) across the whole repo. No DEL/CHECK/GC path depends on its current over-broad "true on any successful write" semantics, so narrowing it is a ~2-line diff with zero other blast radius. - Fix #3 ("cleanup never deletes an only-updated advertisement") needs the identical op-result signal captured at the same CreateOrUpdate call site to know create-vs-update after the fact - any real implementation of it collapses into fix #1 byte-for-byte. The only way to make it a distinct change is a second, redundant field nothing else would consume. - Fix #2 (fold EndpointSlice publish into publishBGPState's retry closure) doesn't close the gap by itself: cmdAdd's deferred rollback fires on any non-nil error regardless of which step produced it, so a failure there still hits the same wrongful-deletion path unless advertisementCreated's semantics are also fixed. Reasonable as a complementary retry-robustness improvement, but not a substitute, and not adopted here. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
privateip
added a commit
that referenced
this pull request
Aug 18, 2026
Open Decision 4 (Phase 4's rollback-risk callout) offered three candidate fixes for the BGPAdvertisement wrongful-deletion hole and left the pick open. Resolved: fix #1, narrowing advertisementCreated's assignment (bgp.go:412) to gate on op == controllerutil.OperationResultCreated, mirroring vrfInstanceCreated's existing pattern (bgp.go:353-362) exactly. Verified by reading the actual code, not just the two candidates in isolation: - advertisementCreated has exactly one setter (bgp.go:412) and one reader (resourceTracker.cleanup, resource.go:92) across the whole repo. No DEL/CHECK/GC path depends on its current over-broad "true on any successful write" semantics, so narrowing it is a ~2-line diff with zero other blast radius. - Fix #3 ("cleanup never deletes an only-updated advertisement") needs the identical op-result signal captured at the same CreateOrUpdate call site to know create-vs-update after the fact - any real implementation of it collapses into fix #1 byte-for-byte. The only way to make it a distinct change is a second, redundant field nothing else would consume. - Fix #2 (fold EndpointSlice publish into publishBGPState's retry closure) doesn't close the gap by itself: cmdAdd's deferred rollback fires on any non-nil error regardless of which step produced it, so a failure there still hits the same wrongful-deletion path unless advertisementCreated's semantics are also fixed. Reasonable as a complementary retry-robustness improvement, but not a substitute, and not adopted here. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds the MASQUE Gateway architecture design document, describing how external clients connect to SRv6-based Galactic VPCs.
Key Concepts
Design Philosophy
Bet on the future, bridge to the present.
Rather than choosing between Iroh and MASQUE, the architecture leverages both:
New Resources (extending Connectors proposal)
ConnectorAttachmentVPCIngressPointVPCAccessPolicyOpen Questions
🤖 Generated with Claude Code