Skip to content

Run the server on pkg/registry in claims mode - #961

Open
rdimitrov wants to merge 13 commits into
registry-libraryfrom
registry-server-claims
Open

rdimitrov wants to merge 13 commits into
registry-libraryfrom
registry-server-claims

Conversation

@rdimitrov

Copy link
Copy Markdown
Member

Summary

Second of three PRs ((a) #960 → (b) → (c) Cedar mode). This PR moves the server onto the pkg/registry library while keeping v1.5.4's claims-based authorization. Stacked on #960: the base is registry-library, so the diff shows only this PR. Retarget it to main once #960 merges.

The library stays claims-free. The server keeps claims in step through two small, generic seams.

  • Writes. The library gains a public postgres.WithEntryWriteHook option. The hook's BeforeEntryWrite and AfterEntryWrite run inside the library's serializable write transaction for every snapshot, publish and delete. The server's ClaimsHook uses them to:

    • apply the publish and delete gates;
    • check claim consistency;
    • store entry claims.

    Claims commit or roll back together with the entries.

  • Reads. The shared list query takes an optional caller. When a caller is set, it applies claims_visible() (migration 28) before choosing each name's winning source. Only the server can set the caller, through a module-internal context key, so external embedders can never turn the filter on.

What changed

Consumer API. httpapi.ConsumerRouter now serves the consumer routes, mounted at /registry, over a claims-aware catalog.Reader (internal/claims.Reader).

  • The registry gate, its 403 message and the bypasses for anonymous users and superadmins are unchanged.
  • An entry the caller can't see falls through to the next source.
  • Consumer reads still emit v1.5.4's audit events (server.list, skill.read, …).
  • internal/api/consumer_compat.go keeps v1.5.4's response shapes:
    • upper-case skill and plugin status;
    • _meta always present on servers;
    • repository: {} on managed skills and plugins.
  • internal/api/openapi_consumer.go keeps the routes in /openapi.json.

Sync. It runs on the library's leased jobs (reconcile, ingest, operator), supervised by internal/sync/standalone (ported from #946).

  • Kubernetes authz-claims annotations are recorded during a fetch and applied at commit.
  • Source create, update and delete refresh the runtime, so inline and Kubernetes sources created through the API start their worker.

Admin API. The /v1 handlers and their responses are unchanged.

  • Publish and delete go through the library.
  • Admin write transactions retry on serialization failures. Concurrent sync jobs make those failures likely.
  • Config sources and registries are reconciled with Definitions.Reconcile, and their claims are stored afterwards.

Removed.

  • The old consumer handlers (internal/api/registry/v01, internal/api/x/*).
  • The sync manager, coordinator and state service.
  • The source fetchers and the old Kubernetes controller.
  • The service's read, dedup and cursor code.

Library changes (still experimental):

  • the write hook;
  • skills and plugins compete for a winning source per namespace and name;
  • ValidateSnapshot accepts servers without $schema, as registry files allow;
  • inline data sources may have a filter;
  • RequiredSchemaVersion is 28.

Rules and docs.

  • .claude/rules/data-model.md §7 now names the one sanctioned SQL claims check.
  • auth.md, api.md, sync.md and layering.md are updated.
  • CLAUDE.md and the library README are updated.

Compatibility with v1.5.4

I restored a v1.5.4 database dump and ran v1.5.4 and this branch against the same data. That's 1,090 consumer and admin GETs across 5 identities, plus 30 write scenarios.

  • Admin API: every /v1 response is identical.
  • Writes: identical status codes and error messages, including the 400, 403, 409 and 404 cases and the claims PUT/GET.
  • Consumer API: the remaining differences are all the intended changes listed below.

Changes users will notice

  • Winning source. Consumer reads always use the highest-priority source, for lists, latest and exact versions alike. v1.5.4's lists and version histories used the source holding the lowest version string, which disagreed with its own …/versions/latest. An exact version that only a lower-priority source has now returns 404.
  • Same-named skills and plugins in different namespaces. Lists now show both. v1.5.4 listed one but served both on direct reads.
  • Publish validation. POST /v1/entries validates payloads against the upstream schema; for example, a server needs a description of 1–100 characters. Invalid payloads return 400. v1.5.4 accepted them.
  • Sync failure messages are categories ("Fetch failed", "Registry validation failed", "Storage failed", "Sync cancelled") instead of raw error text, which can carry credentials.
  • Server icons are now returned. v1.5.4 stored them but never sent them.
  • Restarts no longer reset per-entry claims on managed entries. v1.5.4 overwrote them with the managed source's claims on every start. That was a bug: an entry published for one org became visible to another.
  • OpenAPI schema names. The skill and plugin list schemas are named api.* instead of skills.* and plugins.*. The paths are unchanged.

For reviewers: one rule mismatch

.claude/rules/sync.md used to say that Kubernetes entries without an annotation get no claims. v1.5.4's code gives them the source's claims. This PR keeps the code's behaviour and rewrites the rule. If the old rule was the intent, changing it would be a user-visible change.

Testing

  • go test -race ./... passes (42 packages).
  • The authz integration suite (193 cases: anonymous, auth-only and full claims) passes. It also passed 6 consecutive runs after the retry fix.
  • golangci-lint reports 0 issues, and task deadcode is clean.
  • New tests:
    • a shared Go/SQL claims case table (29 cases);
    • claims reader fall-through, registry gate and bypasses;
    • write hook ordering, abort and retry semantics;
    • namespace-aware winners in both conformance suites;
    • Kubernetes annotation recording;
    • the consumer shape and audit wrappers;
    • config claims reconciliation;
    • app assembly against a real database;
    • the sync runner lifecycle;
    • admin write retries.

Not covered: Kubernetes sources end to end (unit-tested only, not run under envtest); git and api sources end to end (the comparison used file and inline sources); running a library host and the server against the same database, which is documented as unsupported.

🤖 Generated with Claude Code

The server now uses the library for consumer reads, sync, publish and
delete, and keeps v1.5.4's claims-based authorization on top of it. The
library stays claims-free: claims are written through a new generic
`postgres.EntryWriteHook` that runs inside the library's write
transaction, and the consumer list filters by claims through an
optional caller on the shared list query, set only through a
module-internal context key.

Consumer routes are served by `httpapi.ConsumerRouter` over a
claims-aware reader. It applies v1.5.4's registry gate and filters
entries with `claims_visible()` (migration 28) before choosing each
name's winning source, so an entry a caller cannot see falls through
to the next source. A shared case table pins the SQL function to the Go
rule in `internal/claims`. Consumer reads keep v1.5.4's response
shapes and audit events.

Sync runs on the library's leased jobs and runtime; Kubernetes
`authz-claims` annotations are recorded during a fetch and applied at
commit. The `/v1` admin handlers are unchanged, and publish, delete and
source changes go through the library. The old consumer handlers, sync
coordinator and manager, source fetchers, Kubernetes controller and
service read paths are removed.

User-visible changes: consumer reads always take the highest-priority
source (v1.5.4 lists used the lowest version string) and exact versions
no longer fall through to lower sources; skills and plugins compete per
namespace; publish validates payloads against the upstream schema; sync
failure messages are categories; server icons are returned; restarts no
longer reset per-entry claims on managed entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov-commenter

codecov-commenter commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 77.36842% with 172 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.94%. Comparing base (0cc5a01) to head (a794b14).

Files with missing lines Patch % Lines
internal/kubernetes/standalone_client.go 0.00% 26 Missing ⚠️
internal/service/db/claims_hook.go 65.00% 21 Missing ⚠️
internal/kubernetes/standalone.go 89.62% 14 Missing ⚠️
internal/app/storage/namespaces.go 0.00% 12 Missing ⚠️
internal/app/storage/mocks/mock_factory.go 0.00% 10 Missing ⚠️
internal/db/sqlc/registry_entries.sql.go 0.00% 9 Missing ⚠️
internal/app/builder.go 89.18% 8 Missing ⚠️
internal/app/catalog.go 93.04% 8 Missing ⚠️
internal/claims/reader.go 78.37% 8 Missing ⚠️
internal/config/secret.go 0.00% 8 Missing ⚠️
... and 13 more
Additional details and impacted files
@@                 Coverage Diff                  @@
##           registry-library     #961      +/-   ##
====================================================
+ Coverage             68.78%   71.94%   +3.16%     
====================================================
  Files                   173      165       -8     
  Lines                 17217    14435    -2782     
====================================================
- Hits                  11842    10385    -1457     
+ Misses                 5375     4050    -1325     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Regenerate the OpenAPI spec with the current `swag`, which places schema
descriptions on property references rather than on the referenced
types, matching what `task gen` produces in CI. Remove a blank line left
in `internal/sources/types.go` after its unused mock directive was
dropped, which `gci` rejected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
rdimitrov and others added 11 commits November 18, 2026 19:28
The API server ends every watch after its request timeout, and the
runner returns `operator.ErrWatch` when one does. The standalone runtime
treated that as fatal, so 30-60 minutes after startup it stopped sync for
every source while readiness stayed green. `OperatorWorker` now runs the
runner again with backoff, and once a source has synced it also retries
any other non-ownership failure, which the restarted runner would
otherwise report as a startup error.

`AnnotationClaims` recorded annotations per kind only, so in a
multi-namespace source the last namespace's list replaced the others and
their entries fell back to the source's claims. It now records them per
namespace and kind, forgets a source's scopes when its worker is rebuilt,
and ignores resources the fetcher does not export.

An annotation-only change left the snapshot hash unchanged, so the sync
completed without committing and the claims hook never wrote the new
claims. `annotationJobs` stores a digest of the written annotation claims
with the sync result and forces a full commit when it differs. The digest
is kept in storage, so every replica compares against what was written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`standalone.Runtime` validated every stored definition and stopped sync
for every source when one failed, while readiness stayed green. One
admin call could trigger it: an inline source created with a
`syncPolicy` is accepted, as in v1.5.4, but its stored schedule failed
validation. The library now drops such settings when it loads a
definition; the runtime also logs and skips any definition that is still
invalid, once per version, so the other sources keep syncing.

Kubernetes `authz-claims` annotations were recorded only with
`auth.authz`, so without it annotated entries were stored with their
source's claims. v1.5.4 recorded them whenever claims were stored; the
builder now always does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two consumer and admin responses changed by accident in the move to the
library. A consumer read of a registry that does not exist answered
"not found" instead of v1.5.4's "registry not found"; the consumer
error mapper now maps the library's `ErrViewNotFound` to that message
on every consumer route.

A managed source from the config file had no `syncStatus` on a fresh
install, because v1.5.4 wrote its initial `registry_sync` row at
startup and the library never syncs a managed source. The claims-mode
startup step now records v1.5.4's completed "Non-synced source (type:
managed)" row with `InitializeSourceSync`, leaving an existing row
alone so restarts and replicas do not overwrite it.

Improves on #946

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`docs/registry-sync.md` still described v1.5.4's two-minute coordinator
and called Kubernetes sources non-synced. Rewrite it for the leased-job
runtime: how polled, inline, Kubernetes and managed sources sync, the
two-minute failure retry, leases across replicas, and the visible
differences from v1.5.4 (Kubernetes reports its real sync status,
API-created inline sources are synced, sources are fetched on their own
interval).

Correct the Kubernetes section of `docs/configuration.md`: entries
without an `authz-claims` annotation get the source's claims, as both
v1.5.4 and this branch do, not no claims. Note that network packages
get `transport.url` from the `registry-url` annotation, and how
`syncPolicy` applies to each source type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The server stopped using Kubernetes leader election when sync moved to
the library's database leases, which fence every source including
Kubernetes ones. `config.LeaderElectionID` was still read from
`THV_REGISTRY_LEADER_ELECTION_ID` but never used, and the chart still
set that variable and created a Role and RoleBinding granting
configmaps, leases and events that nothing needs.

Remove the field, the chart's env entry and the leader-election Role
and RoleBinding; the chart writes `env:` only when it has content. A
deployment that still sets the variable is unaffected. The DNS-name
rule for sources stays, but its rationale is now an API contract
rather than lease naming.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants