122 lines
4.8 KiB
Markdown
122 lines
4.8 KiB
Markdown
# OpenSpec Change: enterprise-network-rename
|
|
|
|
- **Change ID**: enterprise-network-rename
|
|
- **Package**: `@suaveplan/network-client` (renamed from `@suaveplan/network`)
|
|
- **Category**: universal
|
|
- **Target path**: `universal/network/network-client`
|
|
- **Status**: SUPERSEDED-BY-GENESIS-WAVE
|
|
- **Date**: 2026-05-01
|
|
- **Replaces**: `enterprise-network` (2026-04-24)
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Resolve the package-name collision between `enterprise-network` (HttpClient + WebSocketClient utilities, dated 2026-04-24) and `network-core` (plugin-based mesh core, dated 2026-04-29). The mesh core has already shipped code at `packages/network/network/` and owns the `@suaveplan/network` package name. This change renames the HTTP/WebSocket utility package to `@suaveplan/network-client` and moves its target path from `universal/network/network` to `universal/network/network-client`.
|
|
|
|
No functionality changes — only package name, path, and internal references.
|
|
|
|
---
|
|
|
|
## Why the rename is necessary
|
|
|
|
| Proposal | Date | Target Package | Target Path | Status |
|
|
|---|---|---|---|---|
|
|
| `enterprise-network` | 2026-04-24 | `@suaveplan/network` | `universal/network/network` | Proposed, not yet implemented |
|
|
| `network-core` | 2026-04-29 | `@suaveplan/network` | `packages/network/network` | **Shipped** — source, tests, and build artifacts exist |
|
|
|
|
`packages/network/network/` already contains:
|
|
|
|
- `src/` with `NetworkNode`, `NetworkBus`, `NetworkPlugin`, `MessageEnvelope`, `Transport`
|
|
- `package.json` with `"name": "@suaveplan/network"`
|
|
- Built `dist/` and `tsconfig.tsbuildinfo`
|
|
|
|
Two packages cannot share the same npm scope + name. Because the mesh core is already instantiated in the monorepo, the HTTP/WebSocket client package must yield the name.
|
|
|
|
---
|
|
|
|
## What changes
|
|
|
|
### 1. Package name
|
|
|
|
From `@suaveplan/network` → `@suaveplan/network-client`
|
|
|
|
### 2. Target path
|
|
|
|
From `universal/network/network` → `universal/network/network-client`
|
|
|
|
### 3. Class and export names
|
|
|
|
To avoid confusion with the mesh core's `NetworkNode` and `NetworkBus`:
|
|
|
|
| Old name | New name | Reason |
|
|
|---|---|---|
|
|
| `NetworkError` | `NetworkClientError` | Disambiguate from mesh `NetError` / `NETWORK_CODES` |
|
|
| `HttpClient` | `HttpClient` | Unchanged — scoped by package import |
|
|
| `WebSocketClient` | `WebSocketClient` | Unchanged — scoped by package import |
|
|
| `createHttpClient` | `createHttpClient` | Unchanged |
|
|
| `createWebSocketClient` | `createWebSocketClient` | Unchanged |
|
|
| `NETWORK_ERROR_METADATA` | `NETWORK_CLIENT_ERROR_METADATA` | Align with new error class |
|
|
| `registerNetworkErrorCodes` | `registerNetworkClientErrorCodes` | Align with new error class |
|
|
|
|
### 4. Error code namespace
|
|
|
|
From `defineCodes("NETWORK", [...])` → `defineCodes("NET_CLIENT", [...])`
|
|
|
|
Codes:
|
|
|
|
- `NET_CLIENT_REQUEST_FAILED`
|
|
- `NET_CLIENT_TIMEOUT`
|
|
- `NET_CLIENT_ABORT`
|
|
- `NET_CLIENT_BAD_STATUS`
|
|
- `NET_CLIENT_PARSE_FAILED`
|
|
- `NET_CLIENT_WS_CONNECT_FAILED`
|
|
- `NET_CLIENT_WS_SEND_FAILED`
|
|
- `NET_CLIENT_WS_MAX_RECONNECTS`
|
|
- `NET_CLIENT_INVALID_URL`
|
|
|
|
### 5. Internal references
|
|
|
|
All middleware, built-ins, and tests reference the new error class and code namespace.
|
|
|
|
---
|
|
|
|
## Public API (unchanged shape, new package scope)
|
|
|
|
```ts
|
|
import { HttpClient, WebSocketClient, buildUrl } from "@suaveplan/network-client";
|
|
```
|
|
|
|
The API surface remains identical to the original `enterprise-network` proposal:
|
|
|
|
- `HttpClient` with middleware pipeline (`use()`)
|
|
- `WebSocketClient` with auto-reconnect, backpressure, ping/pong
|
|
- URL utilities (`buildUrl`, `parseQueryString`, `serializeQueryString`, `isAbsoluteUrl`, `joinPaths`)
|
|
- Injectable `fetch` and `WebSocket` constructors
|
|
- Built-in middleware: `loggingMiddleware`, `retryMiddleware`, `authMiddleware`, `rateLimitMiddleware`
|
|
|
|
---
|
|
|
|
## Downstream impact
|
|
|
|
Any genesis package that planned to import `@suaveplan/network` for HTTP/WebSocket utilities must instead import `@suaveplan/network-client`. At the time of this change, no genesis package has such an import because `enterprise-network` was not yet implemented.
|
|
|
|
Packages that consume the mesh core (`@suaveplan/network`) are unaffected.
|
|
|
|
---
|
|
|
|
## Verification approach
|
|
|
|
- `src/error-codes.spec-conformance.test.ts` — pins `NET_CLIENT.*` code registry is frozen.
|
|
- `src/core/http-client/http-client.spec-conformance.test.ts` — pins request/response shape, middleware chain order, injectable fetch.
|
|
- `src/core/websocket-client/websocket-client.spec-conformance.test.ts` — pins reconnect behaviour, ping/pong, injectable WebSocket.
|
|
- `src/utils/url.spec-conformance.test.ts` — pins round-trip property for buildUrl/parseQueryString.
|
|
- `tests/dep-graph.test.ts` — pins no import of `@suaveplan/network` (the mesh core) from this package.
|
|
- 100/100/100/100 Istanbul coverage.
|
|
|
|
---
|
|
|
|
## Migration impact
|
|
|
|
None within genesis — additive rename of an unimplemented proposal. The old `enterprise-network` change is superseded by this one and should be archived once this is approved.
|