@objectstack/service-datasource 7.6.0

package/dist/contracts/index.d.cts

@@ -0,0 +1,178 @@
+/**
+ * IDatasourceAdminService — runtime datasource lifecycle contract
+ * (ADR-0015 Addendum: Runtime UI-Created Datasources).
+ *
+ * Where {@link IExternalDatasourceService} covers *federation* (introspection,
+ * object drafting, schema validation) of datasources that already exist, this
+ * service covers their *lifecycle*: testing a connection before saving,
+ * creating / updating / removing a **runtime** datasource (`origin: 'runtime'`),
+ * and listing all datasources with their provenance + health.
+ *
+ * Code-defined datasources (`origin: 'code'`, authored as `*.datasource.ts`)
+ * are read-only here: `updateDatasource` / `removeDatasource` reject them, and
+ * a runtime datasource never shadows a code one of the same name (code wins).
+ *
+ * Credentials are never persisted in cleartext: callers pass a {@link SecretInput}
+ * separately from the connection `config`; the implementation encrypts it into
+ * the secret store (`sys_secret`) and persists only an opaque `credentialsRef`.
+ */
+/** Provenance of a datasource definition. */
+type DatasourceOrigin = 'code' | 'runtime';
+/**
+ * A cleartext secret (password or full connection string) supplied for a
+ * create/update/test call. Never persisted as-is — encrypted into the secret
+ * store, with only the returned handle (`credentialsRef`) kept on the record.
+ */
+interface SecretInput {
+    /** The cleartext value to encrypt (e.g. password or connection string). */
+    value: string;
+    /** Optional secret-store namespace (defaults to `'datasource'`). */
+    namespace?: string;
+    /** Optional secret-store key (defaults to the datasource name). */
+    key?: string;
+}
+/**
+ * The connection definition a caller supplies to test/create/update. A subset
+ * of `Datasource` — server-managed fields (`origin`) are never accepted from
+ * the client.
+ */
+interface DatasourceDraft {
+    name: string;
+    label?: string;
+    driver: string;
+    schemaMode?: 'managed' | 'external' | 'validate-only';
+    /** Driver-specific connection config (host, port, database, …). No secrets. */
+    config?: Record<string, unknown>;
+    /** External federation settings (required when schemaMode != 'managed'). */
+    external?: Record<string, unknown>;
+    pool?: Record<string, unknown>;
+    active?: boolean;
+}
+/** Result of probing a connection (live driver connect + cheap round-trip). */
+interface TestConnectionResult {
+    ok: boolean;
+    /** Round-trip latency of the probe, when the connection succeeded. */
+    latencyMs?: number;
+    /** Driver-reported server version, when available. */
+    serverVersion?: string;
+    /** Human-readable failure reason, when `ok === false`. */
+    error?: string;
+}
+/** A datasource with its provenance and current health (no secrets). */
+interface DatasourceSummary {
+    name: string;
+    label?: string;
+    driver: string;
+    schemaMode: 'managed' | 'external' | 'validate-only';
+    origin: DatasourceOrigin;
+    active: boolean;
+    /** Validation health: `unvalidated` until the first validate/test runs. */
+    status: 'ok' | 'error' | 'unvalidated';
+    /** Package id that defines a code-origin datasource (omitted for runtime). */
+    definedIn?: string;
+    /** True when a runtime row is shadowed by a code definition of the same name. */
+    conflictsWithCode?: boolean;
+}
+/**
+ * Runtime datasource lifecycle service. Registered into the kernel as the
+ * `'datasource-admin'` service; consumed by the REST layer and Studio wizard.
+ */
+interface IDatasourceAdminService {
+    /** List every datasource (code + runtime) with provenance and health. */
+    listDatasources(): Promise<DatasourceSummary[]>;
+    /**
+     * Probe a connection without persisting anything. Accepts an unsaved draft
+     * so the wizard can validate credentials before "Save".
+     */
+    testConnection(input: DatasourceDraft, secret?: SecretInput): Promise<TestConnectionResult>;
+    /**
+     * Persist a new runtime datasource (`origin: 'runtime'`, environment-scoped).
+     * Rejects when a code-defined datasource of the same name exists.
+     */
+    createDatasource(input: DatasourceDraft, secret?: SecretInput): Promise<DatasourceSummary>;
+    /**
+     * Patch an existing runtime datasource. Rejects for code-defined datasources.
+     * Passing `secret` re-wraps the stored credential.
+     */
+    updateDatasource(name: string, patch: Partial<DatasourceDraft>, secret?: SecretInput): Promise<DatasourceSummary>;
+    /**
+     * Remove a runtime datasource. Rejects for code-defined ones and while
+     * objects are still bound to it.
+     */
+    removeDatasource(name: string): Promise<void>;
+}
+
+/**
+ * IDatasourceDriverFactory — host-provided capability that builds a live driver
+ * from a connection spec (ADR-0015 Addendum §3.5).
+ *
+ * The framework deliberately ships no universal "driver-by-id" registry —
+ * concrete drivers (`SqlDriver`, `MongoDBDriver`, `TursoDriver`, …) are
+ * constructed by the host stack and registered as live connections. The
+ * runtime-datasource lifecycle (`IDatasourceAdminService`) needs to build a
+ * driver from an *unsaved* draft — to probe a connection before "Save", and to
+ * hot-register a pool after create/update — so the host exposes this factory
+ * as the `'datasource-driver-factory'` service.
+ *
+ * When no factory is registered, or none `supports()` a given driver id, the
+ * admin service degrades gracefully: `testConnection` returns
+ * `{ ok: false, error }` and create/update skip hot pool registration (the
+ * driver is picked up on the next boot instead).
+ *
+ * Security: the cleartext `secret` on {@link DatasourceConnectionSpec} is used
+ * only to open the live connection. Factories MUST NOT persist or log it.
+ */
+/** Everything needed to construct one live driver connection. */
+interface DatasourceConnectionSpec {
+    /** Datasource name, when building for an existing/named datasource. */
+    name?: string;
+    /** Driver id (e.g. `'postgres'`, `'sqlite'`, `'mongodb'`). */
+    driver: string;
+    /** Driver-specific connection config (host, port, database, …). No secrets. */
+    config: Record<string, unknown>;
+    /** Cleartext secret (password / DSN) injected for this connection only. */
+    secret?: string;
+    /** External federation settings (timeouts, allowed schemas, …). */
+    external?: Record<string, unknown>;
+    /** Connection pool settings. */
+    pool?: Record<string, unknown>;
+}
+/**
+ * A live (or lazily-connecting) driver handle. Intentionally structural and
+ * fully optional so any concrete driver satisfies it — the admin service uses
+ * whatever capabilities are present and skips the rest.
+ */
+interface DatasourceDriverHandle {
+    /** Open the connection / pool. */
+    connect?(): Promise<void>;
+    /** Close the connection / pool. */
+    disconnect?(): Promise<void>;
+    /** Cheap liveness round-trip (preferred for probes). */
+    ping?(): Promise<unknown>;
+    /** Introspect the live schema (fallback probe when `ping` is absent). */
+    introspectSchema?(): Promise<unknown>;
+    /** Liveness check on the underlying engine driver (probe fallback). */
+    checkHealth?(): Promise<boolean>;
+    /** Driver-reported server version, when available. */
+    serverVersion?(): Promise<string | undefined>;
+    /**
+     * Escape hatch: the concrete engine driver to hand to
+     * `IDataEngine.registerDriver()` when hot-registering a pool. When present
+     * the admin service registers *this* (whose `.name` must equal the
+     * datasource name for routing) instead of the handle itself; absent ⇒ the
+     * handle is assumed to be the driver. Never serialized.
+     */
+    driver?: unknown;
+}
+/** Host-provided factory that builds drivers from connection specs. */
+interface IDatasourceDriverFactory {
+    /** True if this factory can build a driver for the given driver id. */
+    supports(driverId: string): boolean;
+    /**
+     * Build a driver instance for the spec. Implementations may return a
+     * not-yet-connected handle; the caller calls `connect()` when needed.
+     */
+    create(spec: DatasourceConnectionSpec): Promise<DatasourceDriverHandle> | DatasourceDriverHandle;
+}
+
+export type { DatasourceConnectionSpec, DatasourceDraft, DatasourceDriverHandle, DatasourceOrigin, DatasourceSummary, IDatasourceAdminService, IDatasourceDriverFactory, SecretInput, TestConnectionResult };

package/dist/contracts/index.d.ts

@@ -0,0 +1,178 @@
+/**
+ * IDatasourceAdminService — runtime datasource lifecycle contract
+ * (ADR-0015 Addendum: Runtime UI-Created Datasources).
+ *
+ * Where {@link IExternalDatasourceService} covers *federation* (introspection,
+ * object drafting, schema validation) of datasources that already exist, this
+ * service covers their *lifecycle*: testing a connection before saving,
+ * creating / updating / removing a **runtime** datasource (`origin: 'runtime'`),
+ * and listing all datasources with their provenance + health.
+ *
+ * Code-defined datasources (`origin: 'code'`, authored as `*.datasource.ts`)
+ * are read-only here: `updateDatasource` / `removeDatasource` reject them, and
+ * a runtime datasource never shadows a code one of the same name (code wins).
+ *
+ * Credentials are never persisted in cleartext: callers pass a {@link SecretInput}
+ * separately from the connection `config`; the implementation encrypts it into
+ * the secret store (`sys_secret`) and persists only an opaque `credentialsRef`.
+ */
+/** Provenance of a datasource definition. */
+type DatasourceOrigin = 'code' | 'runtime';
+/**
+ * A cleartext secret (password or full connection string) supplied for a
+ * create/update/test call. Never persisted as-is — encrypted into the secret
+ * store, with only the returned handle (`credentialsRef`) kept on the record.
+ */
+interface SecretInput {
+    /** The cleartext value to encrypt (e.g. password or connection string). */
+    value: string;
+    /** Optional secret-store namespace (defaults to `'datasource'`). */
+    namespace?: string;
+    /** Optional secret-store key (defaults to the datasource name). */
+    key?: string;
+}
+/**
+ * The connection definition a caller supplies to test/create/update. A subset
+ * of `Datasource` — server-managed fields (`origin`) are never accepted from
+ * the client.
+ */
+interface DatasourceDraft {
+    name: string;
+    label?: string;
+    driver: string;
+    schemaMode?: 'managed' | 'external' | 'validate-only';
+    /** Driver-specific connection config (host, port, database, …). No secrets. */
+    config?: Record<string, unknown>;
+    /** External federation settings (required when schemaMode != 'managed'). */
+    external?: Record<string, unknown>;
+    pool?: Record<string, unknown>;
+    active?: boolean;
+}
+/** Result of probing a connection (live driver connect + cheap round-trip). */
+interface TestConnectionResult {
+    ok: boolean;
+    /** Round-trip latency of the probe, when the connection succeeded. */
+    latencyMs?: number;
+    /** Driver-reported server version, when available. */
+    serverVersion?: string;
+    /** Human-readable failure reason, when `ok === false`. */
+    error?: string;
+}
+/** A datasource with its provenance and current health (no secrets). */
+interface DatasourceSummary {
+    name: string;
+    label?: string;
+    driver: string;
+    schemaMode: 'managed' | 'external' | 'validate-only';
+    origin: DatasourceOrigin;
+    active: boolean;
+    /** Validation health: `unvalidated` until the first validate/test runs. */
+    status: 'ok' | 'error' | 'unvalidated';
+    /** Package id that defines a code-origin datasource (omitted for runtime). */
+    definedIn?: string;
+    /** True when a runtime row is shadowed by a code definition of the same name. */
+    conflictsWithCode?: boolean;
+}
+/**
+ * Runtime datasource lifecycle service. Registered into the kernel as the
+ * `'datasource-admin'` service; consumed by the REST layer and Studio wizard.
+ */
+interface IDatasourceAdminService {
+    /** List every datasource (code + runtime) with provenance and health. */
+    listDatasources(): Promise<DatasourceSummary[]>;
+    /**
+     * Probe a connection without persisting anything. Accepts an unsaved draft
+     * so the wizard can validate credentials before "Save".
+     */
+    testConnection(input: DatasourceDraft, secret?: SecretInput): Promise<TestConnectionResult>;
+    /**
+     * Persist a new runtime datasource (`origin: 'runtime'`, environment-scoped).
+     * Rejects when a code-defined datasource of the same name exists.
+     */
+    createDatasource(input: DatasourceDraft, secret?: SecretInput): Promise<DatasourceSummary>;
+    /**
+     * Patch an existing runtime datasource. Rejects for code-defined datasources.
+     * Passing `secret` re-wraps the stored credential.
+     */
+    updateDatasource(name: string, patch: Partial<DatasourceDraft>, secret?: SecretInput): Promise<DatasourceSummary>;
+    /**
+     * Remove a runtime datasource. Rejects for code-defined ones and while
+     * objects are still bound to it.
+     */
+    removeDatasource(name: string): Promise<void>;
+}
+
+/**
+ * IDatasourceDriverFactory — host-provided capability that builds a live driver
+ * from a connection spec (ADR-0015 Addendum §3.5).
+ *
+ * The framework deliberately ships no universal "driver-by-id" registry —
+ * concrete drivers (`SqlDriver`, `MongoDBDriver`, `TursoDriver`, …) are
+ * constructed by the host stack and registered as live connections. The
+ * runtime-datasource lifecycle (`IDatasourceAdminService`) needs to build a
+ * driver from an *unsaved* draft — to probe a connection before "Save", and to
+ * hot-register a pool after create/update — so the host exposes this factory
+ * as the `'datasource-driver-factory'` service.
+ *
+ * When no factory is registered, or none `supports()` a given driver id, the
+ * admin service degrades gracefully: `testConnection` returns
+ * `{ ok: false, error }` and create/update skip hot pool registration (the
+ * driver is picked up on the next boot instead).
+ *
+ * Security: the cleartext `secret` on {@link DatasourceConnectionSpec} is used
+ * only to open the live connection. Factories MUST NOT persist or log it.
+ */
+/** Everything needed to construct one live driver connection. */
+interface DatasourceConnectionSpec {
+    /** Datasource name, when building for an existing/named datasource. */
+    name?: string;
+    /** Driver id (e.g. `'postgres'`, `'sqlite'`, `'mongodb'`). */
+    driver: string;
+    /** Driver-specific connection config (host, port, database, …). No secrets. */
+    config: Record<string, unknown>;
+    /** Cleartext secret (password / DSN) injected for this connection only. */
+    secret?: string;
+    /** External federation settings (timeouts, allowed schemas, …). */
+    external?: Record<string, unknown>;
+    /** Connection pool settings. */
+    pool?: Record<string, unknown>;
+}
+/**
+ * A live (or lazily-connecting) driver handle. Intentionally structural and
+ * fully optional so any concrete driver satisfies it — the admin service uses
+ * whatever capabilities are present and skips the rest.
+ */
+interface DatasourceDriverHandle {
+    /** Open the connection / pool. */
+    connect?(): Promise<void>;
+    /** Close the connection / pool. */
+    disconnect?(): Promise<void>;
+    /** Cheap liveness round-trip (preferred for probes). */
+    ping?(): Promise<unknown>;
+    /** Introspect the live schema (fallback probe when `ping` is absent). */
+    introspectSchema?(): Promise<unknown>;
+    /** Liveness check on the underlying engine driver (probe fallback). */
+    checkHealth?(): Promise<boolean>;
+    /** Driver-reported server version, when available. */
+    serverVersion?(): Promise<string | undefined>;
+    /**
+     * Escape hatch: the concrete engine driver to hand to
+     * `IDataEngine.registerDriver()` when hot-registering a pool. When present
+     * the admin service registers *this* (whose `.name` must equal the
+     * datasource name for routing) instead of the handle itself; absent ⇒ the
+     * handle is assumed to be the driver. Never serialized.
+     */
+    driver?: unknown;
+}
+/** Host-provided factory that builds drivers from connection specs. */
+interface IDatasourceDriverFactory {
+    /** True if this factory can build a driver for the given driver id. */
+    supports(driverId: string): boolean;
+    /**
+     * Build a driver instance for the spec. Implementations may return a
+     * not-yet-connected handle; the caller calls `connect()` when needed.
+     */
+    create(spec: DatasourceConnectionSpec): Promise<DatasourceDriverHandle> | DatasourceDriverHandle;
+}
+
+export type { DatasourceConnectionSpec, DatasourceDraft, DatasourceDriverHandle, DatasourceOrigin, DatasourceSummary, IDatasourceAdminService, IDatasourceDriverFactory, SecretInput, TestConnectionResult };

package/dist/contracts/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}