Documentation
¶
Overview ¶
Package internal_membership exposes octo-server's Project membership facts over an authenticated service-to-service surface, for consumers that hold no end-user token.
Why a separate module from modules/project ¶
modules/project owns the user-facing surface: every route there is mounted behind AuthMiddleware plus the Space/Project middleware, and its handlers answer a logged-in human. The endpoints here answer a PEER SERVICE holding a deployment-issued token, and they must not inherit any of that: no AuthMiddleware, no uid, no per-uid rate limiter. Mixing the two trust domains in one module means one wrong middleware line grants a service token a user-scoped route, or leaves a service route depending on a uid that is never present.
The split also keeps the error contract right. modules/project pins its wire status to 400 (ResponseErrorL) for D14 compatibility with shipped clients; these endpoints have no such clients and use ResponseErrorLWithStatus, so a peer service reads a real 401/400/500 like it does from every other /v1/internal endpoint in this repository.
Scalar membership facts use pkg/project. The full roster calls the exported modules/project read service, which owns its DAO and response projection; this HTTP module never copies those reads. pkg/project remains independent of modules/project. Cross-module HTTP tests live in the external test package so the production dependency is not reversed by in-package test imports.
Consumers ¶
The Loop/Fleet control plane, which needs two facts octo-server alone can answer: whether a NAMED OTHER user still holds a seat in a project (the end-user verify endpoint can only speak for its own token holder), and whether a project's membership has changed since an authorization snapshot was taken. Every endpoint is gated by its own X-Internal-Token so a leaked credential grants exactly one capability.
Index ¶
Constants ¶
const ( // MembershipInternalTokenEnv gates this module's endpoints. The Loop/Fleet // control plane presents the value in X-Internal-Token on every call, and // the same variable name is used on the Fleet side for the credential it // sends — one secret, one name, so an operator cannot mis-pair them. // // Exported so main.go can feed the value into the cross-capability // exclusion checks without a second copy of the literal drifting out of // sync with this constant. MembershipInternalTokenEnv = "OCTO_MEMBERSHIP_INTERNAL_TOKEN" // PeerMaxCacheAgeEnv is the second half of the enablement gate: the operator // declares, in seconds, the time bound the PEER places on decisions it caches // from these endpoints. Setting the token without it does not enable the // capability. // // # Why the release condition is an env and not a sentence // // member_epoch cannot be a sufficient invalidation signal, and not because of // any defect: it is keyed per PROJECT while one of the four axes that decide // the answer — a super-admin ban or an account destroy — is per USER. A ban // moves no epoch, so a cached grant keeps its agreement and a cached denial // survives the unban. Nothing on this side can close that; the bound has to // exist on the consumer. See docs/project-membership-cache-bound-proposal.md. // // That made the safety argument for shipping "the peer implements a TTL, and // the token stays unset until they do" — a promise living in a PR description // and a rollout document, with the only observable being a gauge nobody had a // reason to watch. This branch's whole discipline is that a mistake worth // making impossible should be made INEXPRESSIBLE rather than documented, and // the branch had not applied it to its own release condition. Now enabling the // capability requires stating the bound, and the stated value is published as // a metric so "did anyone actually agree a number" is answerable at any time. // // It carries the VALUE rather than being a yes/no acknowledgement because the // value is the contract. When §3.1 of the proposal lands and the answers start // carrying max_age_seconds on the wire, this is where that number comes from — // no second source to drift. // // This is NOT a claim that the peer honours it. The server cannot verify that // from here; §5 of the proposal specifies the measured gate (observe the // peer's re-verification interval) that eventually can. It is the difference // between an unstated assumption and a stated one. PeerMaxCacheAgeEnv = "OCTO_MEMBERSHIP_INTERNAL_PEER_MAX_CACHE_AGE_SECONDS" )
Environment knobs and wire constants.
A distinct token per internal consumer is the repository convention (see modules/internal_resolve/config.go and modules/bot_mention/config.go): it lets one consumer be revoked or rotated without disturbing the rest, and bounds the blast radius when a single value leaks.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Module ¶
Module is the module handle registered with the wkhttp router.
func New ¶
New loads the enablement configuration at construction. When any part of it is missing or invalid the reason is logged and every request is refused — the module still mounts, so a misconfigured deployment fails closed on the endpoint rather than failing to boot the whole server.
Two things have to be right, not one. The token is the credential; the declared peer cache bound is the RELEASE CONDITION, and it is enforced here rather than promised in a document because these endpoints hand a peer authorization answers whose account axis member_epoch structurally cannot invalidate. See PeerMaxCacheAgeEnv.
Refusing to enable rather than panicking is deliberate and matches the rest of this module: one capability's misconfiguration must not take down a server whose other two dozen modules are serving real traffic. The distinction an operator needs — "off because nobody configured it" versus "off because I configured it wrong" — is carried by the ERROR line and the configured gauge, not by the process exiting.
func (*Module) Route ¶
Route mounts the membership and project-list endpoints under /v1/internal.
Middleware EXECUTION ORDER matters and is asserted by a test:
- per-endpoint strict IP rate limit — MUST run first, so abusive traffic never reaches the token compare (a Redis Lua round trip) or the database.
- internalAuthMiddleware — constant-time X-Internal-Token compare, fail-closed when unset.
Both are mounted on the CONCRETE routes rather than on the group. Gin runs group handlers ahead of route handlers, so auth-on-group + limiter-on-route would execute as auth → limiter: a missing or wrong token would then abort before consuming the strict bucket, and token-probing traffic would fall back to the much wider global per-IP bucket. modules/internal_resolve documents having been bitten by exactly this ordering.
None of these routes takes AuthMiddleware. That is the deliberate exclusion the space-isolation rule asks to be documented: these endpoints have no end user, the caller is a peer service authenticated by a deployment-issued token, and there is no session identity for a user-scoped middleware to read. On the list route uid is a token-authorized query target, or project_ids names metadata candidates; neither is caller identity. The required space_id scopes both modes. The Project member-list route binds its required space_id and project_id together; its peer authorizes the end user.