d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
36 lines
1.7 KiB
Markdown
36 lines
1.7 KiB
Markdown
# Symbol Server API
|
||
|
||
> **Imposed rule:** All API responses must include tenant scoping and content digests; cross-tenant symbol access is forbidden.
|
||
|
||
Base path: `/api/v1/symbols` (service: Symbol Server / Export Center plugin).
|
||
|
||
## Endpoints
|
||
|
||
- `GET /manifest` – returns `SYMBOL_MANIFEST/v1` for the tenant.
|
||
- Headers: `X-Stella-Tenant` (required)
|
||
- Query: `image_digest` (optional filter), `build_id` (exact match)
|
||
- `GET /files/{path}` – stream a symbol file by relative path in manifest.
|
||
- Headers: `X-Stella-Tenant`
|
||
- Responds with `Content-SHA256` header and ETag; 404 if tenant mismatch.
|
||
- `POST /ingest` – upload a symbol bundle (tar or OCI artifact) and manifest.
|
||
- Headers: `X-Stella-Tenant`, `X-Stella-Attestation` (optional DSSE digest)
|
||
- Validates manifest checksum, entry digests, and tenant.
|
||
- `GET /health` – readiness/liveness.
|
||
|
||
## Error model
|
||
- Problem+JSON; include `tenant`, `correlation_id`, and `policy` fields when access is denied.
|
||
- Rate limits: `429` with `Retry-After`; deterministic budget per tenant.
|
||
|
||
## Security
|
||
- Auth via Authority-issued JWT; enforce `symbols:read`/`symbols:write` scopes.
|
||
- Tenant check on every request; manifest tenant must equal header.
|
||
- Optional DSSE attestation digest header is recorded and surfaced in `/manifest` under `source.attestation`.
|
||
|
||
## Caching & offline
|
||
- Console/CLI cache manifest + files in CAS; revalidate via `If-None-Match` on `GET /manifest`.
|
||
- Offline kits mount symbol bundle read-only; API client can be pointed at `file://` CAS handler for air-gapped use.
|
||
|
||
## Observability
|
||
- Emit counters per tenant: `symbol_manifest_requests`, `symbol_file_bytes_served`, `symbol_ingest_failures`.
|
||
- Logs include `build_id`, `image_digest`, `tenant`, `attested` flag.
|