Host on AWS Lambda
AWS Lambda runs the app's own static Linux binary on the provided.al2023 runtime. The binary that wisp build --target lambda makes answers Lambda's runtime API when AWS_LAMBDA_RUNTIME_API is set. A plain release build leaves that runtime out, so it compiles faster, and stops with a message on Lambda. WISP_LAMBDA=1 for a plain cargo build --release keeps it.
Build
rustup target add x86_64-unknown-linux-musl # once
wisp build --target lambda # dist/lambda/bootstrap.zip
The build links the binary with Rust's lld and needs no C toolchain (an app with WebSocket routes needs one: WebSockets).
Deploy
Create the function once (runtime provided.al2023, x86_64, handler bootstrap) and add a Function URL (or API Gateway or an ALB):
aws lambda create-function --function-name my-app --runtime provided.al2023 \
--architectures x86_64 --handler bootstrap --role <role-arn> \
--zip-file fileb://dist/lambda/bootstrap.zip
Then for each release:
aws lambda update-function-code --function-name my-app --zip-file fileb://dist/lambda/bootstrap.zip
Behind an ALB without multi-value headers, a reply holds at most 512 set-cookie headers. Wisp sends the first 512 and logs one line for the reply.
wisp deploy init lambda writes a GitHub Actions workflow that runs that update on push to main. It reads the secret AWS_ROLE_ARN (a role GitHub may assume) and the variables AWS_REGION and LAMBDA_FUNCTION.
WebSockets
A Response::websocket route runs on Lambda behind an API Gateway WebSocket API, with the same handler code as on the binary. API Gateway holds the connection. Wisp turns its events into the handler's recv and send:
$connectasks the route named by thepathquery parameter as an upgrade. The rest of the query is the route's.beforeand the origin check run as for any route. An upgrade starts the handler and API Gateway takes the connection. The client gets any other answer (a 403, a 404) instead.- Each
$defaultmessage goes to the handler'srecv.sendposts to the connection's@connectionsURL, signed with the function's role (SigV4). What the handler sends before the connection is open waits for it. When the handler returns, Wisp deletes the connection there. $disconnectendsrecv.
The client names the route:
const ws = new WebSocket('wss://<api-id>.execute-api.<region>.amazonaws.com/prod?path=/chat');
Build
wisp build --target lambda sees the WebSocket routes and turns on wisp's tls feature, since @connections is https. Its crypto (ring) compiles some C for Linux, so this build needs a C compiler for Linux: on x86_64 Linux the system gcc (or musl-gcc), or any cross compiler named in CC_x86_64_unknown_linux_musl. The build stops early and says so when it finds none. An app with no WebSocket route builds as before, with no C toolchain.
From Windows or macOS, run that build on an x86_64 Linux machine or a Linux CI runner (GitHub Actions ubuntu-latest has gcc). wisp deploy init lambda writes such a workflow.
AWS_ENDPOINT_URL_APIGATEWAYMANAGEMENTAPI (https://host/stage, as AWS's SDKs read it) sends the @connections calls somewhere else: a VPC endpoint, LocalStack, a test stand-in.
Deploy
A connection's handler lives in the instance that took its $connect, so the WebSocket API gets a function of its own from the same zip, held to one instance (which caps its scale: Limits). The HTTP function keeps scaling.
# The same bootstrap.zip as a second function, one instance at a time.
aws lambda create-function --function-name my-app-ws --runtime provided.al2023 \
--architectures x86_64 --handler bootstrap --role <role-arn> --timeout 10 \
--environment "Variables={ORIGIN=https://my-app.example}" \
--zip-file fileb://dist/lambda/bootstrap.zip
aws lambda put-function-concurrency --function-name my-app-ws --reserved-concurrent-executions 1
# The WebSocket API: $connect, $disconnect and $default to that function.
aws apigatewayv2 create-api --name my-app-ws --protocol-type WEBSOCKET \
--route-selection-expression '$request.body.action'
aws apigatewayv2 create-integration --api-id <api-id> --integration-type AWS_PROXY \
--integration-uri arn:aws:lambda:<region>:<account>:function:my-app-ws
for route in '$connect' '$disconnect' '$default'; do
aws apigatewayv2 create-route --api-id <api-id> --route-key "$route" --target integrations/<integration-id>
done
aws apigatewayv2 create-stage --api-id <api-id> --stage-name prod --auto-deploy
aws lambda add-permission --function-name my-app-ws --statement-id apigateway \
--action lambda:InvokeFunction --principal apigateway.amazonaws.com \
--source-arn "arn:aws:execute-api:<region>:<account>:<api-id>/*"
The function's role also needs execute-api:ManageConnections on arn:aws:execute-api:<region>:<account>:<api-id>/prod/*/@connections/*, to send and to close.
ORIGINis the site whose pages connect: the page and the API have different hosts, so without it the origin check refuses the upgrade (403).--timeout: after each event the handlers run until they all wait again (onrecv, a channel), then Lambda freezes the instance. That must fit in the timeout, 3 s by default.
Limits
- Scale is one instance. Reserved concurrency 1 is what keeps every connection's handler in reach, and it is also the ceiling: one Lambda instance handles every
$connect, message and$disconnectof the API, one event at a time. Lambda throttles an event that arrives while it is busy, so throughput is what one instance can do serially (each event costs the handler's time plus its@connectionscalls). Wisp has no way to spread connections over instances here. For more, use a host that holds sockets (node,bun,deno,cloudflare, the binary) or a realtime service. - One instance holds every connection, so
wisp::channelreaches every handler of that function (send to it from a handler, not from the HTTP function, which is another instance). A message for a connection the instance does not hold (Lambda replaced it, or a second instance took it) closes that connection with a line on stderr, and the client reconnects: give clients a reconnect loop. - API Gateway takes text frames only (a binary frame closes the connection with 1003), up to 128 KB a message, and closes a connection idle for 10 minutes or open for 2 hours (quotas). It answers pings itself, so
WISP_WS_IDLEdoes not apply. A message over the route'sBODY_LIMITendsrecvand closes the connection, as does more than 1 MiB of messages the handler has not read. - Between events nothing runs: a handler's timer fires at the next event.
- Each
sendis one signed HTTPS call to API Gateway.
Environment
WISP_SECRETas an environment variable of the function, for an app that signs cookies.- Other variables: Environment variables.
Limits
- Everything works. Wisp collects a streamed reply and sends it whole (up to 25 s and 4 MB, so its base64 still fits), unless the Function URL streams (below). WebSockets need the WebSocket API above: through a Function URL a WebSocket route answers 501.
- Behind a REST API (payload 1.0) API Gateway hands over the path decoded. Wisp encodes
%,?,#, spaces and non-ASCII in it again, so/files/a%3Fbroutes as on the binary. Wisp cannot tell a%2Ffrom/, so it routes as one. HTTP APIs, Function URLs and ALBs pass the path as sent. A body marked base64 that is not answers 400. - Lambda answers at most 6 MB a buffered reply, and a body that is not UTF-8 goes as base64, a third larger. A reply over that is answered 500 with
Internal Server Error: the reply is over Lambda's 6 MB, and the log says why, rather than Lambda's bare 502. Stream large replies. - The
towerfeature withlambda_httpalso works: Testing and mixing with Rust code. wisp::cronandwisp::workrun from EventBridge Scheduler: when the app has jobs the build writeseventbridge.sh, one schedule perwisp::cron(and one each minute for queues), in AWS's six-fieldcron(..)with the weekday counted 1 to 7 from Sunday. Run it after deploying withFUNCTION_ARNandROLE_ARN(a role that Scheduler assumes, with permission forlambda:InvokeFunction). Each run invokes one instance with{"wisp_cron":"<schedule>"}, which runs that schedule's tasks and then the due jobs. On Lambdawisp::cronsets no timer, so concurrent instances never both run it, and the schedules have no retries. A schedule with both a day of the month and a weekday, or a weekday step (*/2), stops the build: AWS cannot say it. SetWISP_STOREfor queued jobs.
Streaming
A Function URL whose invoke mode is RESPONSE_STREAM sends the reply as it comes: SSE, large downloads, up to 200 MB (AWS). Lambda cannot be asked which mode it is, so tell the app:
aws lambda update-function-url-config --function-name my-app --invoke-mode RESPONSE_STREAM
aws lambda update-function-configuration --function-name my-app \
--environment "Variables={WISP_LAMBDA_STREAM=1,WISP_SECRET=...}"
With WISP_LAMBDA_STREAM=1 each Function URL (payload 2.0) reply goes out as Lambda's streamed HTTP integration response: the status, headers and cookies, then the body chunk by chunk, until it ends or a second before the invocation's timeout. Past the first 6 MB Lambda sends at most 2 MB/s, and a Function URL in a VPC does not stream (AWS). Set it only with RESPONSE_STREAM: a BUFFERED URL would show the stream's framing as the body.
Files and Data
static/is inside the binary.- Saved tables go in
/tmp, per instance: usewisp::storefor lasting data. See Where rows are kept. wisp::kvandwisp::blobsdefault to files under/tmp/wisp-data/storage, per instance: setWISP_KV_<NAME>=upstashandWISP_BLOB_<NAME>=s3:<endpoint>/<bucket>. See Storage.
More
Edge and serverless targets, Deploying.
Is This Page Useful?