@standard-server/aws-lambda

@standard-server/aws-lambda adapts AWS Lambda events and response streams to the transport-agnostic request and response model defined by Standard Server.

Standard Server provides a unified interface for client-server communication across HTTP and message-based transports. It lets you write handlers against the same request, response, body, and streaming primitives whether the underlying transport is the Fetch API, Node.js HTTP, HTTP/2, or a peer-style message channel.

Standard Server ships as a small ecosystem of packages:

| Package | Description | | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | @standard-server/core | The shared contract: types, body parsing rules, validators, and SSE helpers | | @standard-server/fetch | Fetch API adapter for browsers, workers, and other Fetch-based runtimes | | @standard-server/node | Node.js HTTP and HTTP/2 adapter | | @standard-server/fastify | Fastify adapter built on the Node.js adapter | | @standard-server/aws-lambda | AWS Lambda adapter with response streaming | | @standard-server/peer | Message-based adapter for WebSocket, MessagePort, and custom transports | | @standard-server/shared | Internal utilities shared across the ecosystem |

This package is the AWS Lambda adapter for that model. It converts an API Gateway proxy event — payload format version 1.0 or 2.0, the latter also used by Lambda Function URLs — into a StandardLazyRequest, and writes a StandardResponse back through the stream provided by awslambda.streamifyResponse, so streaming bodies such as server-sent events flow to the client as they are produced instead of being buffered.

Package overview

The package exposes these helpers:

| Group | Exports | Purpose | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | Request and response | toStandardLazyRequest(), sendStandardResponse() | Adapt Lambda events and response streams to Standard Server | | Lower-level helpers | toStandardUrl(), toStandardHeaders(), getEventHeader(), toStandardBody(), toLambdaHeaders() | Convert individual pieces of an event | | Types and option shapes | APIGatewayProxyEvent, APIGatewayProxyEventV2, AnyAPIGatewayProxyEvent, HttpResponseStream, AwsLambdaGlobal, SendStandardResponseOptions | Type handler inputs and serializer options |

APIGatewayProxyEvent and APIGatewayProxyEventV2 are structural subsets of the same-named types from @types/aws-lambda, so events typed with either work; the adapter accepts both via AnyAPIGatewayProxyEvent and tells them apart by the top-level httpMethod field only payload format 1.0 carries. AwsLambdaGlobal describes the awslambda global the Lambda Node.js runtime injects — the package deliberately does not declare global, so importing it never pollutes your project's global types. Declare the global yourself where you need typed access to awslambda.streamifyResponse.

Server-side request handling

Use toStandardLazyRequest() to convert the incoming event into a StandardLazyRequest, then sendStandardResponse() to write the resulting StandardResponse back through the response stream. The handler must be wrapped with awslambda.streamifyResponse, and the function must run on the AWS Lambda Node.js runtime with response streaming enabled.

import type { AwsLambdaGlobal } from '@standard-server/aws-lambda'
import type { StandardLazyRequest, StandardResponse } from '@standard-server/core'
import { sendStandardResponse, toStandardLazyRequest } from '@standard-server/aws-lambda'

// injected by the AWS Lambda Node.js runtime when response streaming is enabled
declare const awslambda: AwsLambdaGlobal

async function handle(request: StandardLazyRequest): Promise<StandardResponse> {
  const body = await request.resolveBody()

  return {
    status: 200,
    headers: { 'content-type': 'application/json' },
    body: {
      ok: true,
      method: request.method,
      url: request.url,
      received: body,
    },
  }
}

export const handler = awslambda.streamifyResponse(async (event, responseStream, context) => {
  const standardRequest = toStandardLazyRequest(event, responseStream)
  const standardResponse = await handle(standardRequest)

  await sendStandardResponse(responseStream, standardResponse, {/** options */})
})

sendStandardResponse() sends the status, headers, and cookies as the response stream metadata prelude via awslambda.HttpResponseStream.from(), then streams the body. It resolves once the response is fully flushed, and rejects if the stream errors.

[!TIP] When sending responses, you can pass additional options such as event-stream keep-alive.

Resolving Body

The event carries the request body as a fully buffered, optionally base64-encoded string. resolveBody(hint?) decodes it and then follows the shared Standard Server resolution rules: an explicit hint wins, then the standard-server header, then inference from the content headers. See how body parsing works in the core README for the full algorithm.

[!TIP] For efficient communication, set the standard-server header to explicitly hint the body type, especially for file or binary streaming. For example, if you upload a file with a common content-type such as application/json but omit the standard-server header, the server may interpret it as JSON and parse it unexpectedly.

Lambda behavior to be aware of

• Response streaming must be enabled. sendStandardResponse() relies on the awslambda global, which only exists on the AWS Lambda Node.js runtime, and on the metadata prelude of awslambda.HttpResponseStream, which the platform only interprets for streaming-enabled invocations.
• set-cookie is sent via metadata cookies. Multiple cookies survive because they are sent through the dedicated cookies metadata field; every other multi-value header is joined with , .
• Request bodies are buffered. API Gateway delivers the whole request body at once, so request-side streaming degrades to a single buffered chunk. Response-side streaming is real streaming.
• Payload format 1.0 query strings are re-encoded. API Gateway delivers them url-decoded, so the adapter re-encodes them when reconstructing the standard url. Payload format 2.0 provides the already encoded rawQueryString, which is used as-is.
• Decoded paths are re-escaped. HTTP APIs deliver the request path url-decoded (payload format 2.0 rawPath included), while REST APIs and Lambda Function URLs deliver it still encoded. The adapter percent-encodes the same characters the WHATWG URL parser escapes in a pathname (?, #, spaces, non-ascii, ...), so encoded paths pass through unchanged and a decoded ? or # cannot be mistaken for the query string or fragment. Characters API Gateway already decoded into url syntax (%2F → /) or dropped cannot be recovered.
• Payload format 2.0 cookies are restored. API Gateway strips the cookie header into the separate cookies field, and the adapter joins them back into a cookie header on the standard request.

Learn more

For the project overview and the shared contract, see the core documentation. For the Node.js primitives this adapter is built on, see the Node.js adapter documentation.

Sponsors

Like what we build over at middleapi? You can help keep it going through GitHub Sponsors or Open Collective. Every bit helps! 🚀

Special Sponsors

Organization Sponsors

Sponsors

Backers

With thanks to 36 past sponsors who helped get us here.

License

Distributed under the MIT License. See LICENCE for more information.