generated from coulomb/repo-seed
tegwick
e8797b2e91
Some checks failed
ci / validate-registry (push) Has been cancelled
Extend federation manifest schema for url sources with auth and TTL metadata. Fetch remote capability indexes over HTTP(S), cache under registry/federation/cache/, and fall back to stale cache on fetch failure. Add --refresh flag, seven federation tests, and updated federation docs.
131 lines
4.2 KiB
Markdown
131 lines
4.2 KiB
Markdown
# Registry Federation
|
|
|
|
**Repository:** `reuse-surface`
|
|
**Audience:** Architects and agents composing multi-repo capability indexes
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
helix_forge capabilities may be registered in multiple repositories. Federation
|
|
composes capability indexes from configured sources into a single discovery
|
|
surface without silently merging duplicate IDs.
|
|
|
|
Sources may be **local filesystem paths** or **remote HTTP(S) URLs** (git raw
|
|
endpoints, published index artifacts, etc.). Remote indexes are cached under
|
|
`registry/federation/cache/` for offline reuse and faster compose.
|
|
|
|
## Manifest
|
|
|
|
`registry/federation/sources.yaml` lists index sources:
|
|
|
|
```yaml
|
|
version: 1
|
|
domain: helix_forge
|
|
collision_policy: warn
|
|
sources:
|
|
- repo: reuse-surface
|
|
index: registry/indexes/capabilities.yaml
|
|
enabled: true
|
|
required: true
|
|
|
|
- repo: sibling-repo
|
|
url: https://git.example.com/org/sibling-repo/raw/main/registry/indexes/capabilities.yaml
|
|
enabled: false
|
|
required: false
|
|
cache_ttl_seconds: 86400
|
|
auth_env: FEDERATION_TOKEN
|
|
auth_header: Authorization
|
|
```
|
|
|
|
Schema: `schemas/federation.schema.yaml`
|
|
|
|
### Source fields
|
|
|
|
| Field | Meaning |
|
|
|---|---|
|
|
| `repo` | Source repository slug |
|
|
| `index` | Local path to `capabilities.yaml` (repo-relative or `~/...`) |
|
|
| `url` | Remote HTTP(S) URL to a `capabilities.yaml` index |
|
|
| `enabled` | Include this source in compose |
|
|
| `required` | Fail compose if index missing or remote fetch fails with no cache |
|
|
| `domain` | Optional domain label |
|
|
| `cache_ttl_seconds` | Reuse cached remote index for this many seconds (`0` = always refetch) |
|
|
| `auth_env` | Environment variable holding token or full header value for `url` sources |
|
|
| `auth_header` | HTTP header for `auth_env` (default `Authorization`) |
|
|
|
|
Each source must specify **either** `index` **or** `url`, not both.
|
|
|
|
Sibling repos (`state-hub`, `feature-control`, `identity-canon`) are listed as
|
|
disabled local placeholders until they publish registry indexes. A disabled
|
|
`example-remote` URL source illustrates HTTP federation.
|
|
|
|
## Compose workflow
|
|
|
|
```bash
|
|
reuse-surface federation compose
|
|
reuse-surface federation compose --refresh # bypass remote cache
|
|
```
|
|
|
|
Writes `registry/indexes/federated.yaml` with:
|
|
|
|
- Merged `capabilities` from all enabled sources
|
|
- `source_repo` and `source_index` on every row
|
|
- `source_url` when the row came from a remote source
|
|
- `collision_policy` and per-source counts
|
|
|
|
### Remote cache
|
|
|
|
Fetched URL indexes are stored at `registry/federation/cache/<repo>.yaml` with
|
|
metadata in `<repo>.meta.yaml`. The cache directory is gitignored; only
|
|
`.gitkeep` is tracked.
|
|
|
|
When a refetch fails, compose reuses a stale cache and emits a warning. Required
|
|
remote sources without cache fail compose with a clear error.
|
|
|
|
### Collision policy
|
|
|
|
`warn` (default): duplicate IDs across sources are kept but reported as
|
|
warnings. Consumers must inspect `source_repo` before choosing an entry.
|
|
|
|
## Agent query pattern
|
|
|
|
1. Run `reuse-surface federation compose` after manifest or sibling index changes.
|
|
2. Read `registry/indexes/federated.yaml` for cross-repo discovery.
|
|
3. Open `path` in the source repo for full entry detail when local; follow
|
|
`source_url` / `source_index` when remote.
|
|
4. Run `reuse-surface graph --check` before relying on relation navigation.
|
|
|
|
### Cross-repo discovery without local checkout
|
|
|
|
Enable a `url` source pointing at a published raw index (Gitea, GitHub, static
|
|
host). Set `auth_env` when the endpoint requires a token. Agents on machines
|
|
without sibling repo clones can still compose a federated view from HTTP sources
|
|
plus the local `reuse-surface` index.
|
|
|
|
## Relation graphs
|
|
|
|
```bash
|
|
reuse-surface graph
|
|
reuse-surface graph --check
|
|
reuse-surface graph --stdout
|
|
```
|
|
|
|
Generates `docs/graph/capability-graph.mmd` from local entry `relations`.
|
|
`--check` reports `depends_on` cycles and broken relation targets against the
|
|
federated ID set.
|
|
|
|
## CI integration
|
|
|
|
Gitea CI runs:
|
|
|
|
```bash
|
|
reuse-surface validate --relations --fail-on-warnings
|
|
reuse-surface federation compose
|
|
reuse-surface catalog
|
|
reuse-surface graph --check --fail-on-warnings
|
|
pytest -q
|
|
```
|
|
|
|
CI uses local sources only (remote examples are disabled). Warnings on missing
|
|
optional sibling indexes do not fail CI; schema validation errors do. |