@forgezero/providers 0.1.9 → 0.1.11

package/dist/http.js

@@ -38,25 +38,71 @@ function chainCredentials(...sources) {
     }
   };
 }
-function staticConfig(services) {
+function scopeCredentials(source, reference) {
+  return {
+    name: `${source.name}:${reference}`,
+    get: (field) => source.get(reference, field)
+  };
+}
+function chainScopedCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No scoped source held field "${field}".`);
+    }
+  };
+}
+function staticConfig(config) {
+  const providers = new Map(config.providers.map((provider) => [provider.instanceKey, provider]));
+  if (providers.size !== config.providers.length) {
+    throw new ProviderError("CONFIG_DUPLICATE_INSTANCE", "Provider instance keys must be unique.");
+  }
   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 provider(instanceKey) {
+      const provider = providers.get(instanceKey);
+      return provider ? { ...provider, config: { ...provider.config } } : undefined;
+    },
+    async list(serviceKey, methodKey) {
+      return (config.services[serviceKey]?.[methodKey] ?? []).map((attachment) => ({
+        ...attachment,
+        health: health.get(`${serviceKey}:${methodKey}:${attachment.instanceKey}:${attachment.providerMethod}`) ?? attachment.health
       }));
     },
-    async recordHealth(serviceKey, providerId, next) {
-      health.set(`${serviceKey}:${providerId}`, next);
+    async recordHealth(serviceKey, methodKey, instanceKey, providerMethod, next) {
+      health.set(`${serviceKey}:${methodKey}:${instanceKey}:${providerMethod}`, next);
     }
   };
 }
+function defineProviderMethod(method) {
+  return method;
+}
 function defineProvider(spec) {
   return spec;
 }
+function defineSingleMethodProvider(spec) {
+  const { method, invoke, classify, ...identity } = spec;
+  return defineProvider({
+    ...identity,
+    methods: { [method]: defineProviderMethod({ invoke, classify }) }
+  });
+}
 var STRIKES_TO_OFFLINE = 3;
+function serviceMethod() {
+  return Object.freeze({});
+}
+function defineService(definition) {
+  return definition;
+}
 function nextHealth(current, kind) {
   if (kind === "success")
     return { strikes: 0, status: "ok" };
@@ -71,80 +117,188 @@ function nextHealth(current, kind) {
 }
 function createRegistry(options) {
   const byId = new Map(options.providers.map((provider) => [provider.id, provider]));
-  async function call(serviceKey, args, callOptions = {}) {
-    const configured = [...await options.config.list(serviceKey)].filter((provider) => provider.enabled).sort((a, b) => a.priority - b.priority);
+  async function call(serviceKey, methodKey, args, callOptions = {}) {
+    const configured = [...await options.config.list(serviceKey, methodKey)].filter((attachment) => attachment.enabled).sort((a, b) => a.priority - b.priority);
     const attempts = [];
-    for (const entry of configured) {
+    for (const attachment of configured) {
       if (callOptions.signal?.aborted) {
         const cancelled = {
           ok: false,
+          fallbackUsed: attempts.length > 0,
           attempts,
-          error: new ProviderError("CALL_ABORTED", `The "${serviceKey}" call was cancelled.`)
+          error: new ProviderError("CALL_ABORTED", `The "${serviceKey}.${methodKey}" call was cancelled.`)
         };
-        options.after?.(cancelled);
+        await options.after?.(cancelled);
         return cancelled;
       }
-      const spec = byId.get(entry.providerId);
-      if (!spec) {
-        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "not registered" });
+      const instance = await options.config.provider(attachment.instanceKey);
+      if (!instance) {
+        attempts.push({ providerId: "unknown", instanceKey: attachment.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance not registered" });
         continue;
       }
-      if (entry.health?.status === "offline") {
-        attempts.push({ providerId: entry.providerId, outcome: "skipped", error: "offline" });
+      const spec = byId.get(instance.providerId);
+      const method = spec?.methods[attachment.providerMethod];
+      if (!spec || !method) {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: !spec ? "provider not registered" : "method not supported" });
         continue;
       }
-      options.before?.({ service: serviceKey, provider: entry.providerId });
+      if (!instance.enabled) {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance disabled" });
+        continue;
+      }
+      if (attachment.health?.status === "offline") {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "offline" });
+        continue;
+      }
+      await options.before?.({ service: serviceKey, method: methodKey, provider: instance.providerId, instance: instance.instanceKey });
+      const startedAt = performance.now();
       try {
-        const result = await spec.invoke({
-          config: entry.config,
-          secret: (field) => options.credentials.get(entry.secretRef, field),
+        const result = await method.invoke({
+          config: instance.config,
+          secret: (field) => options.credentials.get(instance.secretRef, field),
           signal: callOptions.signal
         }, 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);
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "sent", durationMs: performance.now() - startedAt });
+        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, nextHealth(attachment.health, "success"));
+        const sent = {
+          ok: true,
+          result,
+          provider: instance.providerId,
+          instance: instance.instanceKey,
+          method: attachment.providerMethod,
+          selected: { providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod },
+          fallbackUsed: attempts.length > 1,
+          attempts
+        };
+        await options.after?.(sent);
         return sent;
       } catch (error) {
         if (callOptions.signal?.aborted) {
           const cancelled = {
             ok: false,
+            fallbackUsed: attempts.length > 0,
             attempts,
-            error: new ProviderError("CALL_ABORTED", `The "${serviceKey}" call was cancelled.`)
+            error: new ProviderError("CALL_ABORTED", `The "${serviceKey}.${methodKey}" call was cancelled.`)
           };
-          options.after?.(cancelled);
+          await options.after?.(cancelled);
           return cancelled;
         }
-        const kind = spec.classify(error);
+        const kind = method.classify(error);
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof ProviderError ? error.code : typeof error?.code === "string" ? error.code : undefined;
         attempts.push({
-          providerId: entry.providerId,
+          providerId: instance.providerId,
+          instanceKey: instance.instanceKey,
+          providerMethod: attachment.providerMethod,
           outcome: "failed",
           kind,
-          error: error instanceof Error ? error.message : String(error)
+          durationMs: performance.now() - startedAt,
+          failure: { kind, ...code ? { code } : {}, message },
+          error: message
         });
-        await options.config.recordHealth(serviceKey, entry.providerId, nextHealth(entry.health, kind));
+        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, nextHealth(attachment.health, kind));
         if (kind === "terminal") {
           const refused = {
             ok: false,
+            fallbackUsed: attempts.length > 1,
             attempts,
             error: new ProviderError("PAYLOAD_REJECTED", "The request was refused as malformed; no provider will accept it.")
           };
-          options.after?.(refused);
+          await options.after?.(refused);
           return refused;
         }
       }
     }
     const failed = {
       ok: false,
+      fallbackUsed: attempts.length > 1,
       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.`)
+      error: new ProviderError(attempts.length === 0 ? "NO_PROVIDER" : "ALL_PROVIDERS_FAILED", attempts.length === 0 ? `No provider method is configured for "${serviceKey}.${methodKey}".` : `Every provider method for "${serviceKey}.${methodKey}" failed or was skipped.`)
     };
-    options.after?.(failed);
+    await options.after?.(failed);
     return failed;
   }
-  return { call };
+  function service(definition) {
+    return {
+      call(method, args, callOptions) {
+        return call(definition.key, method, args, callOptions);
+      }
+    };
+  }
+  return { call, service };
+}
+function createService(definition, methods, options = {}) {
+  const providers = new Map;
+  const credentials = new Map;
+  const instances = [];
+  const serviceMethods = {};
+  for (const methodKey of Object.keys(definition.methods)) {
+    const attachments = methods[methodKey];
+    if (!Array.isArray(attachments)) {
+      throw new ProviderError("CONFIG_METHOD_MISSING", `Service method "${definition.key}.${methodKey}" needs an attachment array.`);
+    }
+    const priorities = new Set;
+    serviceMethods[methodKey] = attachments.map((attachment, index) => {
+      if (!Number.isInteger(attachment.priority) || attachment.priority < 1 || attachment.priority > 1000) {
+        throw new ProviderError("CONFIG_PRIORITY", `Priority for "${definition.key}.${methodKey}" must be an integer from 1 to 1000.`);
+      }
+      if (priorities.has(attachment.priority)) {
+        throw new ProviderError("CONFIG_PRIORITY_DUPLICATE", `Priorities for "${definition.key}.${methodKey}" must be unique.`);
+      }
+      priorities.add(attachment.priority);
+      if (!attachment.provider.methods[attachment.method]) {
+        throw new ProviderError("CONFIG_METHOD_UNSUPPORTED", `Provider "${attachment.provider.id}" does not support "${attachment.method}".`);
+      }
+      const existing = providers.get(attachment.provider.id);
+      if (existing && existing !== attachment.provider) {
+        throw new ProviderError("CONFIG_PROVIDER_DUPLICATE", `Provider id "${attachment.provider.id}" has more than one definition.`);
+      }
+      providers.set(attachment.provider.id, attachment.provider);
+      const internalKey = `${definition.key}:${methodKey}:${index}`;
+      credentials.set(internalKey, attachment.credentials);
+      instances.push({
+        instanceKey: internalKey,
+        providerId: attachment.provider.id,
+        enabled: attachment.enabled ?? true,
+        config: { ...attachment.config ?? {} },
+        secretRef: internalKey
+      });
+      return {
+        instanceKey: internalKey,
+        providerMethod: attachment.method,
+        priority: attachment.priority,
+        enabled: attachment.enabled ?? true
+      };
+    });
+  }
+  const registry = createRegistry({
+    providers: [...providers.values()],
+    config: staticConfig({ providers: instances, services: { [definition.key]: serviceMethods } }),
+    credentials: {
+      name: [...new Set([...credentials.values()].map((source) => source.name))].join("+"),
+      async get(reference, field) {
+        const source = credentials.get(reference);
+        if (!source)
+          throw new ProviderError("CREDENTIAL_SOURCE_MISSING", "The provider credential source is unavailable.");
+        return source.get(field);
+      }
+    },
+    ...options
+  });
+  const dynamic = registry.service(definition);
+  return {
+    async call(method, args, callOptions) {
+      const result = await dynamic.call(method, args, callOptions);
+      const { instance: _instance, selected, attempts, ...rest } = result;
+      return {
+        ...rest,
+        ...selected ? { selected: { providerId: selected.providerId, providerMethod: selected.providerMethod } } : {},
+        attempts: attempts.map(({ instanceKey: _instanceKey, ...attempt }) => attempt)
+      };
+    }
+  };
 }
-var VERSION = "0.1.9";
+var VERSION = "0.1.11";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {
@@ -227,9 +381,9 @@ function createHttpClient(config) {
     budget: () => budgetState(config.budget.host)
   };
 }
-var http = defineProvider({
+var http = defineSingleMethodProvider({
   id: "http",
-  service: "http",
+  method: "request",
   label: "HTTP",
   multiInstance: true,
   credentials: {

package/dist/index.d.ts

@@ -39,6 +39,11 @@ export interface CredentialSource {
     readonly name: string;
     get(reference: string, field: string): Promise<string>;
 }
+/** Credentials already scoped to one provider identity. */
+export interface ScopedCredentialSource {
+    readonly name: string;
+    get(field: string): Promise<string>;
+}
 /** Environment variables. `smtp` + `password` → `SMTP_PASSWORD`. */
 export declare function envCredentials(env: Record<string, string | undefined>): CredentialSource;
 /**
@@ -50,30 +55,48 @@ export declare function envCredentials(env: Record<string, string | undefined>):
  * a test that locks the vault and asserts mail still sends.
  */
 export declare function chainCredentials(...sources: readonly CredentialSource[]): CredentialSource;
+/** Bind a reference once so a provider receives only its own credential fields. */
+export declare function scopeCredentials(source: CredentialSource, reference: string): ScopedCredentialSource;
+/** Try provider-scoped sources in order, for example Vault then systemd. */
+export declare function chainScopedCredentials(...sources: readonly ScopedCredentialSource[]): ScopedCredentialSource;
 export interface ProviderHealth {
     strikes: number;
     status: 'ok' | 'degraded' | 'offline';
     lastFailureAtTs?: number;
 }
-export interface ProviderConfig {
+/** One configured provider identity. It is independent of every service. */
+export interface ProviderInstanceConfig {
+    /** Stable key used by service-method attachments. */
+    instanceKey: string;
     providerId: string;
-    /** Named relay, for providers configurable more than once. */
-    instanceKey?: string;
-    priority: number;
+    /** Disables every method on this instance without deleting its configuration. */
     enabled: boolean;
     config: Record<string, unknown>;
     /** Names a vault entry. NEVER the secret itself — a dump yields metadata. */
     secretRef: string;
+}
+/** One service method's attachment to one provider instance method. */
+export interface ServiceMethodAttachment {
+    instanceKey: string;
+    /** Explicit provider capability; it is never inferred from the service name. */
+    providerMethod: string;
+    priority: number;
+    enabled: boolean;
     health?: ProviderHealth;
 }
-/** Where the ordered list lives: a database, a file, constants. */
+/** Provider identities and service routing policy may live in any store. */
 export interface ConfigSource {
     readonly name: string;
-    list(serviceKey: string): Promise<readonly ProviderConfig[]>;
+    provider(instanceKey: string): Promise<ProviderInstanceConfig | undefined>;
+    list(serviceKey: string, methodKey: string): Promise<readonly ServiceMethodAttachment[]>;
     /** Persisted, because strikes that reset on restart retry a dead provider forever. */
-    recordHealth(serviceKey: string, providerId: string, health: ProviderHealth): Promise<void>;
+    recordHealth(serviceKey: string, methodKey: string, instanceKey: string, providerMethod: string, health: ProviderHealth): Promise<void>;
 }
-export declare function staticConfig(services: Record<string, readonly ProviderConfig[]>): ConfigSource;
+export interface StaticRegistryConfig {
+    providers: readonly ProviderInstanceConfig[];
+    services: Record<string, Record<string, readonly ServiceMethodAttachment[]>>;
+}
+export declare function staticConfig(config: StaticRegistryConfig): ConfigSource;
 /**
  * How a failure should be treated.
  *
@@ -92,29 +115,58 @@ export interface InvokeContext {
     secret(field: string): Promise<string>;
     signal?: AbortSignal;
 }
-export interface ProviderSpec<Args = never, Result = never> {
+export interface ProviderMethodSpec<Args = never, Result = never> {
+    invoke(context: InvokeContext, args: Args): Promise<Result>;
+    classify(error: unknown): FailureKind;
+}
+export declare function defineProviderMethod<Args, Result>(method: ProviderMethodSpec<Args, Result>): ProviderMethodSpec<Args, Result>;
+export type AnyProviderMethod = ProviderMethodSpec<any, any>;
+export type ProviderMethods = Record<string, AnyProviderMethod>;
+/** A vendor/provider identity with named capabilities, independent of services. */
+export interface ProviderDefinition<Methods extends ProviderMethods = ProviderMethods> {
     id: string;
-    service: string;
     label: string;
     multiInstance?: boolean;
     /** JSON Schema. `writeOnly` fields route to secret storage. */
     credentials?: Record<string, unknown>;
     config?: Record<string, unknown>;
+    methods: Methods;
+}
+export declare function defineProvider<Methods extends ProviderMethods>(spec: ProviderDefinition<Methods>): ProviderDefinition<Methods>;
+/** Convenience for a provider that exposes exactly one named method. */
+export declare function defineSingleMethodProvider<Method extends string, Args, Result>(spec: Omit<ProviderDefinition<Record<Method, ProviderMethodSpec<Args, Result>>>, 'methods'> & {
+    method: Method;
     invoke(context: InvokeContext, args: Args): Promise<Result>;
     classify(error: unknown): FailureKind;
-}
-export declare function defineProvider<Args, Result>(spec: ProviderSpec<Args, Result>): ProviderSpec<Args, Result>;
+}): ProviderDefinition<Record<Method, ProviderMethodSpec<Args, Result>>>;
 export declare const STRIKES_TO_OFFLINE = 3;
 export interface Attempt {
     providerId: string;
+    instanceKey: string;
+    providerMethod: string;
     outcome: 'sent' | 'skipped' | 'failed';
     kind?: FailureKind;
+    durationMs?: number;
+    failure?: {
+        kind: FailureKind;
+        code?: string;
+        message: string;
+    };
+    /** @deprecated Read `failure.message`; retained for 0.1 compatibility. */
     error?: string;
 }
 export interface CallResult<Result> {
     ok: boolean;
     result?: Result;
     provider?: string;
+    instance?: string;
+    method?: string;
+    selected?: {
+        providerId: string;
+        instanceKey: string;
+        providerMethod: string;
+    };
+    fallbackUsed: boolean;
     attempts: readonly Attempt[];
     error?: ProviderError;
 }
@@ -122,6 +174,48 @@ export interface CallOptions {
     /** Reaches provider fetch/socket code; cancellation never falls through to another vendor. */
     signal?: AbortSignal;
 }
+/** Type-only input/output contract for one service method. */
+export interface ServiceMethodContract<Args, Result> {
+    readonly __args?: (args: Args) => void;
+    readonly __result?: Result;
+}
+export declare function serviceMethod<Args, Result>(): ServiceMethodContract<Args, Result>;
+export type ServiceMethods = Record<string, ServiceMethodContract<any, any>>;
+export interface ServiceDefinition<Key extends string, Methods extends ServiceMethods> {
+    key: Key;
+    methods: Methods;
+}
+export declare function defineService<Key extends string, Methods extends ServiceMethods>(definition: ServiceDefinition<Key, Methods>): ServiceDefinition<Key, Methods>;
+type ServiceArgs<T> = T extends ServiceMethodContract<infer Args, unknown> ? Args : never;
+type ServiceResult<T> = T extends ServiceMethodContract<unknown, infer Result> ? Result : never;
+/**
+ * One direct service attachment. This is the normal application API: pass the
+ * provider itself, its capability, scoped credentials, config and priority.
+ * Stable instance keys exist only inside the dynamic control-plane adapter.
+ */
+export interface DirectServiceAttachment {
+    provider: ProviderDefinition;
+    method: string;
+    credentials: ScopedCredentialSource;
+    config?: Record<string, unknown>;
+    priority: number;
+    enabled?: boolean;
+}
+export type DirectServiceConfig<Methods extends ServiceMethods> = {
+    [Method in keyof Methods]: readonly DirectServiceAttachment[];
+};
+export interface DirectServiceOptions {
+    before?: RegistryOptions['before'];
+    after?: RegistryOptions['after'];
+}
+export type DirectAttempt = Omit<Attempt, 'instanceKey'>;
+export type DirectCallResult<Result> = Omit<CallResult<Result>, 'instance' | 'selected' | 'attempts'> & {
+    selected?: {
+        providerId: string;
+        providerMethod: string;
+    };
+    attempts: readonly DirectAttempt[];
+};
 export interface RegistryOptions {
     credentials: CredentialSource;
     config: ConfigSource;
@@ -136,16 +230,31 @@ export interface RegistryOptions {
      * 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>[];
+    providers: readonly ProviderDefinition[];
     before?: (context: {
         service: string;
+        method: string;
         provider: string;
-    }) => void;
-    after?: (result: CallResult<unknown>) => void;
+        instance: string;
+    }) => void | Promise<void>;
+    after?: (result: CallResult<unknown>) => void | Promise<void>;
 }
 export declare function nextHealth(current: ProviderHealth | undefined, kind: FailureKind | 'success'): ProviderHealth;
 export declare function createRegistry(options: RegistryOptions): {
-    call: <Result>(serviceKey: string, args: unknown, callOptions?: CallOptions) => Promise<CallResult<Result>>;
+    call: <Result>(serviceKey: string, methodKey: string, args: unknown, callOptions?: CallOptions) => Promise<CallResult<Result>>;
+    service: <Key extends string, Methods extends ServiceMethods>(definition: ServiceDefinition<Key, Methods>) => {
+        call<Method extends Extract<keyof Methods, string>>(method: Method, args: ServiceArgs<Methods[Method]>, callOptions?: CallOptions): Promise<CallResult<ServiceResult<Methods[Method]>>>;
+    };
+};
+/**
+ * Create a typed service directly from ordered provider attachments.
+ *
+ * This deliberately hides provider-instance keys and the ConfigSource
+ * ceremony. Applications normally know their providers in code; ForgeZero's
+ * dynamic admin control plane can continue to use createRegistry separately.
+ */
+export declare function createService<Key extends string, Methods extends ServiceMethods>(definition: ServiceDefinition<Key, Methods>, methods: DirectServiceConfig<Methods>, options?: DirectServiceOptions): {
+    call<Method extends Extract<keyof Methods, string>>(method: Method, args: ServiceArgs<Methods[Method]>, callOptions?: CallOptions): Promise<DirectCallResult<ServiceResult<Methods[Method]>>>;
 };
 /** Passed to `registry.call('email', message)`. */
 export interface EmailMessage {
@@ -176,4 +285,5 @@ export interface EmailBatchResult {
     };
     results: readonly EmailBatchItemResult[];
 }
-export declare const VERSION = "0.1.9";
+export declare const VERSION = "0.1.11";
+export {};