@objectstack/service-datasource 7.6.0

package/dist/index.d.ts

@@ -0,0 +1,414 @@
+import { IExternalDatasourceService, IntrospectedSchema, RemoteTable, GenerateDraftOpts, ObjectDraft, ImportObjectOpts, ImportObjectResult, SchemaValidationResult, SchemaValidationReport, ICryptoProvider, IHttpServer } from '@objectstack/spec/contracts';
+import { ExternalCatalog } from '@objectstack/spec/data';
+import { Plugin, PluginContext } from '@objectstack/core';
+import { IDatasourceAdminService, TestConnectionResult, SecretInput, DatasourceSummary, DatasourceDraft, IDatasourceDriverFactory } from './contracts/index.js';
+export { DatasourceConnectionSpec, DatasourceDriverHandle, DatasourceOrigin } from './contracts/index.js';
+
+/**
+ * ExternalDatasourceService — implements {@link IExternalDatasourceService}
+ * (ADR-0015 §6) on top of driver introspection.
+ *
+ * The service is intentionally decoupled from the kernel: all I/O
+ * (introspection, metadata reads) is injected via
+ * {@link ExternalDatasourceServiceConfig}, so the introspection/draft/validate
+ * logic is pure and unit-testable. The kernel plugin wires the real
+ * `IDataEngine` + `IMetadataService` callbacks in.
+ */
+
+/** Minimal datasource shape the service reads (subset of `Datasource`). */
+interface DatasourceLike {
+    name: string;
+    schemaMode?: 'managed' | 'external' | 'validate-only';
+    external?: {
+        allowedSchemas?: string[];
+        validation?: {
+            onMismatch?: 'fail' | 'warn' | 'ignore';
+        };
+    };
+}
+/** Minimal object shape the service reads (subset of `ServiceObject`). */
+interface ObjectLike {
+    name: string;
+    label?: string;
+    datasource?: string;
+    external?: {
+        remoteName?: string;
+        remoteSchema?: string;
+        columnMap?: Record<string, string>;
+        ignoreColumns?: string[];
+    };
+    fields?: Record<string, {
+        type?: string;
+        required?: boolean;
+    }>;
+}
+interface Logger$1 {
+    warn: (message: string, meta?: unknown) => void;
+    info?: (message: string, meta?: unknown) => void;
+}
+/**
+ * Injected dependencies. The plugin supplies real implementations backed by
+ * the driver registry and `IMetadataService`; tests supply fakes.
+ */
+interface ExternalDatasourceServiceConfig {
+    /** Introspect a datasource's live schema via its driver. */
+    introspect: (datasource: string) => Promise<IntrospectedSchema>;
+    /** Resolve a datasource definition by name. */
+    getDatasource: (name: string) => Promise<DatasourceLike | undefined>;
+    /** Resolve one object definition by name. */
+    getObject: (name: string) => Promise<ObjectLike | undefined>;
+    /** List all object definitions (for `validateAll`). */
+    listObjects: () => Promise<ObjectLike[]>;
+    /**
+     * Persist a refreshed catalog snapshot as an `external_catalog` metadata
+     * record. Optional: when absent, `refreshCatalog` still returns the snapshot
+     * but does not cache it (e.g. dev runs without a writable metadata store).
+     */
+    persistCatalog?: (catalog: ExternalCatalog) => Promise<void>;
+    /**
+     * Persist an imported object definition as a live (runtime-origin) `object`
+     * metadata record. Optional: when absent, {@link ExternalDatasourceService.importObject}
+     * throws (the deployment is GitOps-only / has no writable metadata store).
+     */
+    persistObject?: (name: string, definition: Record<string, unknown>) => Promise<void>;
+    logger?: Logger$1;
+}
+declare class ExternalDatasourceService implements IExternalDatasourceService {
+    private readonly config;
+    constructor(config: ExternalDatasourceServiceConfig);
+    private get logger();
+    private findTable;
+    listRemoteTables(datasource: string, opts?: {
+        schema?: string;
+    }): Promise<RemoteTable[]>;
+    generateObjectDraft(datasource: string, remoteName: string, opts?: GenerateDraftOpts): Promise<ObjectDraft>;
+    importObject(datasource: string, remoteName: string, opts?: ImportObjectOpts): Promise<ImportObjectResult>;
+    refreshCatalog(datasource: string): Promise<ExternalCatalog>;
+    validateObject(objectName: string): Promise<SchemaValidationResult>;
+    validateAll(): Promise<SchemaValidationReport>;
+}
+
+interface ExternalDatasourceServicePluginOptions {
+    /** Override the introspection function (mainly for tests). */
+    introspect?: (datasource: string) => Promise<IntrospectedSchema>;
+    logger?: Logger$1;
+}
+/**
+ * ExternalDatasourceServicePlugin — registers `IExternalDatasourceService`
+ * into the kernel as the `'external-datasource'` service (ADR-0015 §6.1).
+ *
+ * It bridges the decoupled {@link ExternalDatasourceService} to the live
+ * `IDataEngine` (for driver introspection) and `IMetadataService` (for object
+ * + datasource reads).
+ */
+declare class ExternalDatasourceServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    private service?;
+    private readonly options;
+    constructor(options?: ExternalDatasourceServicePluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * Minimal logger surface used by the runtime-admin half of this package.
+ * (Structurally identical to the federation service's own `Logger`; kept
+ * separate so the admin modules carry no internal import coupling.)
+ */
+interface Logger {
+    warn: (message: string, meta?: unknown) => void;
+    info?: (message: string, meta?: unknown) => void;
+}
+
+/**
+ * DatasourceAdminService — implements {@link IDatasourceAdminService}
+ * (ADR-0015 Addendum) on top of injected persistence + secret + driver probe
+ * callbacks.
+ *
+ * Like its federation sibling `ExternalDatasourceService`, this service is
+ * intentionally decoupled from the kernel: every side effect (connection probe,
+ * metadata read/write, secret write, bound-object count, hot pool (de)register)
+ * is injected via {@link DatasourceAdminServiceConfig}, so the lifecycle rules
+ * (origin gating, secret indirection, removal safety) are pure and unit-testable.
+ *
+ * Invariants enforced here, independent of the wiring:
+ *  - Code-defined datasources (`origin: 'code'`) are read-only — update/remove
+ *    reject them, and create refuses a name a code datasource already owns.
+ *  - A runtime datasource never shadows a code one (code wins on collision).
+ *  - Credentials never persist in cleartext: the cleartext {@link SecretInput}
+ *    transits create/update/test only; create/update write it to the secret
+ *    store and persist only the returned `credentialsRef`.
+ *  - Removal is refused while objects are still bound to the datasource.
+ */
+
+/**
+ * A persisted datasource record (subset of `Datasource`). `origin` distinguishes
+ * code-defined from runtime; `external.credentialsRef` is the opaque secret
+ * handle — never a cleartext credential.
+ */
+interface StoredDatasource {
+    name: string;
+    label?: string;
+    driver: string;
+    schemaMode?: 'managed' | 'external' | 'validate-only';
+    config?: Record<string, unknown>;
+    external?: (Record<string, unknown> & {
+        credentialsRef?: string;
+    }) | undefined;
+    pool?: Record<string, unknown>;
+    active?: boolean;
+    origin?: 'code' | 'runtime';
+    /** Package that defines a code-origin datasource, when known. */
+    definedIn?: string;
+}
+/** What a connection probe needs (cleartext secret is transient, never stored). */
+interface ProbeInput {
+    driver: string;
+    config: Record<string, unknown>;
+    /** Cleartext secret used for this probe only (e.g. password / DSN). */
+    secret?: string;
+    external?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+/**
+ * Injected dependencies. The plugin supplies real implementations backed by the
+ * driver registry, `IMetadataService` (runtime store), and the secret store;
+ * tests supply fakes.
+ */
+interface DatasourceAdminServiceConfig {
+    /** Probe a connection live (driver connect + cheap round-trip). */
+    probe: (input: ProbeInput) => Promise<TestConnectionResult>;
+    /** Read every datasource record (code + runtime). */
+    listDatasourceRecords: () => Promise<StoredDatasource[]>;
+    /** Read one datasource record by name. */
+    getDatasourceRecord: (name: string) => Promise<StoredDatasource | undefined>;
+    /** Persist a runtime datasource record into the runtime metadata store. */
+    putDatasourceRecord: (record: StoredDatasource) => Promise<void>;
+    /** Remove a runtime datasource record from the runtime metadata store. */
+    deleteDatasourceRecord: (name: string) => Promise<void>;
+    /** Encrypt + store a secret, returning an opaque `credentialsRef`. */
+    writeSecret: (input: SecretInput, hint: {
+        name: string;
+    }) => Promise<string>;
+    /** Best-effort delete of a stored secret by ref (cleanup on remove/rewrap). */
+    removeSecret?: (credentialsRef: string) => Promise<void>;
+    /** Count objects bound to a datasource (removal blocked while > 0). */
+    countBoundObjects: (datasource: string) => Promise<number>;
+    /** Hot-(re)register a runtime datasource's connection pool after write. */
+    registerPool?: (record: StoredDatasource) => Promise<void> | void;
+    /** Tear down a runtime datasource's pool on remove. */
+    unregisterPool?: (name: string) => Promise<void> | void;
+    logger?: Logger;
+}
+declare class DatasourceAdminService implements IDatasourceAdminService {
+    private readonly config;
+    constructor(config: DatasourceAdminServiceConfig);
+    private get logger();
+    listDatasources(): Promise<DatasourceSummary[]>;
+    testConnection(input: DatasourceDraft, secret?: SecretInput): Promise<TestConnectionResult>;
+    createDatasource(input: DatasourceDraft, secret?: SecretInput): Promise<DatasourceSummary>;
+    updateDatasource(name: string, patch: Partial<DatasourceDraft>, secret?: SecretInput): Promise<DatasourceSummary>;
+    removeDatasource(name: string): Promise<void>;
+    private assertValidName;
+    private toRecord;
+    private toSummary;
+    private tryRegisterPool;
+    private tryUnregisterPool;
+    private tryRemoveSecret;
+}
+
+/**
+ * Host-provided secret binding. Encrypts a cleartext credential into the secret
+ * store and returns an opaque `credentialsRef`; `unbind` deletes it. Wired by
+ * the stack that owns the `ICryptoProvider` + `sys_secret` store. When absent,
+ * the plugin fails *closed*: creating/updating a datasource *with* a secret
+ * throws rather than risk persisting cleartext.
+ */
+interface SecretBinder {
+    bind: (input: {
+        value: string;
+        namespace?: string;
+        key?: string;
+    }, hint: {
+        name: string;
+    }) => Promise<string>;
+    unbind?: (credentialsRef: string) => Promise<void>;
+    /**
+     * Dereference a `credentialsRef` back to cleartext for opening a live
+     * connection (boot rehydration + hot pool registration). Optional: when
+     * absent, pools for secret-bearing datasources are built without the
+     * credential (fine for credential-less drivers like sqlite/memory).
+     */
+    resolve?: (credentialsRef: string) => Promise<string | undefined>;
+}
+interface DatasourceAdminServicePluginOptions {
+    /** Secret binding backed by the host's crypto provider + `sys_secret`. */
+    secrets?: SecretBinder;
+    /** Override the driver factory (defaults to the `'datasource-driver-factory'` service). */
+    driverFactory?: IDatasourceDriverFactory;
+    logger?: Logger;
+}
+/**
+ * DatasourceAdminServicePlugin — registers `IDatasourceAdminService` into the
+ * kernel as the `'datasource-admin'` service (ADR-0015 Addendum).
+ *
+ * Bridges the decoupled {@link DatasourceAdminService} to live infrastructure:
+ *  - persistence + bound-object count via the `'metadata'` service
+ *    (`register`/`unregister` write through to the runtime DB loader),
+ *  - connection probe + hot pool (de)registration via the
+ *    `'datasource-driver-factory'` capability and the `'data'` engine,
+ *  - secret encryption via a host-provided {@link SecretBinder} (fail-closed).
+ *
+ * Every dependency degrades gracefully: a missing driver factory turns
+ * `testConnection` into a clear `{ ok: false }` and skips hot pool registration
+ * (the driver is picked up at next boot); a missing secret binder makes
+ * secret-bearing create/update fail loudly instead of leaking cleartext.
+ */
+declare class DatasourceAdminServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    private service?;
+    private config?;
+    private readonly options;
+    constructor(options?: DatasourceAdminServicePluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    /**
+     * Boot-time rehydration: list persisted runtime datasources and re-register
+     * each one's connection pool (driver build → connect → registerDriver),
+     * decrypting its `sys_secret` credential on the way via the configured
+     * `registerPool` (which resolves `credentialsRef`). Code-defined datasources
+     * are owned by the host stack's own boot path and skipped here. Entirely
+     * best-effort: a missing factory/engine, an unpersisted dev store (nothing
+     * to rehydrate), or a single failing pool never blocks boot.
+     */
+    private rehydratePools;
+    destroy(): Promise<void>;
+    private toSpec;
+    /** Probe a connection via the driver factory: build → connect → ping → close. */
+    private probe;
+}
+
+/**
+ * Default (dev/self-host) implementation of {@link IDatasourceDriverFactory}.
+ *
+ * The framework ships no universal "driver-by-id" registry — concrete drivers
+ * are constructed by the host stack (ADR-0015 Addendum §3.5). This factory is
+ * the host-side glue that lets the runtime-datasource lifecycle
+ * (`IDatasourceAdminService`) build a live driver from an *unsaved* draft so it
+ * can probe a connection before "Save" and hot-register a pool afterwards.
+ *
+ * Supported driver ids map onto the same open-core drivers the standalone
+ * stack auto-detects:
+ *   - `postgres` / `pg` / `postgresql` → `@objectstack/driver-sql` (client `pg`)
+ *   - `sqlite` / `sqlite3`             → `@objectstack/driver-sql` (better-sqlite3)
+ *   - `mongodb` / `mongo`             → `@objectstack/driver-mongodb` (peer dep)
+ *   - `memory` / `inmemory`           → `@objectstack/driver-memory`
+ *
+ * Anything else returns `supports() === false`, so the admin service degrades
+ * gracefully (testConnection → `{ ok: false }`, create skips hot pool reg).
+ *
+ * SECURITY: the cleartext `spec.secret` is used only to open the connection and
+ * is never persisted or logged here.
+ */
+
+/**
+ * Create the default datasource driver factory. Driver packages are imported
+ * lazily so a host that never builds (e.g.) a mongo connection doesn't pay for
+ * the mongo SDK.
+ */
+declare function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory;
+
+/**
+ * Default datasource SecretBinder — persists a runtime datasource's cleartext
+ * credential into the `sys_secret` cipher store and returns an opaque
+ * `credentialsRef` handle (ADR-0015 Addendum, security invariant).
+ *
+ * Mirrors the SettingsService Phase-3 split: the cleartext is wrapped by an
+ * {@link ICryptoProvider} into a {@link CryptoHandle}, the ciphertext lands in a
+ * `sys_secret` row keyed by `handle.id`, and only the handle id (wrapped as
+ * `sys_secret:<id>`) is ever stored on the datasource artefact. Cleartext never
+ * touches metadata.
+ *
+ * This is the dev/self-host wiring; production hosts swap the
+ * `LocalCryptoProvider` for a KMS-backed `ICryptoProvider` and pass it here.
+ */
+
+/** Minimal data-engine surface used to read/write the `sys_secret` store. */
+interface SecretStoreEngineLike {
+    insert(object: string, data: Record<string, unknown>, options?: unknown): Promise<unknown>;
+    delete(object: string, options: {
+        where: Record<string, unknown>;
+    }): Promise<unknown>;
+    /**
+     * Read `sys_secret` rows for the `resolve()` path. Optional so existing
+     * callers that only bind/unbind keep working; `resolve()` no-ops when absent.
+     * Mirrors `IDataEngine.find` — returns an array (or `{ data: [...] }`).
+     */
+    find?(object: string, query: Record<string, unknown>): Promise<unknown>;
+}
+interface DatasourceSecretBinderDeps {
+    /** Data engine (ObjectQL) used to persist the `sys_secret` row. */
+    engine: SecretStoreEngineLike;
+    /** Crypto provider that wraps cleartext into a {@link CryptoHandle}. */
+    cryptoProvider: ICryptoProvider;
+    /** Settings namespace recorded on the secret row (default `'datasource'`). */
+    namespace?: string;
+}
+interface DatasourceSecretBinder {
+    bind(input: {
+        value: string;
+        namespace?: string;
+        key?: string;
+    }, hint: {
+        name: string;
+    }): Promise<string>;
+    unbind(credentialsRef: string): Promise<void>;
+    /**
+     * Dereference a `credentialsRef` back to its cleartext credential by reading
+     * the `sys_secret` row and decrypting it. Used at boot to rebuild a runtime
+     * datasource's live connection pool (the cleartext is never persisted, so it
+     * must be recovered from the cipher store). Returns `undefined` when the ref
+     * isn't ours, the row is gone, the engine can't read, or decryption fails
+     * (e.g. an ephemeral dev key changed across restarts) — callers degrade to
+     * skipping that pool rather than crashing boot.
+     */
+    resolve(credentialsRef: string): Promise<string | undefined>;
+}
+/** Build a `credentialsRef` from a crypto handle id. */
+declare function toCredentialsRef(handleId: string): string;
+/** Extract the `sys_secret` handle id from a credentialsRef, if it is one. */
+declare function parseCredentialsRef(ref: string): string | undefined;
+/**
+ * Create the default datasource secret binder. Persists into `sys_secret` via
+ * the data engine and never returns or logs the cleartext.
+ */
+declare function createDatasourceSecretBinder(deps: DatasourceSecretBinderDeps): DatasourceSecretBinder;
+
+/**
+ * Datasource lifecycle REST routes (ADR-0015 Addendum §3.5).
+ *
+ * Mounted under `/api/v1/datasources` and served by the `datasource-admin`
+ * service. Every route degrades gracefully
+ * (`503 datasource_admin_unavailable`) when the service is not wired in, and
+ * lifecycle/validation failures surface as `400` with the service's message.
+ *
+ *   GET    /datasources              → listDatasources (provenance + health)
+ *   POST   /datasources/test         → testConnection (no persistence)
+ *   POST   /datasources              → createDatasource (origin: 'runtime')
+ *   PATCH  /datasources/:name        → updateDatasource (runtime only)
+ *   DELETE /datasources/:name        → removeDatasource (runtime only)
+ *
+ * Request bodies carry the connection draft inline with an optional cleartext
+ * `secret` field; the route splits `secret` out so it never reaches the draft
+ * the service persists.
+ */
+declare function registerDatasourceAdminRoutes(server: IHttpServer, ctx: PluginContext, basePath?: string): void;
+
+export { DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, type ObjectLike, type ProbeInput, type SecretBinder, SecretInput, type SecretStoreEngineLike, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, parseCredentialsRef, registerDatasourceAdminRoutes, toCredentialsRef };