Skip to content

HTTP event handler implementation checklist

  • H-OBSERVABILITY: Implement optional Metrics and OTel middleware. Verified 176 Metrics and 128 Tracer middleware reference cases (2,066 HTTP cases across the three modules), scope/span concurrency and body lifecycle tests, all 22 packaged modules/19 independent consumers, both CGO-disabled Linux builds, 622/622 RIE assertions, 95/95 streaming Runtime API checks and 14/14 Batch artifact checks (2026-09-22, Asia/Shanghai). Docker ran amd64; arm64 was cross-compiled. No AWS resources were used. See HTTP_OBSERVABILITY.md.

Reference: Powertools TypeScript v2.35.0. The HTTP utility is an independent eventhandler/http Go module. Scope includes every HTTP-01 through HTTP-11 item in the original feature inventory; a completed implementation slice does not establish full parity.

  • H-CORE: Implement the initial four event adapters, request/response conversion, static/dynamic/regex routing, prefixes/inclusion, middleware, stores and HTTP error policies. Verify 414 actual TypeScript cases, 64 concurrent callers, context/snapshot isolation, cancellation, panic cleanup and response-body ownership. JSON bodies use decoded-value comparison; remaining URL/regex/native/error boundaries are explicit in HTTP.md.

  • H-COMPOSE: Implement optional Standard Schema-style request/response checks with aggregate issues, separate transformed values and operational errors. Compose actual Parser/Validation callbacks and existing Logger/OTel context in all four HTTP event forms without importing these modules into HTTP. Reuse Commons environment/whitespace and the extracted Parser Base64/UTF-8 implementations.

  • H-01: Inspect public exports, options, defaults and actual implementation; record mappings and explicit language/runtime differences.

  • H-02: Implement REST API, HTTP API v2, ALB and Function URL adapters, request access and response serialization. Verify headers, multi-value fields, query parameters, cookies, bodies and binary encoding against the reference.
  • H-03: Implement static, parameter, wildcard and regex routes, method behavior, precedence, prefixes and router composition. Preserve reference matching semantics rather than inheriting an unrelated Go router's defaults.
  • H-04: Implement middleware order, early responses, errors, request state and shared stores with concurrent invocation isolation.
  • H-05: Implement built-in HTTP errors, custom error handlers, debug behavior and optional request/response logging.
  • H-06: Implement CORS, preflight and gzip/deflate compression, including pinned header negotiation and route policies. Verify 1,076 additional TypeScript cases, concurrent configuration snapshots and body lifecycle checks. Local composition adds 108 checks across four event formats, bringing Docker acceptance to 609/609 (2026-09-17, Asia/Shanghai). Standard-library compressor bytes can differ from Node; decoded bytes and each runtime's wire length are checked. Malformed native-header and Unicode case boundaries remain under H-11. See HTTP_MIDDLEWARE.md.
  • H-07: Compose Parser and Validation through small application-facing contracts; preserve structured errors and keep heavyweight dependencies optional.
  • Retired H-08: The pinned TypeScript v2.35.0 HTTP package does not expose OpenAPI generation. The original inventory entry is outside the requested one-to-one baseline; no implementation is claimed.
  • H-08-AUDIT: Reconcile the original OpenAPI entry against the installed package manifest, runtime HTTP/middleware exports and complete Router declarations/prototype (2026-09-23). The runtime namespace exposes 27 HTTP exports, Router has 17 own prototype members including its constructor/protected error handler, and middleware exports only compress/cors/metrics/tracer. None exposes an OpenAPI or Swagger generator. Keep request/response schema validation under H-07.
  • H-09: Implement native Lambda response streaming with cancellation, error handling, middleware cleanup and OTel composition. Keep unresolved platform behavior explicit.
  • H-09a: Implement shared streaming resolution, owned reader transfer, Lambda metadata framing and the native Go SDK adapter. Verify 272 additional TypeScript cases (1,762 HTTP total), first-byte/backpressure behavior, cancellation/error/panic cleanup, 32 concurrent streams and bounded reads for a 32 MiB generated body. The real Go Lambda SDK passed 95/95 Docker checks against a local Runtime API fixture, including error trailers, deadlines, warm recovery and Logger/OTel composition (2026-09-17, Asia/Shanghai). AWS service acceptance and the pinned SDK's missing response-mode header remain explicit under H-09; see HTTP_STREAMING.md.
  • H-10: Verify the initial 414 reference cases, concurrent reuse, all 20 packaged module tests/vet/tidy checks, seventeen independent consumers, both CGO-disabled Linux builds and 501/501 Docker assertions (2026-09-16, Asia/Shanghai). The same saved artifacts passed 14/14 Batch checks. Temporary containers/network were cleaned. Docker executed amd64; arm64 was cross-compiled only. No AWS resources were used. Root Commons, Parser and HTTP have no third-party module dependencies. Full parity remains under H-01 through H-09 and H-11.
  • H-11: Complete remaining public API/default/error parity, performance/resource budgets, dependency/license review and independent publication requirements.

Finite boundary audit #190

  • H-FINITE-190: Complete the matrix below, reproduce and fix header validation bypasses and retained-native body cleanup, and pass three affected packaged modules/three independent consumers with CGO disabled and GOWORK off. JSON v2, licenses, navigation, eighteen guides, strict site build and discovery checks pass (2026-10-13). Local Docker was unavailable; hosted runtime checks and AWS acceptance remain separate evidence.

This matrix reviews the named HTTP/Streaming boundaries in issue #190 against the installed TypeScript v2.35.0 package. It does not close the broad H-01 through H-05, H-07, H-09 or H-11 gates above. Existing evidence is reused before adding cases: 414 core, 1,076 CORS/compression, 272 streaming and 128 maintained OTel middleware fixtures, plus native header/cookie, request-body, JSON v2, error-redispatch and stream lifecycle tests.

tools/reference/generate-http-boundaries.mjs executes the actual public converters and Router and saves 88 observations in the HTTP module's own testdata/boundaries-v2.35.0.json. The upstream errors/messages and original outputs are retained. Tests compare successful URL/header/body/cookie values directly, with structural comparison only for JSON router bodies. Native Go error classes and messages are checked by their conversion/cause contract, rather than asserting Node's diagnostic spelling.

Boundary and public Go APIs Existing evidence Added evidence and classification
Request headers, ProxyEventToWebRequest Core fixtures and adapter/header tests 48 upstream cases across REST/v2/ALB/Function URL: valid token punctuation, padding, tabs and Latin-1 values verified; reproduced acceptance of control/DEL/non-ASCII names fixed with ASCII token validation. CR/LF/NUL values remain rejected.
URL conversion, ProxyEventToWebRequest Core request-field, encoded parameter and query cases 24 upstream observations: encoded slashes, literal plus, IPv6/port, malformed host and credentials reviewed. Four malformed-percent paths remain an intentional native difference: WHATWG retains %; Go net/url returns a wrapped native error before routing. The fixture is unchanged.
Named regex and HandleRegex Core specificity, named-regex and parameter cases Eight upstream cases verify named capture/miss, encoded slash, invalid UTF-8, blank parameter, explicit anchors and both ungrouped alternation branches. Registration wraps the pattern with ^/$; ungrouped alternation retains regex operator precedence in both implementations, so it can match a partial path. JavaScript-only forms/flags are outside this row.
Response headers/cookies, HandlerResultToWebResponse, Response, WebResponseToProxyResult Existing native/proxy/typed cookie and multi-value tests Eight upstream observations plus buffered/streaming native, typed, multi-value, cookie and inherited-header failures. Reproduced typed/native/cookie validation bypass fixed. Final middleware mutations and direct proxy conversion reject invalid fields before output and close owned bodies. Empty value slices still require a valid name.
Cookie representation Existing buffered and streaming projections Intentional native difference: Go Header retains every Set-Cookie value; pinned Web Headers entries() exposes the last while getSetCookie() preserves both. The single converter fixture explicitly maps this known view difference and still compares both cookie strings exactly, including Expires commas. Buffered output preserves all cookies; streaming metadata keeps the final cookie.
RequestContext.Respond and middleware body ownership Native ownership, cancellation/panic cleanup and middleware fixtures Replacement, error, panic and retaining the same native response verified. A failed retained-native conversion closes its body once and detaches it from deferred cleanup; buffered and streaming regressions cover that path. Headers remain caller-owned snapshots.
ResolveStream, Streamify, ResponseStream 272 upstream cases, staged first-byte/backpressure, blocking-read cancellation, failure/panic identity, 32 concurrent streams, bounded 32 MiB reads and cleanup-before-EOF Raw NUL/non-UTF-8 body bytes and two-field metadata/eight-byte framing verified. Short metadata/body writes preserve io.ErrShortWrite, close once and stop transfer. Sixteen concurrent Close calls cancel one blocked producer, preserve the event snapshot, wait for one cleanup and retain the cancellation cause on later reads. Destination ownership is unchanged.
Errors, validation and OTel composition Error-redispatch regressions, native read/write/close failures, JSON v2/validation suites and maintained HTTP Tracer's 128 fixtures plus #182 Verified existing Go error/cause, panic and iterative dispatch policies. No new error hierarchy, parser default or OTel capture behavior is introduced. Middleware parsing remains independent of the Tracer's metadata storage switch; the frozen X-Ray adapter is unchanged.

The fixes add no public API or dependency. They reject invalid header names and CR/LF/NUL values that previously passed some native paths; otherwise JSON v2, response encoding, ownership and maintained OTel policies remain intact.

Unreviewed boundaries remain explicit: exhaustive WHATWG URL/Headers/Unicode semantics, JavaScript regex flags/unsupported forms and regex prefixes, arbitrary native objects, async middleware misuse, default console/ALC logging, resource budgets (#200), publication and AWS streaming/integration acceptance (#201/#202). The local Runtime API's historical 95 checks are existing evidence, not a new AWS acceptance claim; the pinned SDK's missing response-mode header remains documented in HTTP_STREAMING.md. No cloud calls are needed to close this finite audit.

Streaming acceptance (2026-09-17, Asia/Shanghai): HTTP has 1,762 reference cases and a separate 95/95 real-SDK/local-Runtime-API acceptance suite. ResolveStream shares the original routing/middleware pipeline, and Streamify keeps producer cleanup inside the invocation lifetime. Cloud streaming and exhaustive API/platform parity remain open. See HTTP_STREAMING.md.

Final post-fix packaged verification passed all 20 modules and seventeen consumers with CGO disabled and GOWORK off; MODULE_ACCEPTANCE.json reflects that completed run. The passing 609-check RIE and 95-check streaming suites were reused. Both normal and streaming handlers were built for Linux amd64/arm64; Docker ran amd64 only.

Historical CORS acceptance (2026-09-17, Asia/Shanghai): HTTP has 1,490 reference cases (414 routing/validation and 1,076 CORS/compression). All 20 packaged modules and seventeen consumers passed before a development-fixture-only correction changed an absent REST GET body from empty string to null. Both Linux architectures were rebuilt and Docker passed 609/609; 14/14 Batch checks reused the same artifacts. The successful runtime continuation used --skip-module-checks, accurately reflected in LOCAL_ACCEPTANCE.json, rather than repeating passed module checks. No public library source changed after those module checks. Docker ran amd64, arm64 was cross-compiled, and temporary resources were cleaned. The earlier H-10 entry retains its original milestone counts.

Reuse standard Go HTTP primitives where they preserve the contract. Keep event adaptation, route matching and invocation execution cohesive and separate. Reuse Commons only for demonstrated shared behavior; do not make Logger, Tracer, Parser or Validation unconditional dependencies of ordinary HTTP routing. Preserve the original invocation context so existing instrumentation and cancellation continue to work.

All documentation and code comments are English. Every Go command uses CGO_ENABLED=0. Use local Docker by default; do not create AWS resources for this work.