commflow
  • English

      • Configuration

      Planned APIs: This page documents client, target, per-call, and adapter configuration after runtime release. commflow@0.0.2 has no runtime configuration surface; see Current Release Quick Start for runnable exports.

      How To Use This Page

      Choose default timeout, retry/reconnect, and service addressing before creating a client, then use per-call options only for exceptions. Keep context, metadata, and hooks centralized so business code does not rebuild them for every call.

      Configuration Layers

      LayerPurposeExamples
      client defaultsDefault behavior for all calls or connections under one clientbaseURL, timeout, retry, reconnect
      target configurationNamed entries for multiple backend servicestargets: [{ name, baseURL }]
      per-call optionsOverrides one call onlyrequest.get('/path', { timeout: 1000 })
      adapter configurationFramework integration settings outside the core packageVextJS propagateRequestId

      Recommendation: put stable values at the client or target layer, and put temporary differences in per-call options.

      Core Options

      OptionApplies toTarget meaningSelection guidance
      baseURLrequest / SSEDefault service URLUse when one client talks to one service.
      headersrequest / RPCDefault request headersStore shared headers, not fields that change every call.
      timeoutrequest / RPCMaximum wait for one callStart around 3000-10000ms, then tune by service SLA.
      retryrequest / RPCExtra attempts after retryable failurev1 uses a number; enable for idempotent calls and be careful with non-idempotent writes.
      retryDelayrequest / RPCDelay before retryUse milliseconds or (attempt) => ms.
      reconnectSSE / socketReconnect policy after connection lossNot the same as request retry; it must handle close and resubscribe.
      targetsrequest / RPCNamed backend servicesUse when one client reaches multiple internal services.
      resolverRPCResolve procedure/service to endpointCentralizes service discovery, static addresses, or load balancing.
      contextProviderrequest / adapterInject requestId, tenant, or trace metadataUse host framework context instead of rebuilding metadata in business code.
      metadataRPC / SSE / socketPropagate call or connection contextUse for requestId, trace, and tenant, not business body data.
      hooksrequest / RPCObserve or lightly adjust lifecycleGood for logs, traces, and header injection, not business branching.
      heartbeatIntervalsocketLong-lived connection heartbeat intervalMatch the server heartbeat requirements.

      Target Configuration

      Use targets for multiple backend services instead of hardcoding several base URLs in application code.

      const request = createCommflowRequestClient({
  targets: [
    {
      name: 'user',
      baseURL: 'https://user.internal',
      timeout: 3000
    },
    {
      name: 'billing',
      baseURL: 'https://billing.internal',
      timeout: 8000,
      retry: 2
    }
  ]
});

await request.target('user').get('/profiles/42');
await request.target('billing').get('/invoices/latest');

      Override order:

      SourcePriority
      per-call optionsHighest, affects one call only
      target configurationMiddle, affects that target
      client defaultsLowest, fallback behavior

      Hook Configuration

      Hooks should observe the communication lifecycle, not hide business logic in the transport layer.

      const request = createCommflowRequestClient({
  hooks: {
    beforeRequest(event) {
      event.headers.set('x-request-source', 'commflow');
    },
    afterResponse(event) {
      console.log(event.request.method, event.response.status, event.durationMs);
    },
    onRetry(event) {
      console.warn('retrying request', event.attempt, event.reason);
    },
    onError(event) {
      console.error('request failed', event.error);
    }
  }
});

      Hook boundaries:

      HookCan mutate requestFailure impact
      beforeRequestCan mutate headersThrowing blocks dispatch.
      afterResponseDoes not mutate responseRecords secondary hook failure; does not turn success into failure.
      onRetryDoes not change retry decisionRecords secondary hook failure; does not cancel the retry.
      onErrorDoes not replace original errorRecords secondary hook failure.

      VextJS Boundary

      VextJS is the first target consumer, but the core package should not be tied to VextJS. Framework-specific options belong in the adapter layer.

      OptionLayerNotes
      timeout / retry / retryDelaycommflow coreShared by request / RPC where possible.
      requestIdHeadercommflow core or adapter sharedThe adapter may provide a default.
      propagateRequestIdVextJS adapterControls whether the Vext request context propagates requestId.
      proxy / fetch hook compatibilityVextJS adapterKeeps behavior stable while replacing app.fetch.

      Current Release Note

      commflow@0.0.2 has no runtime configuration surface. You do not need environment variables, proxy settings, retry policies, or VextJS integration options to use the current package.

      If you only want to verify the released package, read Current Release Quick Start. To understand how configuration affects recovery, continue to Errors And Retries.