Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

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:

  • $connect asks the route named by the path query parameter as an upgrade. The rest of the query is the route's. before and 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 $default message goes to the handler's recv. send posts to the connection's @connections URL, 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.
  • $disconnect ends recv.

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.

  • ORIGIN is 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 (on recv, 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 $disconnect of 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 @connections calls). 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::channel reaches 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_IDLE does not apply. A message over the route's BODY_LIMIT ends recv and 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 send is one signed HTTPS call to API Gateway.

Environment

  • WISP_SECRET as 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%3Fb routes as on the binary. Wisp cannot tell a %2F from /, 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 tower feature with lambda_http also works: Testing and mixing with Rust code.
  • wisp::cron and wisp::work run from EventBridge Scheduler: when the app has jobs the build writes eventbridge.sh, one schedule per wisp::cron (and one each minute for queues), in AWS's six-field cron(..) with the weekday counted 1 to 7 from Sunday. Run it after deploying with FUNCTION_ARN and ROLE_ARN (a role that Scheduler assumes, with permission for lambda:InvokeFunction). Each run invokes one instance with {"wisp_cron":"<schedule>"}, which runs that schedule's tasks and then the due jobs. On Lambda wisp::cron sets 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. Set WISP_STORE for 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: use wisp::store for lasting data. See Where rows are kept.
  • wisp::kv and wisp::blobs default to files under /tmp/wisp-data/storage, per instance: set WISP_KV_<NAME>=upstash and WISP_BLOB_<NAME>=s3:<endpoint>/<bucket>. See Storage.

More

Edge and serverless targets, Deploying.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.