83 lines
2.6 KiB
Markdown
83 lines
2.6 KiB
Markdown
# OpenSpec Change: enterprise-api-plugin-database
|
|
|
|
- **Change ID**: enterprise-api-plugin-database
|
|
- **Package**: `@suaveplan/api-plugin-database`
|
|
- **Category**: api/data
|
|
- **Target path**: `api/data/api-plugin-database`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-database.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-database` on the genesis branch from scratch at enterprise quality. Foundation database plugin for the API tier: wraps `@suaveplan/surrealdb` (or any `DatabaseAdapter`-compatible backend), provides `getDb()` helper for downstream plugins, runs SurrealQL migrations at boot, exposes a `/health/db` readiness probe, and registers a `DatabaseService` with connection-pool stats. This is the dependency declared by almost every other plugin; it must land first in the dependency wave. Events: `database:connected`, `database:error`.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
|
|
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
|
|
| `@suaveplan/db` (`workspace:^`) | `DatabaseAdapter` interface |
|
|
| `@suaveplan/error` (`workspace:^`) | `DatabasePluginError` hierarchy |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
|
|
| `@suaveplan/events` (`workspace:^`) | Event bus |
|
|
| `@suaveplan/logger` (`workspace:^`) | Structured logging |
|
|
| `hono` + `@hono/zod-openapi` + `zod` | Routes |
|
|
| `@opentelemetry/api` | OTel |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
function createDatabasePlugin(config: DatabasePluginConfig): PluginDescriptor<DatabasePluginConfig>
|
|
|
|
// Registered service accessible by downstream plugins:
|
|
interface DatabaseService {
|
|
getDb(): DatabaseAdapter
|
|
runMigrations(path: string): Promise<MigrationResult>
|
|
healthCheck(): Promise<{ status: 'ok' | 'degraded'; latencyMs: number }>
|
|
getStats(): DatabaseStats
|
|
}
|
|
|
|
interface DatabasePluginConfig {
|
|
adapter: DatabaseAdapter // injected; typically @suaveplan/surrealdb
|
|
migrationsBasePath?: string
|
|
}
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type DatabasePluginErrorCode =
|
|
| "DB_CONNECTION_FAILED"
|
|
| "DB_MIGRATION_FAILED"
|
|
| "DB_HEALTH_CHECK_FAILED"
|
|
| "DB_NOT_INITIALIZED"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
api/data/api-plugin-database/
|
|
package.json tsconfig.json vitest.config.ts
|
|
src/
|
|
index.ts events.ts types/ errors/
|
|
services/database/
|
|
routes/health/
|
|
tests/integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
This is the most critical dependency: every other plugin with `dependencies: ["database"]` requires this plugin. Must be published first. Prerequisites: `@suaveplan/api`, `@suaveplan/db`, `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/logger`.
|