93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
# Tasks: enterprise-events-transport
|
|
|
|
- **Change ID**: enterprise-events-transport
|
|
- **Package**: `@suaveplan/events-transport`
|
|
- **Date**: 2026-04-24
|
|
|
|
## Prerequisites (must be published to Verdaccio first)
|
|
|
|
- [x] `@suaveplan/events`
|
|
- [x] `@suaveplan/error`
|
|
- [x] `@suaveplan/types`
|
|
|
|
## Optional peer (for trace context injection)
|
|
|
|
- [x] `@suaveplan/events-otel` — if present, `serializeTraceContext`/`deserializeTraceContext` are used automatically
|
|
|
|
## Tasks
|
|
|
|
### 1. Scaffold package
|
|
|
|
- [x] Create `universal/events/events-transport/` directory tree per file layout in `proposal.md`
|
|
- [x] Write `package.json` (name `@suaveplan/events-transport`, version `0.1.0`, `sideEffects: false`, correct workspace deps and `@opentelemetry/api` catalog dep)
|
|
- [x] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`
|
|
- [x] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`
|
|
|
|
### 2. Error codes (`src/error-codes.ts`)
|
|
|
|
- [x] Define `EventsTransportErrorCode` union type
|
|
- [x] Call `defineCodes` to register all `EVENTS_TRANSPORT.*` codes
|
|
- [x] Export `registerEventsTransportErrorCodes()` and `EventsTransportError`
|
|
|
|
### 3. Types (`src/types/common.ts`)
|
|
|
|
- [x] Define and export `EventTransport`, `DeliveryGuarantee`, `ConnectOptions`, `TransportHandle`, `TransportStats`
|
|
- [x] Write `common.md`
|
|
|
|
### 4. Transport envelope (`src/core/envelope/`)
|
|
|
|
- [x] Define `TransportEnvelope` interface and `TransportEnvelopeSchema` Zod schema
|
|
- [x] Export stable envelope version constant `ENVELOPE_VERSION = 1`
|
|
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`
|
|
|
|
### 5. Nonce dedup window (`src/core/nonce-window/`)
|
|
|
|
- [x] Implement LRU sliding window of received nonces with configurable `windowSize`
|
|
- [x] `has(nonce)` and `add(nonce)` methods
|
|
- [x] Write `.md`, `.test.ts`, `index.ts`
|
|
|
|
### 6. Structured-clone safety check (`src/utils/structured-clone-check.ts`)
|
|
|
|
- [x] Implement `isStructuredCloneable(value)` — attempt `structuredClone(value)` and return false on error
|
|
- [x] Implement `assertStructuredCloneable(value)` — throws `EventsTransportError("EVENTS_TRANSPORT_NOT_CLONEABLE")`
|
|
- [x] Write `.md` and `.test.ts`
|
|
|
|
### 7. MessageChannel transport (`src/transports/message-channel/`)
|
|
|
|
- [x] Implement at-least-once delivery: send envelope, wait for ack within `ackTimeoutMs`, retry up to `maxRetries`
|
|
- [x] Receiver sends ack immediately after re-dispatching
|
|
- [x] Nonce dedup window prevents duplicate re-dispatch
|
|
- [x] OTel span linking: `events_transport.send` and `events_transport.receive` linked via trace context in envelope
|
|
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`
|
|
|
|
### 8. BroadcastChannel transport (`src/transports/broadcast-channel/`)
|
|
|
|
- [x] Implement at-most-once delivery: fire-and-forget with nonce dedup on receive
|
|
- [x] Optional origin filter
|
|
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`
|
|
|
|
### 9. Tests
|
|
|
|
- [x] Unit tests co-located (100% coverage target)
|
|
- [x] `tests/integration.test.ts` — real MessageChannel and BroadcastChannel in Bun worker context; assert delivery and dedup behaviour
|
|
- [x] `tests/property.test.ts` — fast-check properties per `proposal.md` §5
|
|
|
|
### 10. Docs
|
|
|
|
- [x] Every `.ts` implementation file has a sibling `.md`
|
|
- [x] Root `README.md`
|
|
|
|
### 11. Pre-publish gate
|
|
|
|
- [x] `bunx turbo lint typecheck test --filter=@suaveplan/events-transport` green
|
|
- [x] `bunx turbo test:coverage --filter=@suaveplan/events-transport` ≥ 100% on touched modules
|
|
|
|
### 12. Publish
|
|
|
|
- [x] `bun scripts/publish.ts --package @suaveplan/events-transport`
|
|
|
|
### 13. Archive
|
|
|
|
- [x] Fold spec delta into `openspec/specs/events/spec.md`
|
|
- [x] `mv openspec/changes/enterprise-events-transport openspec/archive/2026-04-24-enterprise-events-transport`
|