@objectstack/service-datasource 10.0.0 → 10.2.0

package/dist/index.js

@@ -1,3 +1,7 @@
+import {
+  allowAllConnectPolicy
+} from "./chunk-XLS4RP7B.js";
+
 // src/external-datasource-service.ts
 import {
   suggestFieldType,
@@ -368,6 +372,179 @@ function safeGetService(ctx, name) {
   }
 }
 
+// src/datasource-connection-service.ts
+function isDatasourceAddressed(ds, ctx) {
+  if (ds.schemaMode && ds.schemaMode !== "managed") return true;
+  if (ds.autoConnect === true) return true;
+  if (ctx.objects?.some((o) => o?.datasource === ds.name)) return true;
+  return false;
+}
+var DatasourceConnectionService = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.policy = cfg.policy ?? allowAllConnectPolicy;
+    this.logger = cfg.logger;
+  }
+  /**
+   * Auto-connect the declared (code-defined) datasources that pass the D2 gate.
+   * Called from `AppPlugin.start()` with the app bundle's datasources + objects.
+   * Each connected external datasource also has its bound objects' read metadata
+   * synced so they are immediately queryable with zero app code.
+   */
+  async connectDeclared(input) {
+    const objects = input.objects ?? [];
+    const results = [];
+    for (const ds of input.datasources) {
+      if (!ds?.name) continue;
+      if (ds.active === false) continue;
+      if (!isDatasourceAddressed(ds, { objects })) continue;
+      const bound = objects.filter((o) => o?.datasource === ds.name && typeof o?.name === "string").map((o) => o.name);
+      results.push(
+        await this.connect(ds, { objects: bound, context: { origin: ds.origin ?? "code", trigger: "declared-auto" } })
+      );
+    }
+    return results;
+  }
+  /**
+   * Build + connect + register a single datasource's live driver. The shared
+   * core used by both auto-connect and the runtime-admin pool registration.
+   *
+   * Failure policy (ADR-0062 D5): an `external` datasource with
+   * `validation.onMismatch: 'fail'` fails fast (re-throws, bricking boot as
+   * intended); everything else degrades with a warning so an optional replica's
+   * connectivity blip never bricks boot.
+   */
+  async connect(record, opts = {}) {
+    const name = record.name;
+    const engine = this.cfg.engine();
+    const factory = this.cfg.factory();
+    if (engine?.getDriverByName?.(name)) {
+      return { name, status: "already-registered" };
+    }
+    let decision;
+    try {
+      decision = await this.policy.canConnect(
+        { name, driver: record.driver, schemaMode: record.schemaMode, external: record.external },
+        opts.context
+      );
+    } catch (err) {
+      decision = { allow: false, reason: `connect policy threw: ${errMsg(err)}` };
+    }
+    if (!decision.allow) {
+      this.logger?.info?.(`datasource '${name}': connect denied by policy${decision.reason ? ` (${decision.reason})` : ""}`);
+      return { name, status: "skipped-policy", reason: decision.reason };
+    }
+    if (!factory || !engine?.registerDriver) {
+      this.logger?.debug?.(`datasource '${name}': no driver factory / engine \u2014 left metadata-only`);
+      return { name, status: "skipped-no-infra" };
+    }
+    if (!factory.supports(record.driver)) {
+      return this.handleFailure(
+        record,
+        "skipped-unsupported",
+        `no driver factory supports driver '${record.driver}'`,
+        opts.context
+      );
+    }
+    let secret;
+    const credentialsRef = record.external?.credentialsRef;
+    if (credentialsRef) {
+      const resolver = this.cfg.secrets?.resolve;
+      if (!resolver) {
+        return this.handleFailure(
+          record,
+          "failed-credentials",
+          `requires credential '${credentialsRef}' but no secret store (SecretBinder/ICryptoProvider) is configured`,
+          opts.context
+        );
+      }
+      try {
+        secret = await resolver(credentialsRef);
+      } catch (err) {
+        return this.handleFailure(record, "failed-credentials", `resolving credential '${credentialsRef}' threw: ${errMsg(err)}`, opts.context);
+      }
+      if (secret == null || secret === "") {
+        return this.handleFailure(
+          record,
+          "failed-credentials",
+          `credential '${credentialsRef}' could not be resolved or decrypted (missing sys_secret row, or the encryption key changed)`,
+          opts.context
+        );
+      }
+    }
+    try {
+      const handle = await factory.create({ ...toSpec(record), ...secret ? { secret } : {} });
+      if (typeof handle?.connect === "function") await handle.connect();
+      const engineDriver = handle.driver ?? handle;
+      try {
+        engineDriver.name = name;
+      } catch {
+      }
+      engine.registerDriver(engineDriver);
+      engine.registerDatasourceDef?.({
+        name,
+        schemaMode: record.schemaMode,
+        external: record.external
+      });
+      for (const objectName of opts.objects ?? []) {
+        try {
+          await engine.syncObjectSchema?.(objectName);
+        } catch (err) {
+          this.logger?.warn?.(`datasource '${name}': syncObjectSchema('${objectName}') failed: ${errMsg(err)}`);
+        }
+      }
+      this.logger?.info?.(`datasource '${name}': connected (driver=${record.driver}, schemaMode=${record.schemaMode ?? "managed"})`);
+      return { name, status: "connected" };
+    } catch (err) {
+      return this.handleFailure(record, "failed-degraded", errMsg(err), opts.context);
+    }
+  }
+  /** Gracefully disconnect a previously-registered datasource pool. */
+  async disconnect(name) {
+    const driver = this.cfg.engine()?.getDriverByName?.(name);
+    if (typeof driver?.disconnect === "function") {
+      try {
+        await driver.disconnect();
+      } catch (err) {
+        this.logger?.warn?.(`datasource '${name}': disconnect failed: ${errMsg(err)}`);
+      }
+    }
+  }
+  /**
+   * Apply the D5 connect-failure policy (also covers D3 credential failures). A
+   * code-defined `external` datasource with `onMismatch:'fail'` auto-connected at
+   * boot re-throws (fail-fast, bricking boot as intended). Runtime-admin
+   * create/update + boot rehydration always degrade-with-warning — a UI action
+   * or a replica blip must never brick the running server (preserves the
+   * pre-ADR-0062 admin behavior). Either way the datasource is left unconnected
+   * with a clear message — never a silent skip.
+   */
+  handleFailure(record, status, reason, context) {
+    const isExternal = record.schemaMode && record.schemaMode !== "managed";
+    const failFast = context?.trigger === "declared-auto" && isExternal && record.external?.validation?.onMismatch === "fail";
+    const msg = `datasource '${record.name}': connect failed \u2014 ${reason}`;
+    if (failFast) {
+      throw new Error(
+        `${msg}. (schemaMode=${record.schemaMode}, validation.onMismatch='fail' \u21D2 fail-fast per ADR-0062 D5)`
+      );
+    }
+    this.logger?.warn?.(`${msg} \u2014 degrading (datasource left unconnected)`);
+    return { name: record.name, status, reason };
+  }
+};
+function toSpec(record) {
+  return {
+    name: record.name,
+    driver: record.driver,
+    config: record.config ?? {},
+    external: record.external,
+    pool: record.pool
+  };
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/datasource-admin-service.ts
 var NAME_RE = /^[a-z_][a-z0-9_]*$/;
 var DatasourceAdminService = class {
@@ -647,6 +824,14 @@ var DatasourceAdminServicePlugin = class {
     const metadataOf = () => safeGetService2(ctx, "metadata");
     const engineOf = () => safeGetService2(ctx, "data");
     const factory = () => this.options.driverFactory ?? safeGetService2(ctx, "datasource-driver-factory");
+    this.connection = new DatasourceConnectionService({
+      factory,
+      engine: () => engineOf(),
+      secrets: { resolve: (ref) => this.options.secrets?.resolve?.(ref) ?? Promise.resolve(void 0) },
+      policy: this.options.connectPolicy,
+      logger: this.options.logger
+    });
+    ctx.registerService("datasource-connection", this.connection);
     const config = {
       probe: (input) => this.probe(factory(), input),
       listDatasourceRecords: async () => {
@@ -690,29 +875,20 @@ var DatasourceAdminServicePlugin = class {
         const objects = await metadata?.listObjects?.() ?? await metadata?.list("object") ?? [];
         return objects.filter((o) => o?.datasource === datasource).length;
       },
+      // Hot pool (de)registration converges on the shared
+      // DatasourceConnectionService (ADR-0062 D1) — one connect path for code-
+      // and runtime-origin datasources. `connect()` builds the driver via the
+      // factory, dereferences `external.credentialsRef` through the SecretBinder,
+      // opens the connection, and registers the live driver + datasource def.
+      // Runtime-admin connects always degrade-with-warning on failure (never
+      // fail-fast), preserving the pre-ADR-0062 admin behavior.
       registerPool: async (record) => {
-        const f = factory();
-        const engine = engineOf();
-        if (!f || !engine?.registerDriver || !f.supports(record.driver)) return;
-        const credentialsRef = record.external?.credentialsRef;
-        const secret = credentialsRef ? await this.options.secrets?.resolve?.(credentialsRef) : void 0;
-        const handle = await f.create({ ...this.toSpec(record), ...secret ? { secret } : {} });
-        if (typeof handle?.connect === "function") await handle.connect();
-        const engineDriver = handle.driver ?? handle;
-        try {
-          engineDriver.name = record.name;
-        } catch {
-        }
-        engine.registerDriver(engineDriver);
-        engine.registerDatasourceDef?.({
-          name: record.name,
-          schemaMode: record.schemaMode,
-          external: record.external
+        await this.connection?.connect(record, {
+          context: { origin: record.origin ?? "runtime", trigger: "runtime-admin" }
         });
       },
       unregisterPool: async (name) => {
-        const driver = engineOf()?.getDriverByName?.(name);
-        if (typeof driver?.disconnect === "function") await driver.disconnect();
+        await this.connection?.disconnect(name);
       },
       logger
     };
@@ -821,15 +997,6 @@ var DatasourceAdminServicePlugin = class {
     this.service = void 0;
   }
   // --- internals -----------------------------------------------------------
-  toSpec(record) {
-    return {
-      name: record.name,
-      driver: record.driver,
-      config: record.config ?? {},
-      external: record.external,
-      pool: record.pool
-    };
-  }
   /** Probe a connection via the driver factory: build → connect → ping → close. */
   async probe(factory, input) {
     if (!factory) {
@@ -847,7 +1014,7 @@ var DatasourceAdminServicePlugin = class {
         external: input.external
       });
     } catch (err) {
-      return { ok: false, error: `Failed to build driver: ${errMsg(err)}` };
+      return { ok: false, error: `Failed to build driver: ${errMsg2(err)}` };
     }
     const startedAt = monotonicNow();
     try {
@@ -863,7 +1030,7 @@ var DatasourceAdminServicePlugin = class {
       }
       return { ok: true, latencyMs, ...serverVersion ? { serverVersion } : {} };
     } catch (err) {
-      return { ok: false, error: errMsg(err) };
+      return { ok: false, error: errMsg2(err) };
     } finally {
       try {
         if (typeof driver?.disconnect === "function") await driver.disconnect();
@@ -879,7 +1046,7 @@ function safeGetService2(ctx, name) {
     return void 0;
   }
 }
-function errMsg(err) {
+function errMsg2(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function monotonicNow() {
@@ -1280,10 +1447,13 @@ function registerDatasourceAdminRoutes(server, ctx, basePath = "/api/v1") {
 export {
   DatasourceAdminService,
   DatasourceAdminServicePlugin,
+  DatasourceConnectionService,
   ExternalDatasourceService,
   ExternalDatasourceServicePlugin,
+  allowAllConnectPolicy,
   createDatasourceSecretBinder,
   createDefaultDatasourceDriverFactory,
+  isDatasourceAddressed,
   parseCredentialsRef,
   registerDatasourceAdminRoutes,
   toCredentialsRef