Difficulty: Expert | Type: architecture / feature
Background: The SDK's internal HTTP layer (underlying all service modules) has no documented extensibility point for consumers wanting to observe or modify requests/responses (e.g., adding custom telemetry headers, logging every call for debugging, or transforming a response before it reaches application code).
Problem: Without a middleware/interceptor mechanism, any cross-cutting consumer need (telemetry, custom auth header injection beyond the built-in apiKey, request/response logging for debugging) currently has no supported extension point and would require monkey-patching or forking the SDK.
Expected outcome: A new, optional client config accepts an ordered list of middleware functions, each able to observe/modify the outgoing request and the incoming response (or short-circuit with a synthetic response, e.g., for testing), composed consistently across every service module's HTTP calls.
Suggested implementation: Define a middleware function signature ((request, next) => Promise<response>, an "onion" composition pattern familiar from HTTP middleware conventions in other ecosystems); thread all service-module HTTP calls through a single internal composed-middleware pipeline; ensure middleware composition correctly interacts with the retry (#4), circuit-breaker (#17), and caching layers (established order: caching wraps the middleware pipeline, or vice versa — this ordering must be explicitly decided and documented, not left ambiguous).
Acceptance criteria: A test middleware that adds a custom header is verified present on the actual outgoing request for every service module; a test middleware that short-circuits with a synthetic response correctly prevents the real network call from firing; the documented interaction order between middleware, caching, retry, and the circuit breaker is explicit and covered by at least one test exercising the combination.
Likely affected files/directories: new src/http/middleware.ts, src/client.ts, src/types.ts, docs/architecture.md, tests/*
Recommended labels: architecture, feature, expert, GrantFox OSS, Maybe Rewarded, Official Campaign | FWC26
Difficulty: Expert | Type: architecture / feature
Background: The SDK's internal HTTP layer (underlying all service modules) has no documented extensibility point for consumers wanting to observe or modify requests/responses (e.g., adding custom telemetry headers, logging every call for debugging, or transforming a response before it reaches application code).
Problem: Without a middleware/interceptor mechanism, any cross-cutting consumer need (telemetry, custom auth header injection beyond the built-in
apiKey, request/response logging for debugging) currently has no supported extension point and would require monkey-patching or forking the SDK.Expected outcome: A new, optional client config accepts an ordered list of middleware functions, each able to observe/modify the outgoing request and the incoming response (or short-circuit with a synthetic response, e.g., for testing), composed consistently across every service module's HTTP calls.
Suggested implementation: Define a middleware function signature (
(request, next) => Promise<response>, an "onion" composition pattern familiar from HTTP middleware conventions in other ecosystems); thread all service-module HTTP calls through a single internal composed-middleware pipeline; ensure middleware composition correctly interacts with the retry (#4), circuit-breaker (#17), and caching layers (established order: caching wraps the middleware pipeline, or vice versa — this ordering must be explicitly decided and documented, not left ambiguous).Acceptance criteria: A test middleware that adds a custom header is verified present on the actual outgoing request for every service module; a test middleware that short-circuits with a synthetic response correctly prevents the real network call from firing; the documented interaction order between middleware, caching, retry, and the circuit breaker is explicit and covered by at least one test exercising the combination.
Likely affected files/directories: new
src/http/middleware.ts,src/client.ts,src/types.ts,docs/architecture.md,tests/*Recommended labels:
architecture,feature,expert,GrantFox OSS,Maybe Rewarded,Official Campaign | FWC26