NestJS HTTP Client Architecture

NestJS HTTP Client Architecture

Overview

This skill documents the architecture of the nestjs-resilient-client library. The library wraps @nestjs/axios's HttpService with a cockatiel resilience policy stack. It exposes two clients: RestClient (resilient HTTP client) and AuthRestClient (authenticated HTTP client). Decorator logic uses base-decorators@1.1.0 primitives (Wrap). Testing uses jest@29 + ts-jest, Stryker v8, jest-it-up, and testcontainers.

Key Concepts

• BaseHttpService: Abstract base class. Provides the full verb surface (request, get, post, etc.) via a protected dispatch template method and callUnderlying helper. Subclasses layer cross-cutting concerns by overriding dispatch. Normalises Observable/Promise results in callUnderlying.
• HookableHttpService: Adds HooksConfig parameter to constructor. Overrides dispatch to apply onInvoke (pre-call arg transform), onReturn (post-call response transform), and onError (error observation) hooks.
• HooksConfig: Interface with three optional hooks: onInvoke(verb, args) => InvokeArgs | Promise<InvokeArgs>, onReturn(verb, args, response) => AxiosResponse | Promise<AxiosResponse>, onError(verb, args, error) => void | never.
• RestClient: Thin wrapper around HttpService that runs requests through a cockatiel IPolicy. policy field is public readonly. Extends HookableHttpService (new), overrides dispatch to wrap with policy.execute(policyCtx => ...) and merges policyCtx.signal into the axios config.
• AuthRestClient: Extends HookableHttpService (new). Holds restClient: RestClient (as httpService) and authProcessor: AuthProcessor. Overrides dispatch to run pre-flight auth, extend request config, and recover from a single 401.
• AuthProcessor: Manages authentication lifecycle. Calls authStrategy.authenticate(client) directly (no authResult caching). Uses @DeduplicateInflight on performAuthenticate() for single-flight guarantee.
• AuthStrategy (interface): Full class-based strategy with authenticate(client: RestClient): Promise<void>, isAuthenticated(): boolean, extendRequest(config): AxiosRequestConfig, invalidate(): void.
• AuthRestModule: Dynamic NestJS module. Accepts { httpService, resilience?, axios?, hooks? }.
• @DeduplicateInflight: Method decorator using Wrap from base-decorators. Coalesces concurrent calls with the same key into a single promise. The decorated class must expose inflightMap: Map<string, Promise<unknown>>.
• RestModule: Dynamic NestJS module. registerAsync creates an internal HttpModule from axios config. fromHttpService accepts a pre-resolved HttpService (used by AuthRestModule).
• RxJS resilience operators: New optional fields in ResilanceConfig — deduplication, rateLimit, timeLimiter, throttle — implemented as RxJS operators applied to the Observable in callUnderlying.
• Timeout conflict resolution: If axios.timeout is set in module options, resilience.timeout must be stripped before constructing RestClient to avoid competing timeouts.

Documentation & References

Recommended Libraries & Tools

Installed Stack

jest@29 + ts-jest with inline tsconfig overrides (module: commonjs, moduleResolution: node) in both jest.config.ts (unit) and jest.e2e.config.ts (e2e). jest-it-up runs as posttest:unit. Stryker v8 + jest runner with 80% break threshold. testcontainers with kennethreitz/httpbin image for e2e.

IMPORTANT: The project uses tsdown with moduleResolution: "bundler" in tsconfig.json. Jest requires CommonJS + moduleResolution: "node". Use inline tsconfig overrides in the ts-jest transform block — do NOT modify root tsconfig.json for jest compatibility.

Patterns & Best Practices

Pattern 1: HookableHttpService + dispatch override

When to use: Layering cross-cutting concerns over the HTTP verb surface. Both RestClient and AuthRestClient use this pattern.

Core mechanics: HookableHttpService maps every verb call to an InvokeArgs carrier { config, url?, data? } and routes it through protected dispatch(verb, args). Subclasses override dispatch to add "around" behavior. callUnderlying(verb, args) invokes the actual transport and normalizes Observable/Promise results.

// RestClient: wraps every request in policy.execute
protected override async dispatch<T>(verb, initialArgs): Promise<AxiosResponse<T>> {
  return await this.policy.execute(async (policyCtx) => {
    const argsWithSignal = { ...initialArgs, config: mergeSignal(initialArgs.config, policyCtx.signal) }
    return await super.dispatch<T>(verb, argsWithSignal)
  }) as AxiosResponse<T>
}

// AuthRestClient: pre-flight auth + 401 re-auth
protected override async dispatch<T>(verb, initialArgs): Promise<AxiosResponse<T>> {
  await this.authStrategy.authenticateIfNeeded()
  const authedArgs = { ...initialArgs, config: this.authStrategy.extendRequest(initialArgs.config) }
  try {
    return await super.dispatch<T>(verb, authedArgs)  // delegates to inner RestClient
  } catch (error) {
    if (isAxiosError(error) && error.response?.status === 401) {
      this.authStrategy.clearAuth()
      await this.authStrategy.authenticateIfNeeded()
      const retryArgs = { ...initialArgs, config: this.authStrategy.extendRequest(initialArgs.config) }
      return await this.callUnderlying<T>(verb, retryArgs)  // bypasses pre-flight on retry
    }
    throw error
  }
}

Key: super.dispatch runs all parent dispatch logic (the resilience pipeline in RestClient). this.callUnderlying bypasses all dispatch overrides and goes straight to the transport. Use callUnderlying on the 401 retry path to avoid double pre-flight auth.

Pattern 2: AuthStrategyService / AuthProcessor with @DeduplicateInflight

Current implementation (auth-strategy.service.ts):

• Holds AuthConfig factory + client: unknown. Caches authResult: AuthStrategy | null.
• performAuthenticate() calls authConfig.authenticate(client) and stores result.
• @DeduplicateInflight(() => 'authenticate') on performAuthenticate — single-flight guarantee.
• Class MUST have readonly inflightMap = new Map<string, Promise<unknown>>().

Post-refactor (AuthProcessor):

• Holds the AuthStrategy class INSTANCE (not a factory). No authResult caching.
• isAuthenticated() → authStrategy.isAuthenticated() directly.
• extendRequest() → authStrategy.extendRequest() directly.
• performAuthenticate() → authStrategy.authenticate(client) directly.
• The AuthStrategy class manages its own internal session state.

// Current AuthStrategyService (before rename)
class AuthStrategyService {
  readonly inflightMap = new Map<string, Promise<unknown>>()
  private authResult: AuthStrategy | null = null

  constructor(private readonly authConfig: AuthConfig, private readonly client: unknown) {}

  isAuthenticated() { return this.authResult?.isAuthenticated() ?? false }
  extendRequest(config) { return this.authResult?.extendRequest(config) ?? config }
  clearAuth() { this.authResult = null }

  @DeduplicateInflight(() => 'authenticate')
  private async performAuthenticate() {
    this.authResult = await this.authConfig.authenticate(this.client as RestClient)
  }
}

Pattern 3: Class-based AuthStrategy DI (pending refactor)

Context: The improve-auth-rest-client task replaces the AuthConfig factory pattern with a class-based DI pattern for AuthStrategy.

New AuthStrategy interface (gains authenticate method):

interface AuthStrategy {
  authenticate(client: RestClient): Promise<void>  // NEW — was in AuthConfig
  isAuthenticated(): boolean
  extendRequest(config: AxiosRequestConfig): AxiosRequestConfig
}

New AuthRestModuleOptions (class reference instead of factory):

interface AuthRestModuleOptions {
  httpService: HttpService
  authStrategy: Type<AuthStrategy>  // Class token, NestJS resolves and instantiates it
  resilience?: ResilanceConfig<unknown>
}

Module wiring change: AuthRestModule.forRootAsync provides the user's AuthStrategy class via useClass so NestJS DI resolves and injects it into AuthProcessor.

clearAuth() design decision: Since AuthProcessor no longer caches authResult, clearAuth() must signal the AuthStrategy instance to invalidate its internal session. The exact mechanism is a design decision — the AuthStrategy class manages its own state, and clearAuth on AuthProcessor triggers re-authentication on the next authenticateIfNeeded() call. One approach: AuthProcessor keeps a boolean _invalidated flag that overrides authStrategy.isAuthenticated() until a fresh authenticate() call completes.

Pattern 4: HookableHttpService

HooksConfig interface:

export interface HooksConfig {
  // Transform verb invocation args before callUnderlying executes.
  // Must return a new InvokeArgs (treat input as immutable).
  onInvoke?: (verb: HttpVerb, args: InvokeArgs) => InvokeArgs | Promise<InvokeArgs>
  // Observe or substitute the response after callUnderlying returns.
  // Must return a new AxiosResponse (treat input as immutable).
  onReturn?: (verb: HttpVerb, args: InvokeArgs, response: AxiosResponse) => AxiosResponse | Promise<AxiosResponse>
  // Receive the error if callUnderlying throws. Can rethrow (to propagate)
  // or remain silent to let the caller handle it.
  onError?: (verb: HttpVerb, args: InvokeArgs, error: unknown) => void | never
}

New HookableHttpService dispatch override:

export class HookableHttpService extends BaseHttpService {
  constructor(httpService: HttpServiceLike, private readonly hooks?: HooksConfig) {
    super(httpService)
  }

  protected override async dispatch<T = unknown>(
    verb: HttpVerb,
    args: InvokeArgs,
  ): Promise<AxiosResponse<T>> {
    const resolvedArgs = this.hooks?.onInvoke
      ? await this.hooks.onInvoke(verb, args)
      : args
    try {
      const response = await super.dispatch<T>(verb, resolvedArgs)
      return this.hooks?.onReturn
        ? await this.hooks.onReturn(verb, resolvedArgs, response)
        : response
    } catch (error) {
      this.hooks?.onError?.(verb, resolvedArgs, error)
      throw error
    }
  }
}

CRITICAL: RestClient and AuthRestClient must pass hooks through to super(httpService, hooks). The RestModule and AuthRestModule must accept hooks?: HooksConfig in options and pass it through to the client constructor.

Pattern 5: RxJS Resilience Operators in ResilanceConfig

Context: Four new RxJS-based operators are added to ResilanceConfig and applied to the HttpService Observable BEFORE firstValueFrom in callUnderlying.

Key insight: @nestjs/axios HttpService returns Observable<AxiosResponse>. The existing callUnderlying uses firstValueFrom(observable). Insert RxJS operator pipeline between the observable and firstValueFrom.

RxJS 7.8.2 is already installed as a transitive dependency of @nestjs/axios. No additional packages needed.

New ResilanceConfig fields:

export interface ResilanceConfig<T, S = void, R = unknown> {
  // ... existing fields ...
  /** Deduplicate concurrent requests to the same endpoint (same verb+url key). */
  deduplication?: DeduplicationConfig
  /** Rate limiting with token-bucket or leaky-bucket algorithm. */
  rateLimit?: RateLimitConfig
  /** Per-request timeout with RxJS timeout operator (cooperative cancellation). */
  timeLimiter?: TimeLimiterConfig
  /** Throttle emissions — allow one request per `duration` ms window. */
  throttle?: ThrottleConfig
}

Operator implementations:

// Deduplication: shareReplay per URL key
// Map<key, Observable> where key = `${verb}:${url ?? config.url}`
// Each key maps to an Observable<AxiosResponse> wrapped in shareReplay({ bufferSize: 1, refCount: true })
// so concurrent callers for the same key share one network call

// Rate Limiter: concatMap + delay for leaky bucket (queue all, emit at fixed rate)
// Token bucket: BehaviorSubject for token count, zip with source
import { throttleTime, timeout as rxjsTimeout, concatMap, of, delay, shareReplay } from 'rxjs'

// Throttle: throttleTime(duration) — emit first, ignore rest for duration ms
observable.pipe(throttleTime(config.throttle.duration))

// Time Limiter: RxJS timeout operator
import { timeout as rxjsTimeout } from 'rxjs'
observable.pipe(rxjsTimeout({ each: config.timeLimiter.duration }))
// TimeoutError is thrown when duration elapses

Implementation location: BaseHttpService.callUnderlying applies the RxJS pipeline when rxjsConfig is provided. OR: a new rxjsPipelineBuilder function (parallel to resiliencePolicyBuilder) composes RxJS operators from config.

CRITICAL: The RxJS pipeline operators are applied to the Observable returned by invokeVerb(httpService, verb, args) BEFORE the branch that checks isObservable(result). For non-Observable (Promise) returns, the RxJS pipeline does NOT apply — this is fine because RestClient wraps HttpService (Observable-based), and the RxJS pipeline is relevant there.

Deduplication key derivation: ${verb}:${url ?? config.url ?? ''} — combines HTTP method and URL into a string key. The InvokeArgs carrier has url (for most verbs) or config.url (for request verb).

Pattern 6: Axios Timeout vs Policy Timeout Conflict Resolution

Problem: If both axios.timeout (in HttpModuleOptions) and resilience.timeout (cockatiel TimeoutPolicy) are set, they compete. The axios timeout fires at the HTTP layer; the cockatiel timeout fires at the policy layer. The axios timeout can cancel a request before the policy timeout, making the policy timeout redundant and potentially causing confusing behavior.

Solution: In both RestModule.forRootAsync and AuthRestModule.forRootAsync, when constructing RestClient, strip timeout from the resilience config if opts.axios?.timeout is set.

function resolveResilience(opts: RestModuleOptions): ResilanceConfig<unknown> | undefined {
  if (opts.axios?.timeout && opts.resilience?.timeout !== undefined) {
    const { timeout: _dropped, ...rest } = opts.resilience ?? {}
    return rest
  }
  return opts.resilience
}
// Usage in RestClient provider factory:
new RestClient(httpService, resolveResilience(opts))

README guidance: Document both timeout mechanisms, when to use each, and the auto-stripping behavior. Example:

// axios.timeout overrides policy timeout — no policy timeout will be set
RestModule.forRootAsync({
  useFactory: () => ({
    axios: { baseURL: 'https://api.example.com', timeout: 5_000 },
    resilience: ResiliencePresets.CONSERVATIVE, // timeout:60s stripped automatically
  }),
})

Pattern 7: Zero-Config RestModule (class-level module import)

Context: Users should be able to import RestModule directly (without forRootAsync) for zero-configuration use.

NestJS pattern: The @Module({}) decorator on the RestModule class itself serves as the default no-config registration. When imports: [RestModule] is used (without calling forRootAsync), NestJS uses the class-level module metadata.

Implementation: Update RestModule class-level @Module decorator:

@Module({
  imports: [HttpModule],
  providers: [
    {
      provide: RestClient,
      useFactory: (http: HttpService) => new RestClient(http),
      inject: [HttpService],
    },
  ],
  exports: [RestClient],
})
export class RestModule { ... }

Constraint: HttpModule imported at class level uses axios defaults (no baseURL). This is intentional for zero-config usage — the consumer sets baseURL per-request or via a different mechanism.

E2e test required: Verify imports: [RestModule] works and RestClient is injectable. Test must make a real HTTP call to prove the client works without any configuration.

Pattern 8: AuthRestModuleOptions extending RestModuleOptions

Context: AuthRestModuleOptions must extend RestModuleOptions to support axios, hooks, and resilience fields in addition to the required httpService.

New interface:

// RestModuleOptions (unchanged):
interface RestModuleOptions {
  axios?: HttpModuleOptions
  resilience?: ResilanceConfig<unknown>
  hooks?: HooksConfig
}

// AuthRestModuleOptions extends RestModuleOptions:
interface AuthRestModuleOptions extends RestModuleOptions {
  httpService: HttpService
}

CRITICAL: When axios is provided to AuthRestModuleOptions, AuthRestModule.forRootAsync must configure the internal HttpModule with it. Currently AuthRestModule imports HttpModule (no config). After the change, it must import HttpModule.registerAsync(...) if opts.axios is non-empty.

Impact on AuthRestModule.forRootAsync: The RestModule.forHttpService call must forward opts.axios to configure the RestClient's HttpService. Currently RestModule.forHttpService only accepts { httpService, resilience? } — it does NOT create a new HttpModule (the httpService is pre-resolved). If axios config needs to apply, the httpService must already carry it. The factory chain:

AuthRestModule.forRootAsync useFactory → returns AuthRestModuleOptions
  → HttpModule.registerAsync(opts.axios) → creates HttpService with axios config
  → RestModule.forHttpService(httpService from above, opts.resilience) → creates RestClient

This means AuthRestModule must also conditionally use HttpModule.registerAsync with opts.axios when it's provided.

Pattern 9: Static auth via RestClient (no AuthRestModule needed)

When to use: Static API tokens where credentials never change. No authentication lifecycle needed.

@Module({
  imports: [
    RestModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        axios: {
          baseURL: 'https://api.example.com',
          headers: {
            Authorization: `Bearer ${config.get('API_TOKEN')}`,
          },
        },
      }),
    }),
  ],
  exports: [RestClient],
})
export class CatalogModule {}

Use RestModule directly. AuthRestModule is only needed for dynamic authentication (token refresh, OAuth flows, etc.).

Test Patterns

Unit test: stub both transport and strategy

Tests in src/auth/__tests__/ stub the underlying RestClient and AuthStrategyService as plain objects with jest.fn(). No @nestjs/testing needed for unit tests.

// AuthRestClient unit test pattern
function createRestClientStub(): RestClientStub {
  const stub = {} as RestClientStub
  for (const verb of ALL_VERBS) {
    stub[verb] = jest.fn().mockResolvedValue({ data: 'ok' } as AxiosResponse)
  }
  return stub
}
const client = new AuthRestClient(restClientStub as unknown as RestClient, authStrategyStub as unknown as AuthStrategyService)

Unit test: DI module with TestingModule

Tests in src/auth/__tests__/auth-rest.module.spec.ts use @nestjs/testing to bootstrap the full module and verify DI wiring:

const moduleRef = await Test.createTestingModule({
  imports: [AuthRestModule.forRootAsync({ useFactory: () => ({ httpService, authConfig }) })],
}).compile()
const authRestClient = moduleRef.get(AuthRestClient)
const restClient = moduleRef.get(RestClient)
// Verify single-source-of-truth: same RestClient instance
expect(authRestClient.restClient).toBe(restClient)

E2e test: httpbin container

E2e specs in tests/ receive process.env.TEST_HTTP_BASE_URL from tests/e2e-setup.ts (globalSetup). Use HttpService + axios.create({ baseURL }) for real HTTP calls. Container is kennethreitz/httpbin via testcontainers.

Common Pitfalls & Solutions

Recommendations

1. Use dispatch override pattern for cross-cutting concerns — AuthRestClient and RestClient both override dispatch; this is the correct extension point, not method decorators on individual verbs.
2. Apply @DeduplicateInflight on performAuthenticate, not authenticateIfNeeded — the public method checks state first; the decorated private method is the network call that should be single-flighted.
3. Use inline tsconfig overrides in ts-jest transform block — never touch the root tsconfig for jest compatibility; tsdown requires moduleResolution: bundler.
4. Treat InvokeArgs as immutable — always produce a new object via spread before forwarding to callUnderlying or super.dispatch; retry paths depend on the pristine original.
5. Always declare readonly inflightMap on @DeduplicateInflight users — the decorator reads it via context.target.inflightMap; missing this causes a runtime error.
6. Use Type<AuthStrategy> in AuthRestModuleOptions (post-refactor) — NestJS resolves and instantiates the class via DI; do not instantiate it manually in the factory.

Implementation Guidance

Integration Points

• RestClient.policy — IPolicy<IDefaultPolicyContext, any>, built in constructor from ResilanceConfig
• AuthRestClient.authStrategy — public readonly field; read by module wiring, tests, and adapters
• AuthRestClient.restClient — getter returning this.httpService as RestClient; used for single-source-of-truth verification
• AuthStrategyService.inflightMap — public Map<string, Promise<unknown>>; required by @DeduplicateInflight
• AuthRestModule re-exports RestModule (not RestClient directly) so consumers get the canonical RestClient provider without a second instance

File Structure (auth module)

src/auth/
  auth.config.ts          # AuthStrategy interface (AuthConfig removed in refactor)
  auth-strategy.service.ts # Renamed to auth-processor.ts in refactor
  auth-rest.client.ts     # AuthRestClient extends HookableHttpService
  auth-rest.module.ts     # AuthRestModule.forRootAsync
  __tests__/
    auth-strategy.service.spec.ts  # Renamed to auth-processor.spec.ts in refactor
    auth-rest.client.spec.ts
    auth-rest.module.spec.ts
tests/
  auth-rest-client.e2e.spec.ts
  rest-client.e2e.spec.ts
  smoke.e2e.spec.ts
  e2e-setup.ts            # globalSetup: starts httpbin container
  e2e-teardown.ts         # globalTeardown: stops container

Pending Refactor: improve-library-usability

The following changes are required by task improve-library-usability:

Sources & Verification

Changelog