Repository navigation
feat: Add the Galactic Worker service API and reconciliation core - #1446
Merged
Merged
Conversation
Galactic Worker resolves every destination by comparing node locators, and must read them from the same trusted source as the locator's local route: the node's BGPRouter Block and Node-ID. The derivation lived unexported in internal/installer, which Worker should not import. Move it to internal/nodelocator.Prefix and keep the installer's nodeLocatorPrefix as a thin wrapper, so its behavior and tests stay as they are. Co-Authored-By: Claude <claude@anthropic.com>
Service agents need one published interface to Galactic Worker. This adds the galactic.worker.v1alpha1 protobuf service from docs/worker/contract.md (GetCapabilities, Request, Update, Observe and Release) and the contract's names: capabilities, conditions, refusal and status reasons, the error domain and the session metadata key. The proto lives in api/galactic/worker/v1alpha1 because buf's STANDARD lint requires the directory to match the package. The service keeps the contract's name, Worker, with SERVICE_SUFFIX ignored. pkg/workerclient is the client library. It imports only the API and gRPC, so an independent client can depend on it without Galactic internals. It dials the unix socket, opens and renews a session, reads the projected token for every call, drops duplicate and reordered snapshots by revision, and retries the codes the contract says to retry, with backoff from 200 ms to 30 s and full jitter. Co-Authored-By: Claude <claude@anthropic.com>
Galactic Worker is the node-local service agents call to deliver tenant traffic, and the single writer of shared host state (docs/worker). This implements its reconciliation core and the authenticated service, with no delivery module built in: Local (#1435) and Fabric (#1436) plug into internal/worker/module. Until then every capability reports ModuleNotRunning. Calls are authenticated over a unix socket (mode 0660): TokenReview of the projected token for audience galactic-worker, cached until it expires; the bound pod must be on this node; the SO_PEERCRED process must run in that pod, which the cgroup path shows; and a static YAML allowlist names each ServiceAccount's capabilities. A mutating call validates the request, authorizes the claim against trusted sources (the attachment's VPC, node and admission) and records desired state durably before it returns. A refusal records nothing, takes no ticket and reaches no module. Every refusal carries a contract reason and is counted in galactic_worker_refusals_total. Reconciliation runs per VPC scope from a deduplicating queue, so duplicate watch events coalesce. It resolves each destination by locator (own locator Local, any other Fabric, never a fallback), takes the scope's ticket from the internal/edge/ownership fence and commits the scope's complete desired state through the modules, then reads the host back. Desired state is durable; programmed and observed state are rebuilt from the host, and Ready stays separate from Programmed. On restart Worker fences and adopts each scope an earlier incarnation owned, refuses changes there with Resyncing until the snapshot commits, and never fences a scope another writer owns. A failed commit leaves the scope resync-required. A release during that repair fences the scope, so the repair's late commit cannot land. Only the owner releases a claim, at its current generation. A caller with no live session for a lease (120 s) has its claims withdrawn, as does a claim whose attachment loses its authority. Tests cover concurrent clients and racing callers; duplicate, stale and out-of-order calls; crashes before programming, mid-apply and before a release is recorded, then restart; duplicate watch events; lease expiry; revocation; withdrawal during repair; and unavailable modules. A privileged test programs real links, routes, rules and a pinned map, then shows that a cross-VPC request leaves all of them unchanged. Co-Authored-By: Claude <claude@anthropic.com>
The contract needs a client that proves the published interface is enough on its own. examples/worker-client is its own module and imports only api/galactic/worker/v1alpha1 and pkg/workerclient; its module path lies outside go.datum.net/galactic, so the compiler refuses internal imports. Its lifecycle subcommand checks the negotiated version and its allowed capabilities, expects a forbidden handoff to be refused, requests, repeats the request, observes, updates, sends a stale release, releases and observes the release. task test:worker-client builds, vets and tests the module and fails if it imports any other Galactic package; test:unit runs it, so task ci does too. TestIndependentClient builds the binary and runs its lifecycle against a real Worker on a unix socket with the real authentication chain, as a ServiceAccount allowed local.veth_pair only. It also checks that another process holding the same token is refused. Co-Authored-By: Claude <claude@anthropic.com>
Implementing the contract settled six points it left open. The epic coordinator approved each, and the contract now states them: - D19: the session ID travels in x-galactic-worker-session; a call without a live session is FAILED_PRECONDITION/NoSession, and a GetCapabilities with a live session renews it - D20: shard and backend destinations are in the API but report Resolved=False/DestinationKindUnsupported until #1437 and #1438 add their resolvers inside Worker - D21: the peer check maps SO_PEERCRED to a pod by its cgroup path, so Worker needs hostPID and the host's /proc, which #1441 packages - D22: the allowlist is a YAML file passed with --allowlist - D18 now includes the claim limit, 1024 per caller - Worker uses internal/edge/ownership in place; #1434 relocates it The pages also record ClaimNotFound for an Update of a missing claim, the status reasons the implementation reports, which capability a claim needs, how Worker compares VPC identity (the base62 identifier on the attachment's status, which is the VPC's fabric identity in this cell), and that Worker adopts only scopes an earlier Worker owned. Co-Authored-By: Claude <claude@anthropic.com>
Collaborator
Author
|
Acceptance evidence for #1433, from head
Each acceptance bullet maps to these tests:
The approved gap decisions are recorded as D19 to D22, plus the claim limit in D18, in |
Admission compared locators to decide whether a claim needs fabric.srv6, ignored lookup errors, and skipped the check while either locator was unknown. During bring-up a caller without fabric.srv6 could be admitted with a destination on another node, and once the locators appeared reconciliation programmed it as Fabric without checking the owner again. A destination on another node now needs fabric.srv6 whatever the locators say, and a lookup error refuses with Resyncing. Worker also records the owner's capabilities with each generation, and reconciliation leaves unprogrammed any destination whose mode they do not cover, reporting CapabilityNotAllowed on Programmed. Co-Authored-By: Claude <claude@anthropic.com>
Collaborator
Author
|
Two independent reviews of the first head both returned merge. The adversarial review found that the |
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
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
Service agents have no node-local API for tenant delivery, so every later Task in the Worker epic needs one authenticated service to build against.
This adds Galactic Worker: the service and its protobuf API, a client library, the reconciliation core and the module interface that the Local and Fabric delivery Tasks plug into. It also adds an independent example client that uses only the published API.
No delivery module is built in yet, so every capability reports that its module is not running until those Tasks land.
Test plan
Fixes #1433