@plumile/relay

Shared Relay environment, transport, provider, and operation-activity helpers for Plumile applications.

HTTP authentication ownership

configureShortAccessTokenRelayEnvironment() injects an auth-aware GraphQL fetch into this package. The injected fetch owns the single refresh and retry after 401; this transport owns multipart encoding, timeouts, and retries for network, 408, 429, and 5xx failures. It does not patch globalThis.fetch.

getAuthHeaders(signal?) receives the same operation signal across HTTP retries. An error from this provider rejects the operation with the original error before sending any request, and is never retried as a network failure. The signal is omitted for WebSocket authentication. Existing callbacks without a parameter remain supported.

Relay query disposal aborts the active HTTP attempt and the complete retry lifecycle, including a pending backoff. Disposed operations never publish a late response or error to their observer.

WebSocket transport contract

Subscriptions use the graphql-transport-ws subprotocol through the package's owned client. The client deliberately remains local because the deployed server contract includes authentication rotation beyond the standard protocol:

• the client sends connection_init with the current authentication headers and waits for connection_ack before subscribing;
• subscriptions use subscribe, next, error, and complete, while keep-alive messages use ping and pong;
• credential rotation sends connection_auth_update and requires connection_auth_update_ack within five seconds;
• an unexpected disconnect retries with bounded exponential backoff (at most ten attempts) and re-subscribes every still-active operation after the next ack;
• invalid or unsupported server messages close the socket with code 4400; normal environment disposal closes it with code 1000.

Do not replace this client with a generic GraphQL WebSocket dependency unless that implementation proves the same authentication-update and reconnection contract without an adapter of comparable complexity.

Validation

From the repository root, run the Relay tests and build:

npx vitest run packages/relay
npm run --workspace @plumile/relay build:package