generated from coulomb/repo-seed
tegwick
cbcd097214
Some checks failed
ci / validate-registry (push) Has been cancelled
Use reuse.coulomb.social, REUSE_SURFACE_URL/TOKEN env vars, reuse-surface image and reuse-surface-env secret. Replace reuse-surface-hub entrypoint with reuse-surface serve; CLI uses --base-url.
264 lines
6.5 KiB
Markdown
264 lines
6.5 KiB
Markdown
# Federation Hub API
|
|
|
|
**Repository:** `reuse-surface`
|
|
**Artifact:** `specs/FederationHubAPI.md`
|
|
**Status:** Draft 0.1 (REUSE-WP-0011-T01)
|
|
**Schema:** `schemas/hub-registration.schema.yaml`
|
|
|
|
---
|
|
|
|
## 1. Purpose
|
|
|
|
The federation hub is a hosted coordination service that records which
|
|
repositories publish capability indexes and serves a composed federated index
|
|
for agent discovery. It does **not** store capability entry Markdown bodies.
|
|
|
|
Companion deployment workplan: `railiance-apps` **RAILIANCE-WP-0007**.
|
|
|
|
---
|
|
|
|
## 2. Base URL and formats
|
|
|
|
| Item | Value |
|
|
|---|---|
|
|
| Default production URL | `https://reuse.coulomb.social` |
|
|
| API prefix | `/v1` |
|
|
| Read formats | JSON (default), YAML via `Accept: application/yaml` or `?format=yaml` |
|
|
| Write content type | `application/json` |
|
|
|
|
Environment variables for clients:
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `REUSE_SURFACE_URL` | Service base URL (no trailing slash) |
|
|
| `REUSE_SURFACE_TOKEN` | Bearer token for write operations |
|
|
|
|
---
|
|
|
|
## 3. Authentication
|
|
|
|
| Endpoint class | Auth |
|
|
|---|---|
|
|
| `GET /health`, `GET /v1/repos`, `GET /v1/repos/{repo}`, `GET /v1/federated` | Public (read) |
|
|
| `POST /v1/repos`, `PATCH /v1/repos/{repo}`, `DELETE /v1/repos/{repo}`, `POST /v1/federated/compose` | Bearer token required |
|
|
|
|
Write requests must include:
|
|
|
|
```http
|
|
Authorization: Bearer <REUSE_SURFACE_TOKEN>
|
|
```
|
|
|
|
Missing or invalid token → `401 Unauthorized`.
|
|
|
|
---
|
|
|
|
## 4. Registration model
|
|
|
|
A registration mirrors federation `url` sources from
|
|
`schemas/federation.schema.yaml`, plus hub metadata:
|
|
|
|
| Field | Required | Notes |
|
|
|---|---|---|
|
|
| `repo` | yes | Slug `[a-z][a-z0-9-]*`; primary key |
|
|
| `url` | yes | HTTP(S) URL to `capabilities.yaml` |
|
|
| `enabled` | yes | Include in federated compose when true |
|
|
| `domain` | yes | e.g. `helix_forge` |
|
|
| `required` | no | Fail compose if fetch fails and no cache |
|
|
| `description` | no | Human-readable note |
|
|
| `cache_ttl_seconds` | no | Default `86400` |
|
|
| `auth_env` | no | Hub container env var for fetch auth (never returned in GET) |
|
|
| `auth_header` | no | Default `Authorization` |
|
|
| `registered_at` | hub | ISO-8601 UTC |
|
|
| `updated_at` | hub | ISO-8601 UTC |
|
|
| `registered_by` | no | Optional client-supplied actor label |
|
|
|
|
Local filesystem `index` paths are **not** accepted — registrations must use
|
|
published raw URLs.
|
|
|
|
---
|
|
|
|
## 5. Endpoints
|
|
|
|
### 5.1 `GET /health`
|
|
|
|
Liveness/readiness probe.
|
|
|
|
**Response `200`:**
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"service": "reuse-surface",
|
|
"version": "0.1.0"
|
|
}
|
|
```
|
|
|
|
### 5.2 `GET /v1/repos`
|
|
|
|
List all registrations (including disabled).
|
|
|
|
**Response `200`:**
|
|
|
|
```json
|
|
{
|
|
"count": 2,
|
|
"repos": [
|
|
{
|
|
"repo": "reuse-surface",
|
|
"url": "https://gitea.coulomb.social/coulomb/reuse-surface/raw/main/registry/indexes/capabilities.yaml",
|
|
"enabled": true,
|
|
"required": true,
|
|
"domain": "helix_forge",
|
|
"description": "Primary registry",
|
|
"cache_ttl_seconds": 86400,
|
|
"registered_at": "2026-06-15T12:00:00Z",
|
|
"updated_at": "2026-06-15T12:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`auth_env` is omitted from responses.
|
|
|
|
### 5.3 `POST /v1/repos`
|
|
|
|
Register a new repository. **Auth required.**
|
|
|
|
**Request body:** `registration_request` from schema.
|
|
|
|
**Response `201`:** Full registration object.
|
|
|
|
**Errors:**
|
|
|
|
| Code | Condition |
|
|
|---|---|
|
|
| `400` | Schema validation failure |
|
|
| `401` | Missing/invalid token |
|
|
| `409` | `repo` already registered |
|
|
|
|
### 5.4 `GET /v1/repos/{repo}`
|
|
|
|
Fetch one registration.
|
|
|
|
**Response `200`:** Registration object.
|
|
**Response `404`:** Unknown repo.
|
|
|
|
### 5.5 `PATCH /v1/repos/{repo}`
|
|
|
|
Update fields on an existing registration. **Auth required.**
|
|
|
|
**Request body:** `registration_update` from schema (at least one field).
|
|
|
|
**Response `200`:** Updated registration.
|
|
|
|
**Errors:** `400`, `401`, `404`.
|
|
|
|
### 5.6 `DELETE /v1/repos/{repo}`
|
|
|
|
Remove a registration. **Auth required.**
|
|
|
|
**Response `204`:** No content.
|
|
**Response `404`:** Unknown repo.
|
|
|
|
### 5.7 `GET /v1/federated`
|
|
|
|
Return the composed federated index from all **enabled** registrations.
|
|
|
|
Reuses WP-0010 remote fetch/cache logic server-side. Output shape matches
|
|
`registry/indexes/federated.yaml`:
|
|
|
|
```yaml
|
|
version: 1
|
|
updated: "2026-06-15"
|
|
domain: helix_forge
|
|
collision_policy: warn
|
|
sources:
|
|
- repo: reuse-surface
|
|
url: https://...
|
|
count: 12
|
|
capabilities:
|
|
- id: capability.registry.register
|
|
source_repo: reuse-surface
|
|
source_url: https://...
|
|
# ... index fields ...
|
|
```
|
|
|
|
Query parameters:
|
|
|
|
| Param | Default | Meaning |
|
|
|---|---|---|
|
|
| `format` | `json` | `json` or `yaml` |
|
|
| `refresh` | `false` | Bypass remote cache when `true` |
|
|
|
|
Warnings from compose (duplicate IDs, fetch fallbacks) are returned in response
|
|
header `X-Federation-Warnings` (semicolon-separated) for MVP; JSON envelope
|
|
extension is a future option.
|
|
|
|
**Response `200`:** Federated index document.
|
|
**Response `502`:** Required source unavailable with no cache.
|
|
|
|
### 5.8 `POST /v1/federated/compose`
|
|
|
|
Trigger federated index refresh (same as `GET /v1/federated?refresh=true`).
|
|
**Auth required.** Useful for operators after bulk registration changes.
|
|
|
|
**Response `200`:** Federated index document.
|
|
|
|
---
|
|
|
|
## 6. Error envelope
|
|
|
|
Non-2xx responses use:
|
|
|
|
```json
|
|
{
|
|
"error": "validation_error",
|
|
"message": "Human-readable summary",
|
|
"details": ["optional field-level messages"]
|
|
}
|
|
```
|
|
|
|
| `error` code | HTTP |
|
|
|---|---|
|
|
| `validation_error` | 400 |
|
|
| `unauthorized` | 401 |
|
|
| `not_found` | 404 |
|
|
| `conflict` | 409 |
|
|
| `compose_error` | 502 |
|
|
|
|
---
|
|
|
|
## 7. Hub service configuration
|
|
|
|
| Env var | Required | Purpose |
|
|
|---|---|---|
|
|
| `REUSE_SURFACE_TOKEN` | yes | Write API bearer token |
|
|
| `REUSE_SURFACE_DB` | no | SQLite path (default `/data/reuse.db`) |
|
|
| `REUSE_SURFACE_CACHE_DIR` | no | Remote index cache (default `/data/cache`) |
|
|
| `REUSE_SURFACE_DOMAIN` | no | Default federated `domain` (default `helix_forge`) |
|
|
|
|
---
|
|
|
|
## 8. CLI mapping
|
|
|
|
| CLI command | API call |
|
|
|---|---|
|
|
| `reuse-surface hub status` | `GET /health` |
|
|
| `reuse-surface hub list` | `GET /v1/repos` |
|
|
| `reuse-surface hub show --repo X` | `GET /v1/repos/X` |
|
|
| `reuse-surface hub register ...` | `POST /v1/repos` |
|
|
| `reuse-surface hub update ...` | `PATCH /v1/repos/{repo}` |
|
|
|
|
Run locally: `reuse-surface serve`. Global client flags: `--base-url`, env
|
|
`REUSE_SURFACE_URL`, `REUSE_SURFACE_TOKEN`.
|
|
|
|
---
|
|
|
|
## 9. Deployment reference
|
|
|
|
- Image: `gitea.coulomb.social/coulomb/reuse-surface:<tag>`
|
|
- Public URL: `https://reuse.coulomb.social`
|
|
- Secret: `reuse-surface-env` with `REUSE_SURFACE_TOKEN`
|
|
- Probe path: `/health`
|
|
- Persistence: PVC at `/data` (SQLite + fetch cache)
|
|
- Helm release: `railiance-apps` RAILIANCE-WP-0007 |