Integrate MASQUE with Galactic Edge provider attachments #975

Activity

1. privateip

   added

   enhancementNew feature or requestNew feature or request

   on Oct 22, 2026
2. privateip

   added a parent issue on Oct 22, 2026

   • MASQUE Connector for gVPC #970
3. privateip

   changed the title [-]MASQUE: implement host-managed gVPC attachment lifecycle[/-] [+]Implement host-managed gVPC attachment lifecycle[/+] on Oct 22, 2026
4. privateip

   added the

   Task

   issue type on Oct 22, 2026
5. privateip

   changed the title [-]Implement host-managed gVPC attachment lifecycle[/-] [+]Integrate MASQUE with Galactic Edge provider attachments[/+] on Oct 25, 2026
6. privateip

   self-assigned this

   on Oct 27, 2026
7. privateip commented on Oct 27, 2026

   

   privateip

   on Oct 27, 2026

   CollaboratorAuthor

   More actions

   Verdict: valid. Main has no MASQUE provider adapter yet (checked at dbbc388).

   What exists today:

   • internal/edge/connectip defines the Admission, Lease and PacketBackend interfaces and an HTTP/3 server. Its package docs say it is not a production admission authority or attachment controller.
   • internal/edge/provider has the instance, attachment and route naming and lifecycle helpers. No MASQUE code calls them.
   • The only code that builds a connectip server or TUN backend is the interoperability harness in tests/connectipinterop.
   • test(edge): Prove MASQUE packet access in the lab #1140 (for Prove MASQUE packet attachments on the Galactic Edge foundation #974) adds a test-only fixture provider under tests/edgeconformance/masqueprovider. It reads static credentials and service UIDs from a config file. It shares one TUN backend per service across all of that service's sessions, and a gate on its instance lease is the only per-session check. It is not an adapter that production code can use.

   What is missing: an importable adapter that requests and checks the pod's instance and per-service attachments, opens only the device that the attachment's status names, sets Ready, counts each attachment's users so drain and cancellation are safe, and binds every session to its VPC, service, attachment, route and current authority. #980 (HTTP/3) and #981 (HTTP/2) would both use it.
8. privateip commented on Oct 27, 2026

   

   privateip

   on Oct 27, 2026

   CollaboratorAuthor

   More actions

   Plan (approved)

   Root cause. Nothing in production implements connectip.Admission, Lease or PacketBackend. The only implementation is the #974 test fixture in #1140.

   Fix. Add a library package, internal/edge/masque, that both transports (#980, #981) import.

   1. Instance. Register the pod's EdgeInstance with provider.CreateInstance and hold its Lease through claim.Instance over provider.InstanceStore. One renewal worker owns the Lease. No packet path or session lock is held during its API calls.
   2. Attachments. Count the users of each per-service attachment.
      • Acquire it with provider.CreateAttachment, requesting v1alpha1, PacketAccess/v1 and PrefixReachability/v1.
      • Read it uncached and check its immutable pod, service UID, instance, provider and status VPC.
      • Wait for Programmed, open only status.packetDevice, then set Ready.
      • A mismatch, refusal, missing device or Draining attachment fails closed with Ready=False.
      • When the last user leaves, close the device, then delete the attachment with a UID precondition and wait for core's finalizer. The adapter never touches host state.
   3. Route gate. Claim the connector's /96 with provider.NewRoute/provider.Claim. A session opens only after core has accepted the claim for this attachment and Lease epoch. The adapter releases only the epoch it still holds.
   4. Admission and PacketBackend. An Authorizer interface returns the trusted grant: connector, service name/UID, VPC UID, /96, routes and deadline. Implement admission, credential expiry and access revocation #977 supplies the real authority. Each session is bound to the full UID and epoch tuple. Every packet, in both directions, is checked against the Lease deadline, the grant deadline and attachment currency. Closing one session removes only its own registration.
   5. Restart. The adapter rebuilds its state from the API and adopts its own attachments by derived name and UID. It never restores forwarding permission from local memory.

   Tests

   • Unit tests with a fake client: a forged or taken name, a refused attachment, a wrong VPC or service, a missing device, a draining attachment, a stale-UID delete, and two sessions on one attachment where cancelling one leaves the other's device, claim and stream intact.
   • envtest against core's attachment and route reconcilers.
   • The Prove MASQUE packet attachments on the Galactic Edge foundation #974 fixture becomes a thin wrapper over the adapter. TestMASQUE gains rows for process restart, shared-attachment cancellation and stale delete, run in the lab against core images built from main.

   Docs. Setup, readiness, drain and cleanup, plus evidence for each #989 row that #975 owns (A01, A03, A09, A11, A15, C04, C07, C08).

   Out of scope. Connector session generations and deadlines (#976), the credential authority (#977), the /96 ledger (#978), source and policy checks (#979), the runnable service (#980) and the HTTP/2 transport (#981). The adapter does not depend on the transport. Two concurrent sessions sharing one attachment cover the shared-attachment criterion.

   Risk. This is new code with no deployed caller. Revert to roll back.

   Delivery. Two stacked PRs on #1140: the adapter with its tests, then the fixture migration, lab rows and docs.
9. privateip commented on Oct 27, 2026

   

   privateip

   on Oct 27, 2026

   CollaboratorAuthor

   More actions

   The fix is up for review as a two-PR stack:

   1. feat(edge): Add the MASQUE provider adapter #1151 adds internal/edge/masque, the provider adapter. It has unit tests and an envtest that runs the adapter against core's attachment and route controllers, the RBAC that ships in config/ and the admission policies.
   2. test(edge): Run the MASQUE lab fixture on the provider adapter #1152 (draft) moves the Prove MASQUE packet attachments on the Galactic Edge foundation #974 lab fixture onto the adapter, adds lab rows and documents setup, readiness, drain and cleanup.

   Change from the plan: a connector's second request is now refused at admission, before any preparation, while its first request is open. Replacing a connector's open request is #976's scope.

   #1152 stays a draft until task verify:masque-conformance runs in the lab.
10. privateip

    closed this as completedin #1152on Oct 27, 2026