@forgezero/providers 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @forgezero/providers — service registry with priority, health and fallback.
+ *
+ * Zero runtime dependencies. It declares two interfaces and someone injects
+ * them; it never imports `@forgezero/vault`. That constraint is what makes it
+ * usable without ForgeZero at all — if it reached for the vault directly it
+ * would be a ForgeZero package with a public name.
+ *
+ *   priority   providers are tried in the order the DATABASE says, not the code
+ *   health     three strikes marks a provider offline; any success clears them
+ *   fallback   the next provider is tried, unless the error says not to
+ *
+ * That last part is what most registries get wrong. See `FailureKind`.
+ */
+export declare class ProviderError extends Error {
+    readonly code: string;
+    /**
+     * Structured detail for `classify`, optional and additive.
+     *
+     * Without it a provider has to decide `terminal` vs `backoff` by matching
+     * substrings of its own error message, which breaks the first time a
+     * vendor rewords one. An HTTP status or a JSON-RPC code is the fact the
+     * decision actually rests on, so it travels with the error.
+     */
+    readonly details?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: string, message: string, 
+    /**
+     * Structured detail for `classify`, optional and additive.
+     *
+     * Without it a provider has to decide `terminal` vs `backoff` by matching
+     * substrings of its own error message, which breaks the first time a
+     * vendor rewords one. An HTTP status or a JSON-RPC code is the fact the
+     * decision actually rests on, so it travels with the error.
+     */
+    details?: Readonly<Record<string, unknown>> | undefined);
+}
+/** Where credentials come from. The interface IS the contract. */
+export interface CredentialSource {
+    readonly name: string;
+    get(reference: string, field: string): Promise<string>;
+}
+/** Environment variables. `smtp` + `password` → `SMTP_PASSWORD`. */
+export declare function envCredentials(env: Record<string, string | undefined>): CredentialSource;
+/**
+ * Try each source in order, swallowing failures until one answers.
+ *
+ * This is what makes bootstrap work. A locked vault THROWS, and if that
+ * propagated it would take down the environment fallback that exists to recover
+ * it. The swallow is load-bearing, not defensive coding — and it is why there is
+ * a test that locks the vault and asserts mail still sends.
+ */
+export declare function chainCredentials(...sources: readonly CredentialSource[]): CredentialSource;
+export interface ProviderHealth {
+    strikes: number;
+    status: 'ok' | 'degraded' | 'offline';
+    lastFailureAtTs?: number;
+}
+export interface ProviderConfig {
+    providerId: string;
+    /** Named relay, for providers configurable more than once. */
+    instanceKey?: string;
+    priority: number;
+    enabled: boolean;
+    config: Record<string, unknown>;
+    /** Names a vault entry. NEVER the secret itself — a dump yields metadata. */
+    secretRef: string;
+    health?: ProviderHealth;
+}
+/** Where the ordered list lives: a database, a file, constants. */
+export interface ConfigSource {
+    readonly name: string;
+    list(serviceKey: string): Promise<readonly ProviderConfig[]>;
+    /** Persisted, because strikes that reset on restart retry a dead provider forever. */
+    recordHealth(serviceKey: string, providerId: string, health: ProviderHealth): Promise<void>;
+}
+export declare function staticConfig(services: Record<string, readonly ProviderConfig[]>): ConfigSource;
+/**
+ * How a failure should be treated.
+ *
+ *   terminal   OUR payload is malformed. Every provider will reject it, so
+ *              trying the next buries the real error under identical ones.
+ *   retryable  THIS provider or key is bad. The next may be fine.
+ *   backoff    rate limited. Skip without a strike — it is working, we are
+ *              asking too fast, and taking it offline punishes it for that.
+ *
+ * Collapsing these into "it failed" gives a system that either gives up too
+ * early or hammers every provider with a request none can accept.
+ */
+export type FailureKind = 'terminal' | 'retryable' | 'backoff';
+export interface InvokeContext {
+    config: Record<string, unknown>;
+    secret(field: string): Promise<string>;
+    signal?: AbortSignal;
+}
+export interface ProviderSpec<Args = never, Result = never> {
+    id: string;
+    service: string;
+    label: string;
+    multiInstance?: boolean;
+    /** JSON Schema. `writeOnly` fields route to secret storage. */
+    credentials?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    invoke(context: InvokeContext, args: Args): Promise<Result>;
+    classify(error: unknown): FailureKind;
+}
+export declare function defineProvider<Args, Result>(spec: ProviderSpec<Args, Result>): ProviderSpec<Args, Result>;
+export declare const STRIKES_TO_OFFLINE = 3;
+export interface Attempt {
+    providerId: string;
+    outcome: 'sent' | 'skipped' | 'failed';
+    kind?: FailureKind;
+    error?: string;
+}
+export interface CallResult<Result> {
+    ok: boolean;
+    result?: Result;
+    provider?: string;
+    attempts: readonly Attempt[];
+    error?: ProviderError;
+}
+export interface RegistryOptions {
+    credentials: CredentialSource;
+    config: ConfigSource;
+    /**
+     * Deliberately `any` in both parameters.
+     *
+     * A registry is heterogeneous by definition — an email provider and a storage
+     * provider have nothing in common but the interface — so this list cannot be
+     * given one useful pair of type arguments. It was `ProviderSpec<never, never>`,
+     * which is unsatisfiable in the `Result` position: every real provider had to
+     * be cast with `as never` at the call site. The type parameters earn their
+     * keep at the DEFINITION site, where `defineProvider` still checks that
+     * `invoke` matches what the provider claims to take and return.
+     */
+    providers: readonly ProviderSpec<any, any>[];
+    before?: (context: {
+        service: string;
+        provider: string;
+    }) => void;
+    after?: (result: CallResult<unknown>) => void;
+}
+export declare function nextHealth(current: ProviderHealth | undefined, kind: FailureKind | 'success'): ProviderHealth;
+export declare function createRegistry(options: RegistryOptions): {
+    call: <Result>(serviceKey: string, args: unknown) => Promise<CallResult<Result>>;
+};
+/** Passed to `registry.call('email', message)`. */
+export interface EmailMessage {
+    to: string | readonly string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    from?: string;
+    replyTo?: string;
+}
+export declare const VERSION = "0.1.0";

package/dist/index.js

@@ -0,0 +1,139 @@
+// src/index.ts
+class ProviderError extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "ProviderError";
+  }
+}
+function envCredentials(env) {
+  return {
+    name: "env",
+    async get(reference, field) {
+      const key = `${reference}_${field}`.replace(/[.-]/g, "_").toUpperCase();
+      const value = env[key];
+      if (value === undefined) {
+        throw new ProviderError("CREDENTIAL_MISSING", `Set ${key} in the environment.`);
+      }
+      return value;
+    }
+  };
+}
+function chainCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(reference, field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(reference, field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No source held ${reference}.${field}.`);
+    }
+  };
+}
+function staticConfig(services) {
+  const health = new Map;
+  return {
+    name: "static",
+    async list(serviceKey) {
+      return (services[serviceKey] ?? []).map((provider) => ({
+        ...provider,
+        health: health.get(`${serviceKey}:${provider.providerId}`) ?? provider.health
+      }));
+    },
+    async recordHealth(serviceKey, providerId, next) {
+      health.set(`${serviceKey}:${providerId}`, next);
+    }
+  };
+}
+function defineProvider(spec) {
+  return spec;
+}
+var STRIKES_TO_OFFLINE = 3;
+function nextHealth(current, kind) {
+  if (kind === "success")
+    return { strikes: 0, status: "ok" };
+  if (kind === "backoff")
+    return current ?? { strikes: 0, status: "ok" };
+  const strikes = (current?.strikes ?? 0) + 1;
+  return {
+    strikes,
+    status: strikes >= STRIKES_TO_OFFLINE ? "offline" : "degraded",
+    lastFailureAtTs: Date.now()
+  };
+}
+function createRegistry(options) {
+  const byId = new Map(options.providers.map((provider) => [provider.id, provider]));
+  async function call(serviceKey, args) {
+    const configured = [...await options.config.list(serviceKey)].filter((provider) => provider.enabled).sort((a, b) => a.priority - b.priority);
+    const attempts = [];
+    for (const entry of configured) {
+      const spec = byId.get(entry.providerId);
+      if (!spec) {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "not registered" });
+        continue;
+      }
+      if (entry.health?.status === "offline") {
+        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "offline" });
+        continue;
+      }
+      options.before?.({ service: serviceKey, provider: entry.providerId });
+      try {
+        const result = await spec.invoke({
+          config: entry.config,
+          secret: (field) => options.credentials.get(entry.secretRef, field)
+        }, args);
+        attempts.push({ providerId: entry.providerId, outcome: "sent" });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, "success"));
+        const sent = { ok: true, result, provider: entry.providerId, attempts };
+        options.after?.(sent);
+        return sent;
+      } catch (error) {
+        const kind = spec.classify(error);
+        attempts.push({
+          providerId: entry.providerId,
+          outcome: "failed",
+          kind,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, kind));
+        if (kind === "terminal") {
+          const refused = {
+            ok: false,
+            attempts,
+            error: new ProviderError("PAYLOAD_REJECTED", "The request was refused as malformed; no provider will accept it.")
+          };
+          options.after?.(refused);
+          return refused;
+        }
+      }
+    }
+    const failed = {
+      ok: false,
+      attempts,
+      error: new ProviderError(attempts.length === 0 ? "NO_PROVIDER" : "ALL_PROVIDERS_FAILED", attempts.length === 0 ? `No provider is configured for "${serviceKey}".` : `Every provider for "${serviceKey}" failed or was skipped.`)
+    };
+    options.after?.(failed);
+    return failed;
+  }
+  return { call };
+}
+var VERSION = "0.1.0";
+export {
+  staticConfig,
+  nextHealth,
+  envCredentials,
+  defineProvider,
+  createRegistry,
+  chainCredentials,
+  VERSION,
+  STRIKES_TO_OFFLINE,
+  ProviderError
+};

package/dist/pool.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Which address an outbound request leaves by, and how many it may carry.
+ *
+ * Venues rate-limit per IP. One address gets a fixed allowance, so placing more
+ * orders than that means more addresses — and choosing between them has to be
+ * accounted centrally or every caller spends the same allowance independently.
+ *
+ * ## This adds no counting
+ *
+ * `@forgezero/providers/http` already reserves before a call and settles from
+ * the response, and its budget is keyed by an arbitrary string rather than a
+ * real hostname. So the per-address cap IS that budget with the address as the
+ * key. What this module adds is the CHOICE of address and the health of each
+ * one, which genuinely did not exist.
+ *
+ * Writing a second counter here would mean two answers to "how much is left",
+ * and they would disagree the first time a response settled differently from
+ * its reservation.
+ *
+ * ## Sticky by key, not round-robin
+ *
+ * Orders for one account should leave by one address where possible. A venue
+ * sees a coherent client rather than an account whose requests arrive from four
+ * places, and — more practically — a per-address weight limit is easier to
+ * reason about when one account's burst lands in one bucket rather than
+ * smeared across all of them.
+ *
+ * Stickiness is a preference, never a guarantee. When the preferred address is
+ * exhausted or unhealthy the request moves, because refusing an order to
+ * preserve affinity is the wrong trade.
+ */
+export declare class PoolExhausted extends Error {
+    readonly addresses: number;
+    readonly retryAfterMs: number;
+    constructor(addresses: number, retryAfterMs: number);
+}
+export declare class PoolEmpty extends Error {
+    constructor();
+}
+export interface PoolAddress {
+    /** The outbound address, or a label for one. Also the budget key. */
+    id: string;
+    /** Local address to bind to, when the host can. Absent means the default route. */
+    bind?: string;
+    enabled: boolean;
+    /** Set when a venue has banned this address. Cleared by hand or by expiry. */
+    blockedUntilMs?: number;
+}
+export interface PoolOptions {
+    addresses: readonly PoolAddress[];
+    /** Requests per address per window. The owner's figure is 50. */
+    perAddress: number;
+    windowMs: number;
+    /** Stop at a fraction of the limit. The venue's window boundary is not ours. */
+    headroom?: number;
+    now?: () => number;
+    /**
+     * Off means every request takes the default route and no accounting happens.
+     *
+     * Correct for a single-node install, and being able to turn it off is what
+     * makes a routing problem debuggable: an operator can remove the routing.
+     */
+    enabled?: boolean;
+}
+export interface Lease {
+    /** The address chosen, or null when the pool is off. */
+    address: PoolAddress | null;
+    /** Call with the true cost once the response is in. */
+    settle: (actualCost: number) => void;
+}
+/**
+ * A pool over the shared budget.
+ *
+ * Deliberately not a class: the state that matters lives in the budget ledger
+ * in `http.ts`, which is module-level and shared by every client in the
+ * process. A pool holding its own counters would be a per-instance view of a
+ * per-process limit, which is the bug this exists to avoid.
+ */
+export declare function createAddressPool(options: PoolOptions): {
+    /**
+     * Take an address for one request.
+     *
+     * Reserves BEFORE the request, like the underlying budget: counting on the
+     * way back lets a burst of concurrent orders all pass the check and
+     * collectively exceed the limit — which is precisely what happens when a
+     * strategy wakes up.
+     */
+    take(args?: {
+        key?: string;
+        cost?: number;
+    }): Lease;
+    /**
+     * Mark an address banned by the venue.
+     *
+     * A 418 from Binance means this address is banned and hammering makes it
+     * longer, so it leaves the rotation entirely rather than merely running out
+     * of budget — a budget resets on its own and a ban does not.
+     */
+    block(id: string, forMs: number): void;
+    /** What each address has spent. For an admin screen and for a decision to scale. */
+    state(): {
+        id: string;
+        spent: number;
+        limit: number;
+        blocked: boolean;
+        enabled: boolean;
+    }[];
+    /** Total capacity per window, so a screen can say "you can place N". */
+    capacity: () => number;
+    enabled: boolean;
+};
+export type AddressPool = ReturnType<typeof createAddressPool>;