100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
# Tasks: enterprise-network
|
|
|
|
**Change ID**: enterprise-network
|
|
**Package**: `@suaveplan/network`
|
|
**Target path**: `universal/network/network`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/serialize`
|
|
|
|
---
|
|
|
|
## 1. Scaffold
|
|
|
|
- [ ] Create directory `universal/network/network/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
|
|
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/retry workspace:^`, `@suaveplan/serialize workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`.
|
|
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
|
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
|
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
|
|
|
---
|
|
|
|
## 2. Types + errors
|
|
|
|
- [ ] Write `src/types/common.ts` — `HttpMethod`, `HttpRequest`, `HttpResponse`, `HttpMiddleware`, `HttpClientOptions`, `WsReadyState`, `WsMessage`, `WebSocketClientOptions`.
|
|
- [ ] Write `src/types/common.md`.
|
|
- [ ] Write `src/error-codes.ts` — `NetworkErrorCode`, `NETWORK_ERROR_METADATA`, `registerNetworkErrorCodes()`.
|
|
- [ ] Write Zod schemas: `HttpRequestSchema`, `HttpClientOptionsSchema`, `WebSocketClientOptionsSchema`.
|
|
|
|
---
|
|
|
|
## 3. URL utilities
|
|
|
|
- [ ] Implement `buildUrl`, `parseQueryString`, `serializeQueryString`, `isAbsoluteUrl`, `joinPaths` in `src/utils/url.ts`.
|
|
- [ ] Write `url.test.ts` (≤500 lines): each function, edge cases (empty params, absolute URLs, path joining).
|
|
- [ ] Write `url.md`.
|
|
|
|
---
|
|
|
|
## 4. Middleware
|
|
|
|
### Logging middleware
|
|
|
|
- [ ] Implement `loggingMiddleware(logger): HttpMiddleware` — logs method, URL, status, duration.
|
|
- [ ] Write `logging.test.ts` and `logging.md`.
|
|
|
|
### Retry middleware
|
|
|
|
- [ ] Implement `retryMiddleware(options?): HttpMiddleware` — wraps `@suaveplan/retry`; retries on 429/5xx and network errors; uses exponential backoff.
|
|
- [ ] Write `retry.test.ts` and `retry.md`.
|
|
|
|
### Auth middleware
|
|
|
|
- [ ] Implement `authMiddleware(token): HttpMiddleware` — adds `Authorization: Bearer <token>` header; `token` may be a function for dynamic tokens.
|
|
- [ ] Write `auth.test.ts` and `auth.md`.
|
|
|
|
### Rate-limit middleware
|
|
|
|
- [ ] Implement `rateLimitMiddleware(options): HttpMiddleware` — sliding-window request rate limiting using injectable `Clock`; queues excess requests.
|
|
- [ ] Write `rate-limit.test.ts` and `rate-limit.md`.
|
|
|
|
---
|
|
|
|
## 5. HttpClient
|
|
|
|
- [ ] Implement `HttpClient` — middleware chain dispatch, injectable `fetch`, body serialisation via `@suaveplan/serialize`, timeout via `AbortSignal.timeout`-compatible wrapper, response body deserialisation, `use()`.
|
|
- [ ] Wire OTel: span `http.request`, counter `http_request_total`, histogram `http_request_duration_ms`.
|
|
- [ ] Write `http-client.test.ts` (≤500 lines): GET/POST/PUT/DELETE with stub fetch, timeout, abort, 4xx throws `NETWORK_BAD_STATUS`, middleware chain order.
|
|
- [ ] Write `http-client.md`.
|
|
|
|
---
|
|
|
|
## 6. WebSocketClient
|
|
|
|
- [ ] Implement `WebSocketClient` — injectable `WebSocket`, auto-reconnect with `@suaveplan/retry` backoff, ping/pong keepalive using injectable `Clock`, `on()` event listener registry, `send()`, `connect()`, `disconnect()`.
|
|
- [ ] Wire OTel: counter `ws.reconnect_total`.
|
|
- [ ] Write `websocket-client.test.ts` (≤500 lines): connect, message, reconnect, max reconnects exceeded throws, abort on disconnect.
|
|
- [ ] Write `websocket-client.md`.
|
|
|
|
---
|
|
|
|
## 7. Benchmarks
|
|
|
|
- [ ] Write `src/__benchmarks__/network.bench.ts` — `buildUrl` with 10 params, middleware chain dispatch 5 middlewares no-op stub fetch.
|
|
|
|
---
|
|
|
|
## 8. Tests
|
|
|
|
- [ ] Write `tests/integration.test.ts` — `HttpClient` + middleware stack end-to-end with stub fetch.
|
|
- [ ] Write `tests/property.test.ts` (fast-check) — `buildUrl` round-trip, `parseQueryString(serializeQueryString(p)) deep equals p`.
|
|
|
|
---
|
|
|
|
## 9. Docs + verify + publish
|
|
|
|
- [ ] All co-located `.md` files (≥200 words each).
|
|
- [ ] Write `README.md` at package root.
|
|
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/network` — green.
|
|
- [ ] `bunx turbo test:coverage --filter=@suaveplan/network` — 100%.
|
|
- [ ] `bun scripts/publish.ts --package @suaveplan/network`.
|
|
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-network/`.
|