Skip to content

Verify binary request classification against API Gateway HTTP API #68

Closed

Description

@danmoz

Description

api_gateway_v2 attempts to reproduce API Gateway's text/binary request handling, including setting isBase64Encoded and base64-encoding binary request bodies.

The current classification is based on media type and UTF-8 validity. This is sensible, but API Gateway's exact behaviour for less common content types and malformed payloads is not completely obvious from its documentation.

Because the goal of this event format is API Gateway v2 compatibility, we should verify the behaviour empirically against a real API Gateway HTTP API.

Suggested test matrix

At minimum:

  • text/plain
  • application/json
  • application/problem+json
  • application/xml
  • application/octet-stream
  • image/jpeg
  • multipart/form-data
  • unknown/vendor media types
  • no Content-Type
  • valid UTF-8 with a binary content type
  • invalid UTF-8 with a textual content type
  • empty bodies

For each request, capture the event received by an identical Lambda through both API Gateway and caddy-lambda and compare body, isBase64Encoded, and relevant headers.

Any intentional differences should be documented.

Acceptance criteria

  • Binary/text behaviour is tested against a real API Gateway HTTP API.
  • Common and edge-case media types are covered.
  • caddy-lambda behaviour matches API Gateway where practical.
  • Intentional incompatibilities are documented.
  • Regression tests cover the resulting behaviour.

Activity

  1. danmoz commented on Sep 5, 2026

    @danmoz
    OwnerAuthor

    Blocked by #73. The current echo fixture does not expose the raw API Gateway event, so the matrix cannot verify body or isBase64Encoded. Issue #73 will add concurrency-safe event metadata to the echo response.

  2. danmoz commented on Sep 5, 2026

    @danmoz
    OwnerAuthor

    Implementation is available in PR #74, which fixes #73 and unblocks this verification work.

  3. danmoz commented on Sep 5, 2026

    @danmoz
    OwnerAuthor

    Ran the issue #68 matrix against the deployed endpoint. The echo fixture now exposes the raw event metadata.

    Case HTTP isBase64Encoded Raw event body
    text/plain 200 false hello world
    application/json 200 false {"hello":"world"}
    application/problem+json 200 false JSON body unchanged
    application/xml 200 false <message>hello</message>
    application/octet-stream 200 true AAH+/w==
    image/jpeg 200 true /9j/4GZha2UtanBlZy1kYXRh/9k=
    multipart/form-data 200 true Base64-encoded multipart payload
    application/vnd.example.test 200 true dmVuZG9yIHBheWxvYWQ=
    No Content-Type 200 false no content type
    Valid UTF-8 with application/octet-stream 200 true dmFsaWQgVVRGLTggdGV4dA==
    Invalid UTF-8 with text/plain 200 false Replacement characters (���)
    Empty text/plain body 200 false null/omitted body
    Empty application/octet-stream body 200 false null/omitted body

    The endpoint and all tested scenarios are working. These results cover caddy-lambda behavior; a direct API Gateway comparison is still needed to determine compatibility differences.

  4. danmoz commented on Sep 5, 2026

    @danmoz
    OwnerAuthor

    Ran the same matrix through a temporary API Gateway HTTP API (payload format 2.0).

    Case API Gateway caddy-lambda Result
    text/plain false false Match
    application/json false false Match
    application/problem+json false false Match
    application/xml false false Match
    application/octet-stream true true Match
    image/jpeg true true Match
    multipart/form-data true true Match; generated boundaries differ
    application/vnd.example.test true true Match
    No Content-Type true false Mismatch
    Valid UTF-8 with application/octet-stream true true Match
    Invalid UTF-8 with text/plain false false Match; both returned replacement characters
    Empty text/plain body false false Match
    Empty application/octet-stream body false false Match

    The only observed compatibility difference is the no-Content-Type case. API Gateway returned isBase64Encoded: true with event body bm8gY29udGVudCB0eXBl, while caddy-lambda returned isBase64Encoded: false with the plain body no content type. All tested requests returned HTTP 200.

  5. danmoz commented on Sep 5, 2026

    @danmoz
    OwnerAuthor

    Fix available in PR #75: #75. It matches API Gateway v2 by base64-encoding non-empty bodies without Content-Type, while preserving HTTPJSON behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions