84 lines
9.0 KiB
Markdown
84 lines
9.0 KiB
Markdown
# Add @suaveplan/api-plugin-database (Path A — wraps SurrealAdapter)
|
|
|
|
**Package**: `@suaveplan/api-plugin-database`
|
|
**Status**: PROPOSED
|
|
**Type**: new-package
|
|
|
|
- **Spec delta**: ./specs/api-plugin-database/spec.md
|
|
|
|
## Why
|
|
|
|
`@suaveplan/api` plugin hosts need a one-shot way to bring up a SurrealDB-backed `DatabaseAdapter` with production-grade orthogonals: a connection pool, an advisory-locked migration runner, tenant provisioning, retry/backoff, RFC 7807 error rendering, and a full OTel surface. Genesis already ships `@suaveplan/surrealdb` (which exposes `SurrealAdapter` implementing `@suaveplan/db`'s `DatabaseAdapter`) and `@suaveplan/api-migrations` (which ships a real SurrealQL migration adapter and runner). Without this plugin, every consuming app must hand-wire those primitives, and the cross-cutting pool/tenancy/retry/problem-json/OTel pieces fall on application code.
|
|
|
|
The upstream `../suaveplan/packages/server/api-plugin-database/` re-implements its own `SurrealAdapter`, exposes an adapter surface (`query`/`select`/`create`/`update`/`delete`/`transaction`/`use`/`info`/`getClient`/`releaseClient`/`getPoolSize`) that is irreconcilable with genesis's `DatabaseAdapter` shape, and hangs tenant lifecycle off a descriptor hook (`onTenantCreate` / `onTenantDelete`) that genesis's `PluginDescriptor` does not carry. Path A is therefore: keep the orthogonal surface upstream contributed (pool, migrations, tenancy callable, retry, problem-json, OTel, error codes), but bind every adapter call to the canonical `SurrealAdapter` and expose it via `ServiceRegistry["db"]: DatabaseAdapter`.
|
|
|
|
## What changes
|
|
|
|
- ADDED: `createDatabasePlugin(options?)` — `PluginDescriptor<DatabasePluginConfig>` factory using `definePlugin`. `onInit` builds the pool, registers `db` in `ServiceRegistry`. `onReady` auto-runs migrations under advisory lock. `onClose` drains the pool.
|
|
- ADDED: `ConnectionPool` — bounded pool of `SurrealAdapter` instances with min/max sizing, idle reaping, `acquireTimeoutMs`, waiter queue, and `size()` introspection.
|
|
- ADDED: Migration ledger + advisory lock + runner integrating with `@suaveplan/api-migrations` (`createSurrealqlAdapter` + `createMigrationRunner`) plus a thin lock layer on top.
|
|
- ADDED: `provisionTenant(adapter, config, tenantId)` / `decommissionTenant(adapter, config, tenantId)` callable exports supporting `shared` | `namespace-per-tenant` | `database-per-tenant`.
|
|
- ADDED: `withRetry(fn, options)` — exponential backoff with optional jitter.
|
|
- ADDED: `respondProblemJson(c, err)` — RFC 7807 renderer that consults the registered `DATABASE_*` error metadata.
|
|
- ADDED: `DATABASE_CODES` registry (8 codes via `defineCodes`) + concrete `DatabaseError` extending `SuaveplanError`.
|
|
- ADDED: `DatabasePluginOptionsSchema` / `DatabasePluginConfigSchema` Zod boundary on every public option bundle.
|
|
- ADDED: OTel instrument bundle (`pool.checkouts_total`, `pool.checkins_total`, `pool.saturation`, `query.duration_ms` histogram keyed by `{ outcome }`, `migrations.applied_total`).
|
|
- ADDED: `ServiceRegistry.db` augmentation (`DatabaseAdapter` slot) consumed by every downstream plugin.
|
|
|
|
## Out of scope
|
|
|
|
- A re-implementation of `SurrealAdapter.query`/`select`/`create`/`update`/`delete`/`transaction`/`use`/`info`/`getClient`/`releaseClient`/`getPoolSize` — every consumer obtains the pooled `DatabaseAdapter` via `ctx.getService("db")` and calls the canonical surface defined by `@suaveplan/db`.
|
|
- Descriptor-level `onTenantCreate` / `onTenantDelete` hooks — the genesis `PluginDescriptor` has no tenant-lifecycle slots; tenant lifecycle ships as the callable exports `provisionTenant` / `decommissionTenant` plus a documented event-bus integration pattern (`api-plugin-tenant` invokes them on its own tenant-create/delete events).
|
|
|
|
## Source mapping
|
|
|
|
This change derives from `../suaveplan/enterprise/api-plugin-database.md` and the upstream source tree `../suaveplan/packages/server/api-plugin-database/`.
|
|
|
|
| Requirement | Source | Notes |
|
|
|---|---|---|
|
|
| Connection pool | `src/pool/connection-pool.ts` | Reworked to pool `SurrealAdapter` instances rather than raw `Surreal` clients so pool members implement `DatabaseAdapter`. |
|
|
| Migration runner / ledger / lock | `src/migrations/runner/runner.ts`, `src/migrations/ledger/ledger.ts`, `src/migrations/lock/lock.ts`, `src/migrations/discovery/discovery.ts` | Discovery delegated to `@suaveplan/api-migrations` `createMigrationRunner` + `createSurrealqlAdapter`; advisory lock layered on top. |
|
|
| Tenancy provisioning callables | `src/tenancy/tenant-lifecycle.ts` | Re-exported as callable functions instead of descriptor hooks (platform constraint). |
|
|
| Retry / backoff | `src/retry/retry.ts` | Verbatim API, Zod-validated options. |
|
|
| RFC 7807 problem-json | `src/routes/problem-json.ts` | Bound to `@suaveplan/error`'s formatter; uses local `DATABASE_*` metadata. |
|
|
| Plugin factory | `src/plugin/create-database-plugin.ts` | Rewritten on top of genesis `definePlugin` + `ServiceRegistry`; no `onTenantCreate/Delete` hooks. |
|
|
| `DATABASE_*` error codes | `src/errors/error-codes.ts` | Registered via genesis `defineCodes` + `SuaveplanError`. |
|
|
| OTel surface | `enterprise/api-plugin-database.md` §3 | Pool checkout/checkin, query duration histogram, migration counter (delegates to `api-migrations` for the migrations counter, mounts pool/query locally). |
|
|
| Zod boundary | `src/config/config-schema.ts` | Re-shaped under genesis Zod v4 import convention. |
|
|
|
|
### Excluded from this migration
|
|
|
|
- `SurrealAdapter.query(sql, vars: Record)` — 🚫 superseded by `@suaveplan/surrealdb` `SurrealAdapter`. Consumers call `ctx.getService("db").query(sql, params: readonly unknown[])` per the `@suaveplan/db` `DatabaseAdapter` contract.
|
|
- `SurrealAdapter.queryOne` — 🚫 superseded; consumers call `(await db.query(...))[0]` or use the standard adapter pattern.
|
|
- `SurrealAdapter.select(table, id)` / `.create(table, data)` / `.update(table, id, data)` / `.delete(table, id)` — 🚫 superseded by `SurrealAdapter`'s native CRUD methods exposed on `DatabaseAdapter`.
|
|
- `SurrealAdapter.transaction(): Transaction` (the inversion-of-control transaction handle pattern) — 🚫 superseded by `DatabaseAdapter.transaction(fn, opts)` callback-style transactions defined by `@suaveplan/db`.
|
|
- `SurrealAdapter.use(ns, db)` / `.info()` / `.ping()` — 🚫 superseded by `SurrealAdapter`'s lifecycle (`connect`/`disconnect`/`isConnected`); namespace/database are set at construction time.
|
|
- `SurrealAdapter.getClient()` / `.releaseClient(c)` / `.getPoolSize()` — 🚫 platform mismatch. Genesis pools `SurrealAdapter` instances (each owning its own client); callers acquire via `pool.acquire()` and release via `pool.release(adapter)`. Pool size is reported by `pool.size()`.
|
|
- Descriptor `onTenantCreate(ctx, tenantId)` / `onTenantDelete(ctx, tenantId)` hooks — 🚫 platform constraint: genesis `PluginDescriptor` has no tenant-lifecycle hook slots. Equivalent functionality ships as `provisionTenant(adapter, config, tenantId)` and `decommissionTenant(adapter, config, tenantId)` callable exports that `@suaveplan/api-plugin-tenant` (or any host) invokes explicitly on its own tenant-lifecycle events via the existing event bus.
|
|
- Back-compat `"surreal"` service alias — 🚫 not part of the genesis contract; the canonical slot is `db`.
|
|
- `databaseMiddleware` Hono middleware — 🚫 genesis pattern is `ctx.getService("db")` from the host; the plugin does not contribute middleware.
|
|
|
|
## Verification approach
|
|
|
|
- `src/error-codes/error-codes.test.ts` — every `DATABASE_*` code is thrown from a production path.
|
|
- `src/retry/retry.test.ts` — exponential backoff, jitter, abort-aware retry.
|
|
- `src/pool/pool.test.ts` — pool acquires/releases, max-size waiter queue, `acquireTimeoutMs`, idle reaper, close drain.
|
|
- `src/migrations/lock.test.ts` — advisory lock with lease expiry, takeover, release.
|
|
- `src/migrations/runner.test.ts` — `.surql` discovery, ledger apply, drift detection, advisory-lock integration.
|
|
- `src/tenancy/tenancy.test.ts` — all three strategies provision/decommission with tenant-id validation.
|
|
- `src/routes/problem-json.test.ts` — RFC 7807 shape for `DatabaseError`, `HttpError`, and unknown throwables.
|
|
- `src/config/config-schema.test.ts` — Zod boundary accepts canonical input and rejects out-of-range knobs.
|
|
- `src/otel/instruments.test.ts` — every counter/histogram emits against an in-memory `MeterProvider`.
|
|
- `src/plugin/plugin.test.ts` — full lifecycle: `onInit` builds pool + registers service, `onReady` migrates under lock, `onClose` drains pool.
|
|
- `tests/integration/full-boot.test.ts` — real SurrealDB testcontainer via `@suaveplan/testing-integration-surrealdb`, full pool + migration + tenancy roundtrip.
|
|
|
|
## Migration impact
|
|
|
|
None — additive new package.
|
|
|
|
## Impact
|
|
|
|
### Affected dependents
|
|
|
|
No existing dependents (verified by `bunx turbo ls --filter=...@suaveplan/api-plugin-database` — new package). Downstream packages that will consume `ServiceRegistry["db"]` (e.g. `api-plugin-user`, future `api-plugin-tenant`) augment the registry themselves; this plugin only seeds `db`.
|