coulomb/reuse-surface
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
b8434aafdf6fbbbff2198f740c2dcb93dd510d58
reuse-surface/specs/FederationHubAPI.md
tegwick b8434aafdf
Some checks failed
ci / validate-registry (push) Has been cancelled
Details
Close REUSE-WP-0011 follow-ups: archive, docs, A4 promotion 
- Archive workplan to workplans/archived/260615-REUSE-WP-0011-*.md
- Document browser landing page routing in FederationHubAPI and deploy docs
- Promote capability.registry.register to A4 (hosted hub API evidence)
- Update SCOPE finished workplan list
2026-06-15 16:25:38 +02:00

280 lines
7.1 KiB
Markdown
Raw Blame History

# 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 workplans: `railiance-apps` **RAILIANCE-WP-0007** (Helm
release), **RAILIANCE-WP-0008** (browser landing page).
### Browser vs API routing
Production ingress (owned by `railiance-apps`) splits paths:
| Path | Handler |
|---|---|
| `GET /` (HTTPS) | Static landing page (`reuse-surface-landing`) — humans only |
| `GET /health`, `GET /v1/*` | Hub API (`reuse-surface` service) |
The landing page does not implement registration or federation; clients and
agents should use `/health` and `/v1/*` only. See
`railiance-apps/docs/reuse-surface-on-railiance01.md`.
---
## 2. Base URL and formats
| Item | Value |
|---|---|
| Default production URL | `https://reuse.coulomb.social` (A → `92.205.62.239`) |
| 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
- Landing page at `/`: `railiance-apps` RAILIANCE-WP-0008 (disable via
`landing.enabled: false` in Helm values)
Reference in New Issue View Git Blame Copy Permalink