diff --git a/memory-bank/decisions.md b/memory-bank/decisions.md index 43fcc8de..e7a676e2 100644 --- a/memory-bank/decisions.md +++ b/memory-bank/decisions.md @@ -45,3 +45,38 @@ Related: - `context/project-overview.md` - `memory-bank/README.md` + +--- + +### D-002: Relay forwarding hardening policy baseline (P2-S3) + +date: 2026-03-24 +author: Cline +scope: `pages/api/middleware/relayForwarding.js`, relay-backed endpoint handlers +type: decision +rationale: Consolidate relay reliability behavior into one shared policy so retries, timeouts, and logging are predictable and safe across all migrated GET flows. +impact: Improves resilience and observability while reducing risk of accidental overload, noisy duplicate logs, and inconsistent retry behavior per endpoint. +status: accepted + +Decision: + +- Shared relay defaults and bounds are centrally enforced in middleware: + - timeout default `8000ms`, clamped to `100..30000ms` + - retries default `2`, clamped to `0..4` + - retry delays clamped to `0..5000ms` +- Retry classification is explicit: + - retryable: `408`, `429`, `5xx`, selected network/transient transport error codes + - non-retryable: deterministic client/auth statuses (`400`, `401`, `403`, `404`, `422`) and other explicit non-retryable HTTP statuses +- Structured relay logs are redacted and emitted once per failure path: + - relay layer emits retry/failure structured events + - endpoint catch logging avoids duplicate emission when relay layer already logged terminal failure + +Consequences: + +- Endpoint contracts remain unchanged while reliability behavior is normalized. +- Future relay policy changes should be made in one location and validated via phase21 hardening tests. + +Related: + +- `memory-bank/change-log.md` (CL-030, CL-031) +- `tests/phase21/relay-forwarding-hardening.test.cjs` diff --git a/memory-bank/patterns.md b/memory-bank/patterns.md index 8734e940..a9a1e288 100644 --- a/memory-bank/patterns.md +++ b/memory-bank/patterns.md @@ -64,3 +64,28 @@ Example paths: - `locales/en/**`, `locales/cy/**` - `next.config.js`, `i18n.js` + +### P-003: Shared Relay Policy via Middleware (No Endpoint Drift) + +date: 2026-03-24 +author: Cline +scope: `pages/api/middleware/relayForwarding.js`, `pages/api/endpoint/*_api.js` relay GET handlers +type: pattern +rationale: Keep reliability and logging policy centralized so endpoint handlers remain thin and behavior stays consistent as relay surface evolves. +impact: Reduces duplication/drift in timeout/retry/error behavior and supports safer incremental endpoint migration/hardening. +status: accepted + +Pattern: +Implement retry/timeout/redacted structured logging in shared relay middleware and keep endpoint handlers focused on validation, transform, and route-level response contracts. + +When to use: + +- Any new or migrated relay-backed endpoint +- Any relay reliability/logging policy update + +Example paths: + +- `pages/api/middleware/relayForwarding.js` +- `pages/api/endpoint/getadvancedsearch_api.js` +- `pages/api/endpoint/getdnscoords_api.js` +- `tests/phase21/relay-forwarding-hardening.test.cjs` diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md index 1913be50..b65a3527 100644 --- a/memory-bank/techContext.md +++ b/memory-bank/techContext.md @@ -22,6 +22,21 @@ - Additional custom server entries exist (`server.js`, `server/server.js`) but are currently treated as non-active for the refactor baseline unless deployment evidence indicates otherwise. - Environment-driven config for auth, relay/API roots, hash key, notify key, and database URL. +### Relay forwarding hardening policy knobs (P2-S3) + +- Shared relay middleware now enforces centralized timeout/retry behavior for relay-backed GET flows. +- Supported env knobs: + - `RELAY_TIMEOUT_MS` (default `8000`, clamped `100..30000`) + - `RELAY_RETRY_MAX` (default `2`, clamped `0..4`) + - `RELAY_RETRY_BASE_DELAY_MS` (default `200`, clamped `0..5000`) + - `RELAY_RETRY_MAX_DELAY_MS` (default `1200`, clamped `0..5000`) +- Retry classification: + - retryable: `408`, `429`, `5xx`, selected transient transport errors + - non-retryable: deterministic client/auth statuses (`400`, `401`, `403`, `404`, `422`) and other explicit non-retryable HTTP statuses +- Logging behavior: + - structured redacted relay events emitted for retry/failure + - duplicate endpoint-layer error logging suppressed when relay layer already emitted terminal failure log + ## Tooling and quality gates - Linting: `npm run lint` (`next lint`).