109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
# OpenSpec Change: enterprise-server-network-gundb-server
|
|
|
|
- **Change ID**: enterprise-server-network-gundb-server
|
|
- **Package**: `@suaveplan/network-gundb-server`
|
|
- **Category**: server/network
|
|
- **Target path**: `server/network/network-gundb-server`
|
|
- **Status**: SUPERSEDED-BY-GENESIS-WAVE
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/network-gundb-server.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/network-gundb-server` on the genesis branch from scratch at enterprise quality. The package runs a Gun.js relay server over WebSockets, enabling decentralised real-time data sync for browser and server peers. It wraps Gun's `GUN({web: server})` pattern into a typed `GunServerAdapter` with `start` / `stop`, `get` / `put` / `on` / `off` for direct data operations on the server side, and connection-count observability. Genesis adds Zod-validated options, `@suaveplan/error` codes, OTel gauges, structured logging, and full integration tests.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Does not exist on genesis — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | Typed `NETWORK_GUNDB.*` error codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
|
| `@suaveplan/logger` (`workspace:^`) | Structured logs |
|
|
| `zod` (`catalog:forms`) | Options validation |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Gauges + counters |
|
|
| `gun` (`catalog:network`) | Gun.js database/relay |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
class GunServerAdapter {
|
|
constructor(options: GunServerOptions)
|
|
start(): Promise<void>
|
|
stop(): Promise<void>
|
|
get<T = unknown>(path: string): Promise<T | undefined>
|
|
put(path: string, data: unknown): Promise<void>
|
|
on<T = unknown>(path: string, handler: (data: T, key: string) => void): () => void
|
|
peerCount(): number
|
|
isRunning(): boolean
|
|
address(): { host: string; port: number } | undefined
|
|
}
|
|
|
|
function createGunServerAdapter(options: GunServerOptions): GunServerAdapter
|
|
|
|
interface GunServerOptions {
|
|
port?: number // default: 8765
|
|
host?: string // default: '0.0.0.0'
|
|
peers?: string[] // bootstrap relay URLs
|
|
radisk?: boolean // persist to disk, default: false
|
|
logger?: LoggerLike
|
|
}
|
|
|
|
const GunServerOptionsSchema: z.ZodSchema<GunServerOptions>
|
|
|
|
type GunServerErrorCode =
|
|
| 'NETWORK_GUNDB_START_FAILED'
|
|
| 'NETWORK_GUNDB_STOP_FAILED'
|
|
| 'NETWORK_GUNDB_PUT_FAILED'
|
|
| 'NETWORK_GUNDB_GET_TIMEOUT'
|
|
|
|
function registerGunServerErrorCodes(): void
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
server/network/network-gundb-server/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/index.ts
|
|
types/
|
|
gundb-server.types.ts
|
|
gundb-server.types.md
|
|
adapter/
|
|
gun-server-adapter/
|
|
gun-server-adapter.ts
|
|
gun-server-adapter.md
|
|
gun-server-adapter.types.ts
|
|
gun-server-adapter.test.ts
|
|
index.ts
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Downstream: real-time sync features, collaborative editing, offline-first client sync. Server-only.
|
|
|
|
**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`.
|