@forgezero/providers 0.1.4 → 0.1.6

package/dist/binance.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/chain.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/chain.ts
 var hexToNumber = (value) => Number(BigInt(value));

package/dist/database.d.ts

@@ -13,36 +13,108 @@
  *   HEALTH       three failed connections mark it degraded, and the same admin
  *                screen that shows email relays shows the database
  *
- * `failover: false` is therefore the default and a deliberate one. Set it true
- * only for read replicas, where answering from a stale replica beats not
- * answering.
+ * Coordinator routing below remains inside one authenticated cluster. It never
+ * treats a different database or replica as an automatic write destination.
  */
 /** Just enough of an ArangoDB client that this package imports nothing. */
 export interface ArangoLike {
-    query<T = unknown>(query: unknown, bindVars?: Record<string, unknown>): Promise<{
+    query<T = unknown>(query: unknown, bindVars?: Record<string, unknown>, options?: {
+        allowDirtyRead?: boolean;
+    }): Promise<{
         all(): Promise<T[]>;
     }>;
     version?(): Promise<{
         version: string;
     }>;
+    close?(): void | Promise<void>;
 }
-export interface ArangoConfig {
+export interface ArangoConnectOptions {
+    /** One coordinator from the verified list; the adapter owns selection. */
     url: string;
     database: string;
     username: string;
+    password: string;
+    loadBalancingStrategy: 'NONE';
+    /** Always zero: only this adapter may decide whether replay is safe. */
+    maxRetries: number;
+}
+export interface ArangoConfig {
+    /** Backwards-compatible single-coordinator coordinate. */
+    url?: string;
+    /** Explicit authenticated private coordinators. Bounded to prevent config abuse. */
+    urls?: readonly string[];
+    /**
+     * Dynamic membership is accepted only as a signed/attested envelope verified
+     * by the host. A Worker/KV node list by itself is discovery data, not routing
+     * authority.
+     */
+    membership?: ArangoMembershipSnapshot;
+    verifyMembership?: ArangoMembershipVerifier;
+    /** Required with dynamic membership, preventing a valid list crossing clusters. */
+    clusterId?: string;
+    database: string;
+    username: string;
     /** Built by the host, because a connection pool must outlive one call. */
-    connect?: (options: {
-        url: string;
-        database: string;
-        username: string;
-        password: string;
-    }) => ArangoLike;
-    failover?: boolean;
+    connect?: (options: ArangoConnectOptions) => ArangoLike;
+    /** Maximum coordinator attempts for an explicitly safe request. */
+    maxCoordinatorAttempts?: number;
+    /** Local transport-failure quarantine. Primarily injectable for tests. */
+    unhealthyForMs?: number;
+    now?: () => number;
 }
 export interface Query {
     query: unknown;
     bindVars?: Record<string, unknown>;
+    /**
+     * No retry is the secure default. `read` and `idempotent` are explicit
+     * caller assertions; this adapter never guesses AQL semantics from text.
+     */
+    retrySafety?: 'read' | 'idempotent' | 'never';
+    /** Required when `retrySafety` is `idempotent`; retained for audit correlation. */
+    idempotencyKey?: string;
 }
+export interface ArangoCoordinatorMember {
+    url: string;
+    /** Clients address Coordinators; Community 3.11.14 has no read-only joiner role. */
+    role: 'coordinator';
+    /** Actual `/_admin/server/mode` state for this Coordinator. */
+    serverMode: 'default';
+    capabilities: {
+        /** Always false for the exact Community 3.11.14 contract. */
+        dirtyFollowerReads: false;
+    };
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Milliseconds since epoch, covered by the membership signature/attestation. */
+    observedAt: number;
+    /** Enrolled hybrid identity. The node key is its Ed25519 public half. */
+    nodeKey: string;
+    publicKeys: {
+        ed25519: string;
+        mlDsa: string;
+    };
+}
+export interface ArangoMembershipSnapshot {
+    authority: 'forgezero-platform-signed' | 'node-attested';
+    edition: 'community';
+    version: '3.11.14';
+    clusterId: string;
+    revision: string;
+    issuedAt: number;
+    expiresAt: number;
+    coordinators: readonly ArangoCoordinatorMember[];
+}
+export type ArangoMembershipVerifier = (snapshot: ArangoMembershipSnapshot, signal?: AbortSignal) => Promise<boolean>;
+export declare const MAX_ARANGO_COORDINATORS = 16;
+export declare const ARANGO_COMMUNITY_VERSION: "3.11.14";
+/** Protected API used to attest cluster-wide `default`/maintenance mode. */
+export declare const ARANGO_SERVER_MODE_PATH: "/_admin/server/mode";
+/**
+ * Accept only an explicit, bounded set of private authenticated endpoints.
+ * Service discovery may propose a new list, but it must pass this authority
+ * boundary before a fresh pool is created; public Worker/KV state is never a
+ * database routing authority.
+ */
+export declare function arangoCoordinatorUrls(config: Pick<ArangoConfig, 'url' | 'urls'>): readonly string[];
 export declare const arangodb: import("./index").ProviderSpec<Query, unknown[]>;
 /** Drop memoised connections. Tests, and after a credential rotation. */
 export declare function resetPools(): void;

package/dist/database.js

@@ -144,15 +144,148 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/database.ts
 var pools = new Map;
+var MAX_ARANGO_COORDINATORS = 16;
+var ARANGO_COMMUNITY_VERSION = "3.11.14";
+var ARANGO_SERVER_MODE_PATH = "/_admin/server/mode";
+function arangoCoordinatorUrls(config) {
+  const input = config.urls ?? (config.url ? [config.url] : []);
+  if (input.length < 1 || input.length > MAX_ARANGO_COORDINATORS) {
+    throw new ProviderError("ARANGO_COORDINATORS_INVALID", `ArangoDB needs from 1 to ${MAX_ARANGO_COORDINATORS} private coordinator URLs.`);
+  }
+  const normalized = input.map((raw) => {
+    let value;
+    try {
+      value = new URL(raw);
+    } catch {
+      throw new ProviderError("ARANGO_COORDINATORS_INVALID", "ArangoDB coordinator URL is malformed.");
+    }
+    if (value.protocol !== "http:" && value.protocol !== "https:") {
+      throw new ProviderError("ARANGO_COORDINATORS_INVALID", "ArangoDB coordinators must use HTTP or HTTPS.");
+    }
+    if (value.username || value.password || value.search || value.hash || value.pathname && value.pathname !== "/") {
+      throw new ProviderError("ARANGO_COORDINATORS_INVALID", "ArangoDB coordinator URLs contain origins only; credentials and paths are separate.");
+    }
+    const hostname = value.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    const ipv4 = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)?.slice(1).map(Number);
+    const privateV4 = ipv4 && ipv4.every((part) => part >= 0 && part <= 255) && (ipv4[0] === 10 || ipv4[0] === 127 || ipv4[0] === 172 && ipv4[1] >= 16 && ipv4[1] <= 31 || ipv4[0] === 192 && ipv4[1] === 168);
+    const privateV6 = hostname === "::1" || /^f[cd][0-9a-f]:/i.test(hostname);
+    if (!privateV4 && !privateV6 && hostname !== "localhost") {
+      throw new ProviderError("ARANGO_COORDINATORS_INVALID", "ArangoDB coordinators must be literal private or loopback endpoints.");
+    }
+    value.hostname = value.hostname.toLowerCase();
+    return value.toString().replace(/\/$/, "");
+  });
+  if (new Set(normalized).size !== normalized.length) {
+    throw new ProviderError("ARANGO_COORDINATORS_INVALID", "ArangoDB coordinator URLs must be unique.");
+  }
+  return normalized;
+}
+async function resolveMembership(config, signal) {
+  if (!config.membership) {
+    const urls = arangoCoordinatorUrls(config);
+    return {
+      members: urls.map((url) => ({
+        url,
+        role: "coordinator",
+        serverMode: "default",
+        capabilities: { dirtyFollowerReads: false },
+        status: "healthy"
+      })),
+      identity: `static:${urls.join(",")}`
+    };
+  }
+  if (config.url || config.urls) {
+    throw new ProviderError("ARANGO_MEMBERSHIP_AMBIGUOUS", "Configure static coordinator URLs or verified membership, not both.");
+  }
+  if (!config.clusterId || config.membership.clusterId !== config.clusterId) {
+    throw new ProviderError("ARANGO_MEMBERSHIP_CLUSTER", "Verified ArangoDB membership does not match the configured cluster.");
+  }
+  if (!config.verifyMembership || !await config.verifyMembership(config.membership, signal)) {
+    throw new ProviderError("ARANGO_MEMBERSHIP_UNVERIFIED", "Dynamic ArangoDB membership must pass the host signature or attestation verifier.");
+  }
+  const now = (config.now ?? Date.now)();
+  const snapshot = config.membership;
+  if (snapshot.edition !== "community" || snapshot.version !== ARANGO_COMMUNITY_VERSION) {
+    throw new ProviderError("ARANGO_MEMBERSHIP_CONTRACT", `Dynamic ArangoDB membership must describe Community ${ARANGO_COMMUNITY_VERSION}.`);
+  }
+  if (!Number.isFinite(snapshot.issuedAt) || !Number.isFinite(snapshot.expiresAt) || snapshot.issuedAt > now || snapshot.expiresAt <= now) {
+    throw new ProviderError("ARANGO_MEMBERSHIP_EXPIRED", "Dynamic ArangoDB membership is not currently valid.");
+  }
+  const validAuthority = snapshot.authority === "forgezero-platform-signed" || snapshot.authority === "node-attested";
+  const validNodes = snapshot.coordinators.every((node) => Number.isFinite(node.observedAt) && node.nodeKey.length > 0 && node.nodeKey === node.publicKeys?.ed25519 && Boolean(node.publicKeys.mlDsa) && (node.status === "healthy" || node.status === "degraded" || node.status === "unhealthy") && node.role === "coordinator" && node.serverMode === "default" && node.capabilities?.dirtyFollowerReads === false);
+  if (!validAuthority || !snapshot.revision || !validNodes) {
+    throw new ProviderError("ARANGO_MEMBERSHIP_INVALID", "Dynamic ArangoDB membership needs a revision and observed timestamps.");
+  }
+  const allUrls = arangoCoordinatorUrls({ urls: snapshot.coordinators.map((node) => node.url) });
+  const members = allUrls.map((url, index) => ({ ...snapshot.coordinators[index], url })).filter((member) => member.status !== "unhealthy");
+  if (members.length === 0) {
+    throw new ProviderError("ARANGO_COORDINATORS_UNAVAILABLE", "Verified membership has no healthy or degraded ArangoDB coordinator.");
+  }
+  return {
+    members,
+    identity: `membership:${snapshot.clusterId}`,
+    issuedAt: snapshot.issuedAt,
+    revision: snapshot.revision
+  };
+}
+function retryableCoordinatorFailure(error) {
+  const failure = error;
+  const status = typeof failure.code === "number" ? failure.code : failure.status;
+  if (status === 408 || status === 429 || status === 502 || status === 503 || status === 504)
+    return true;
+  return typeof failure.code === "string" && [
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ETIMEDOUT"
+  ].includes(failure.code);
+}
+function boundedAttempts(config, available, safe) {
+  if (!safe)
+    return 1;
+  const requested = config.maxCoordinatorAttempts ?? available;
+  if (!Number.isInteger(requested) || requested < 1 || requested > MAX_ARANGO_COORDINATORS) {
+    throw new ProviderError("ARANGO_ATTEMPTS_INVALID", `ArangoDB coordinator attempts must be from 1 to ${MAX_ARANGO_COORDINATORS}.`);
+  }
+  return Math.min(requested, available);
+}
+function requestIsSafe(request) {
+  if (request.retrySafety === "read")
+    return true;
+  if (request.retrySafety !== "idempotent")
+    return false;
+  if (!request.idempotencyKey || request.idempotencyKey.length > 128) {
+    throw new ProviderError("ARANGO_IDEMPOTENCY_KEY_INVALID", "An idempotent ArangoDB retry needs a non-empty idempotency key of at most 128 characters.");
+  }
+  return true;
+}
+function selectNode(pool, excluded, now, eligibleMember) {
+  const eligible = pool.nodes.filter((node) => !excluded.has(node.url) && node.unhealthyUntil <= now && eligibleMember(node));
+  if (eligible.length === 0)
+    return;
+  const least = Math.min(...eligible.map((node) => node.inFlight));
+  for (let offset = 0;offset < pool.nodes.length; offset += 1) {
+    const index = (pool.cursor + offset) % pool.nodes.length;
+    const node = pool.nodes[index];
+    if (!excluded.has(node.url) && node.unhealthyUntil <= now && eligibleMember(node) && node.inFlight === least) {
+      pool.cursor = (index + 1) % pool.nodes.length;
+      return node;
+    }
+  }
+  return;
+}
+function nodeForRequest(pool, excluded, now) {
+  return selectNode(pool, excluded, now, () => true);
+}
 var arangodb = defineProvider({
   id: "arangodb",
   service: "database",
   label: "ArangoDB",
-  multiInstance: true,
   credentials: {
     type: "object",
     additionalProperties: false,
@@ -164,20 +297,45 @@ var arangodb = defineProvider({
   config: {
     type: "object",
     additionalProperties: false,
-    required: ["url", "database", "username"],
+    required: ["database", "username"],
+    anyOf: [
+      { required: ["url"] },
+      { required: ["urls"] },
+      { required: ["clusterId"] }
+    ],
     properties: {
       url: {
         type: "string",
         title: "URL",
         description: "Bind to loopback. A database reachable from the internet is a database that will be."
       },
+      urls: {
+        type: "array",
+        minItems: 1,
+        maxItems: MAX_ARANGO_COORDINATORS,
+        uniqueItems: true,
+        items: { type: "string" },
+        title: "Coordinator URLs",
+        description: "Authenticated private coordinators in this one logical cluster."
+      },
+      clusterId: {
+        type: "string",
+        title: "Cluster ID",
+        description: "Binds host-verified dynamic membership to one logical cluster."
+      },
       database: { type: "string", title: "Database" },
       username: { type: "string", title: "Username" },
-      failover: {
-        type: "boolean",
-        default: false,
-        title: "Allow failover",
-        description: "Off by default. Writing to a different database because the first was slow is data loss with extra steps. Enable only for read replicas."
+      maxCoordinatorAttempts: {
+        type: "integer",
+        minimum: 1,
+        maximum: MAX_ARANGO_COORDINATORS,
+        title: "Safe request attempts"
+      },
+      unhealthyForMs: {
+        type: "integer",
+        minimum: 1000,
+        maximum: 300000,
+        title: "Local coordinator quarantine (ms)"
       }
     }
   },
@@ -186,35 +344,111 @@ var arangodb = defineProvider({
     if (!config.connect) {
       throw new ProviderError("ARANGO_NO_CONNECT", "Provide a connect function in this provider's config — arangojs on a server; a database is not reachable from an edge runtime.");
     }
-    const key = `${config.url}/${config.database}/${config.username}`;
-    let client = pools.get(key);
-    if (!client) {
-      client = config.connect({
-        url: config.url,
-        database: config.database,
-        username: config.username,
-        password: await context.secret("password")
+    const membership = await resolveMembership(config, context.signal);
+    const members = membership.members;
+    const urls = members.map(({ url }) => url);
+    const safe = requestIsSafe(request);
+    const available = members.length;
+    if (available === 0) {
+      throw new ProviderError("ARANGO_COORDINATORS_UNAVAILABLE", "No verified authoritative ArangoDB coordinator is available.");
+    }
+    const attempts = boundedAttempts(config, available, safe);
+    const key = `${membership.identity}/${config.database}/${config.username}`;
+    let pool = pools.get(key);
+    if (!pool) {
+      const password = await context.secret("password");
+      pool = {
+        nodes: members.map((member) => ({
+          url: member.url,
+          member,
+          client: config.connect({
+            url: member.url,
+            database: config.database,
+            username: config.username,
+            password,
+            loadBalancingStrategy: "NONE",
+            maxRetries: 0
+          }),
+          inFlight: 0,
+          unhealthyUntil: 0
+        })),
+        cursor: 0,
+        membershipIssuedAt: membership.issuedAt,
+        membershipRevision: membership.revision
+      };
+      pools.set(key, pool);
+    } else if (membership.issuedAt !== undefined) {
+      if (pool.membershipIssuedAt !== undefined && membership.issuedAt < pool.membershipIssuedAt) {
+        throw new ProviderError("ARANGO_MEMBERSHIP_ROLLBACK", "ArangoDB membership is older than the last accepted signed revision.");
+      }
+      const existing = new Map(pool.nodes.map((node) => [node.url, node]));
+      const missing = urls.filter((url) => !existing.has(url));
+      const password = missing.length > 0 ? await context.secret("password") : undefined;
+      const nextNodes = members.map((member) => {
+        const retained2 = existing.get(member.url);
+        if (retained2) {
+          retained2.member = member;
+          return retained2;
+        }
+        return {
+          url: member.url,
+          member,
+          client: config.connect({
+            url: member.url,
+            database: config.database,
+            username: config.username,
+            password,
+            loadBalancingStrategy: "NONE",
+            maxRetries: 0
+          }),
+          inFlight: 0,
+          unhealthyUntil: 0
+        };
       });
-      pools.set(key, client);
+      const retained = new Set(urls);
+      for (const removed of pool.nodes.filter((node) => !retained.has(node.url) && node.inFlight === 0)) {
+        try {
+          await removed.client.close?.();
+        } catch {}
+      }
+      pool.nodes = nextNodes;
+      pool.cursor %= nextNodes.length;
+      pool.membershipIssuedAt = membership.issuedAt;
+      pool.membershipRevision = membership.revision;
+    }
+    const tried = new Set;
+    let lastError;
+    for (let attempt = 0;attempt < attempts; attempt += 1) {
+      if (context.signal?.aborted) {
+        throw context.signal.reason ?? new ProviderError("ARANGO_ABORTED", "ArangoDB request was cancelled.");
+      }
+      const now = (config.now ?? Date.now)();
+      const node = nodeForRequest(pool, tried, now);
+      if (!node)
+        break;
+      tried.add(node.url);
+      node.inFlight += 1;
+      try {
+        const cursor = await node.client.query(request.query, request.bindVars);
+        const result = await cursor.all();
+        node.unhealthyUntil = 0;
+        return result;
+      } catch (error) {
+        lastError = error;
+        if (!retryableCoordinatorFailure(error))
+          throw error;
+        const quarantine = Math.min(Math.max(config.unhealthyForMs ?? 15000, 1000), 300000);
+        node.unhealthyUntil = now + quarantine;
+        if (!safe)
+          throw error;
+      } finally {
+        node.inFlight -= 1;
+      }
     }
-    const cursor = await client.query(request.query, request.bindVars);
-    return cursor.all();
+    throw lastError ?? new ProviderError("ARANGO_COORDINATORS_UNAVAILABLE", "No healthy ArangoDB coordinator is available.");
   },
-  classify(error) {
-    const arango = error;
-    if (arango.errorNum === 1210)
-      return "terminal";
-    if (arango.errorNum === 1202)
-      return "terminal";
-    if (arango.errorNum === 1501)
-      return "terminal";
-    if (arango.code === 400 || arango.code === 404 || arango.code === 409)
-      return "terminal";
-    if (arango.code === 401 || arango.code === 403)
-      return "retryable";
-    if (arango.code === 503)
-      return "backoff";
-    return "retryable";
+  classify() {
+    return "terminal";
   }
 });
 function resetPools() {
@@ -224,5 +458,9 @@ var databaseProviders = [arangodb];
 export {
   resetPools,
   databaseProviders,
-  arangodb
+  arangodb,
+  arangoCoordinatorUrls,
+  MAX_ARANGO_COORDINATORS,
+  ARANGO_SERVER_MODE_PATH,
+  ARANGO_COMMUNITY_VERSION
 };

package/dist/email.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/email.ts
 var recipients = (to) => Array.isArray(to) ? [...to] : [to];

package/dist/http.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/index.d.ts

@@ -156,4 +156,4 @@ export interface EmailMessage {
     from?: string;
     replyTo?: string;
 }
-export declare const VERSION = "0.1.4";
+export declare const VERSION = "0.1.6";

package/dist/index.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 export {
   staticConfig,
   nextHealth,

package/dist/pool.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/storage.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/storage.ts
 var encoder = new TextEncoder;

package/dist/translation.js

@@ -144,7 +144,7 @@ function createRegistry(options) {
   }
   return { call };
 }
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
 
 // src/translation.ts
 var GOOGLE_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/providers",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "publishConfig": {
     "access": "public",