84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
<!-- markdownlint-disable MD024 -->
|
|
|
|
# Capability Spec: api-graphql-ui-altair
|
|
|
|
**Package**: `@suaveplan/api-graphql-ui-altair`
|
|
**Status**: SHIPPED 2026-05-26
|
|
|
|
> Every requirement carries a `**Verified by:**` line.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Mounts Altair at the configured UI endpoint
|
|
|
|
The package SHALL expose `createAltairUi(opts)` returning a `RouterPlugin` that registers `GET <uiEndpoint>` (default `/graphql/ui`). The response MUST be the Altair HTML shell embedding the configured `graphqlEndpoint`, `subscriptionEndpoint`, `initialQuery`, `initialHeaders`, and `initialEnvironments`.
|
|
|
|
#### Scenario: default mount serves Altair at /graphql/ui
|
|
|
|
- **WHEN** the plugin is mounted with default `opts`
|
|
- **THEN** `GET /graphql/ui` returns 200 AND the body contains the Altair shell AND the embedded `graphqlEndpoint` reads `/graphql`
|
|
|
|
#### Scenario: configured initial environments flow into the shell
|
|
|
|
- **WHEN** `createAltairUi({ initialEnvironments: { production: { url: "https://api.example.com" } } })`
|
|
- **THEN** the rendered HTML embeds those environments
|
|
|
|
**Verified by:** `src/factory/create-altair-ui.test.ts::"default mount returns Altair HTML at /graphql/ui"` AND `src/factory/create-altair-ui.spec-conformance.test.ts::"initialEnvironments flow into embedded shell"`
|
|
|
|
---
|
|
|
|
### Requirement: Bundled assets only — no CDN fetches
|
|
|
|
Every static asset SHALL be served from this package's `dist/assets/`. No external host references. Cache-busting hashes embedded. Missing asset returns 404 with `GRAPHQL_UI_ALTAIR_ASSET_MISSING`.
|
|
|
|
#### Scenario: no external hosts in the shell
|
|
|
|
- **WHEN** the HTML body is inspected
|
|
- **THEN** no `src` or `href` attribute points at an external host
|
|
|
|
#### Scenario: missing asset returns spec'd code
|
|
|
|
- **WHEN** a request arrives for `<uiEndpoint>/assets/does-not-exist.js`
|
|
- **THEN** the response is 404 with `code: "GRAPHQL_UI_ALTAIR_ASSET_MISSING"`
|
|
|
|
**Verified by:** `src/assets/assets.test.ts::"rendered shell references no external hosts"` AND `src/assets/assets.test.ts::"missing asset returns GRAPHQL_UI_ALTAIR_ASSET_MISSING"`
|
|
|
|
---
|
|
|
|
### Requirement: CSP header on the HTML response
|
|
|
|
The response SHALL carry `Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'`. Inline scripts MUST NOT be permitted.
|
|
|
|
#### Scenario: CSP header present, scripts not 'unsafe-inline'
|
|
|
|
- **WHEN** the HTML response is returned
|
|
- **THEN** the CSP header is set AND `script-src` does NOT include `'unsafe-inline'`
|
|
|
|
**Verified by:** `src/headers/csp.test.ts::"CSP header set with 'unsafe-inline' only for style-src"`
|
|
|
|
---
|
|
|
|
### Requirement: Endpoint-collision detection
|
|
|
|
If `<uiEndpoint>` is already mounted, this package SHALL refuse with `GRAPHQL_UI_ALTAIR_ENDPOINT_COLLISION`.
|
|
|
|
#### Scenario: collision refused
|
|
|
|
- **WHEN** another plugin has already mounted `GET /graphql/ui`
|
|
- **THEN** mount fails with `GRAPHQL_UI_ALTAIR_ENDPOINT_COLLISION`
|
|
|
|
**Verified by:** `src/factory/create-altair-ui.test.ts::"endpoint collision refused with GRAPHQL_UI_ALTAIR_ENDPOINT_COLLISION"`
|
|
|
|
---
|
|
|
|
### Requirement: OTel counter shares the GraphiQL variant's metric name
|
|
|
|
The package SHALL emit `graphql.ui.requests_total` counter labelled `{ ui: "altair" }` on each UI HTML request. The metric name is deliberately identical to the GraphiQL variant's so dashboards can sum across both UIs by dropping the `ui` label.
|
|
|
|
#### Scenario: UI HTML request increments the counter with ui="altair"
|
|
|
|
- **WHEN** `GET /graphql/ui` returns 200
|
|
- **THEN** an in-memory `MeterProvider` observes `graphql.ui.requests_total{ui="altair"}` increment by 1
|
|
|
|
**Verified by:** `src/instruments/instruments.test.ts::"UI HTML increments graphql.ui.requests_total with ui='altair' label"`
|