Capability Registry¶
Responsibility¶
Control-plane service for capability discovery. Providers register themselves; orchestrator (and other consumers) look up capabilities by name/version.
Canonical contract: Capability Provider Contract (17).
Starters: Add a Capability Provider.
Deploy wiring: Deploy integration (18).
API surface¶
| Method | Path | Purpose |
|---|---|---|
POST |
/v1/registry/services/register |
Register service + capabilities (returns service_id, generation, lease) |
POST |
/v1/registry/services/{service_id}/heartbeat |
Renew lease; 404 → re-register |
DELETE |
/v1/registry/services/{service_id} |
Deregister |
GET |
/v1/registry/services |
List registered services |
GET |
/v1/registry/capabilities |
List capabilities (capability_kind, capability_name filters) |
GET |
/v1/registry/routes |
Route hints from metadata.public_paths |
GET |
/healthz / /readyz |
Probes |
Auth: optional registry token (CAPABILITY_REGISTRY_TOKEN / Bearer) depending on deployment.
Consumers¶
- Orchestrator —
CAPABILITY_REGISTRY_URLforservice_calldiscovery and validation (?strict=true) - Gateway — route / trigger discovery where enabled
- Dashboard — capability catalog / designer metadata
- Providers — self-register + heartbeat (≈
LEASE_TTL/2)
Architecture notes¶
- Providers send
SERVICE_URLas their reachable base URL. - Heartbeat with stale generation returns
404so clients re-register. - Workflows never call the registry directly; they declare
capability_name+pathonservice_call.
Deploy¶
- Image / deployment:
capability-registry - Cluster / Compose service DNS:
http://capability-registry:8080 - Orchestrator env:
CAPABILITY_REGISTRY_URL=http://capability-registry:8080 - Docker Compose host publish:
localhost:8093→ container8080(use only from the host)
Do not set provider CAPABILITY_REGISTRY_URL to :8093 inside the cluster or Compose network — that port is the host mapping only.
Related (historical)¶
Design docs 15 and 16 are superseded — use 17 + 18 + howto 16 + Integration end-to-end.