A Stacktape WebSocket API Gateway creates a managed, pay-per-use WebSocket endpoint backed by Lambda functions. You define the gateway once and attach routes such as $connect, $disconnect, $default, and sendMessage to functions. Stacktape creates the API, integrations, permissions, deployment stage, access logs, and connection-management access.
The default route selection expression is $request.body.action. A client message such as { "action": "sendMessage", "text": "hello" } therefore invokes the function that owns the sendMessage route.
When to use
Use a WebSocket API Gateway for Lambda-based real-time features that should have no always-on server cost:
- chat and collaboration updates
- progress, job-status, and deployment notifications
- lightweight presence and live dashboards
- targeted server-to-client notifications
- applications with spiky or modest concurrent connection counts
Use an Application Load Balancer instead when you already run a persistent container WebSocket server, need a framework such as Socket.IO with server-side state, or need more control over the connection process.
Basic example
Routes live on Lambda functions rather than inside the gateway. The route handlers automatically receive the gateway connection variables and the scoped execute-api:ManageConnections permission; you do not also need to add the gateway to their connectTo lists.
Stacktape owns one stable internal stage and deploys route changes automatically. There is no stage or deployment setting to keep in sync.
Route behavior
| Route | When it runs |
|---|---|
$connect | During the opening handshake. Returning an error rejects the connection. |
$disconnect | After a connection closes. Delivery is best-effort and is not guaranteed. |
$default | When no custom route matches, including messages that cannot be selected. |
| Custom key | When the route selection expression resolves to that key. |
Only JSON messages can be selected by $request.body.action. Non-JSON messages and JSON without a matching action go to $default when that route exists.
Route handler return bodies are not sent to the client by default. Use returnResponse: true for a simple reply to the calling client, as described below. Use the API Gateway Management API when the application should send later, broadcast, or target a different connection.
Sending a message to a connection
For a gateway named realtime, every route handler receives:
STP_REALTIME_URL— the publicwss://client URLSTP_REALTIME_MANAGEMENT_ENDPOINT— the HTTPS endpoint forApiGatewayManagementApiClientSTP_REALTIME_API_ID— the API IDSTP_REALTIME_CANONICAL_DOMAIN— the AWS DNS target
The handler also gets connection-management permission scoped to this gateway and Stacktape's managed stage.
Do not post to the connection from $connect: the connection does not exist until that handler succeeds. Handle GoneException when a connection has already closed.
Other producers can send to clients too. Add connectTo: [realtime] to a different Lambda, container workload, batch job, or script to receive the same scoped permission and environment variables. The permission covers PostToConnection, GetConnection and DeleteConnection on every connection of the gateway's stage.
Connection storage and broadcasts
Stacktape does not create a DynamoDB connection registry automatically. A direct reply needs only the connectionId in the current event, while broadcast, rooms, and user-to-connection lookup each need different application data. An automatic table would impose the wrong schema on many applications.
When you need lookup or broadcast:
- Add a normal DynamoDB table for the fields your application needs.
- Connect the
$connect,$disconnect, and broadcasting workloads to that table withconnectTo. - Store connection IDs with a TTL.
- Delete stale records when a Management API send returns
GoneException.
TTL and failed-send cleanup matter because $disconnect is best-effort and may not run.
Authorization
Authorization is optional and belongs on the $connect route because API Gateway authorizes a WebSocket connection only while opening it. Later messages use the identity established at connection time and any checks in your application code.
For application-specific authentication, use a Lambda REQUEST authorizer:
The default identity source is route.request.header.Authorization. You can explicitly use header or query-string sources such as route.request.querystring.token. A WebSocket Lambda authorizer returns an IAM policy response; the HTTP API simple-response and JWT/Cognito authorizer settings do not apply.
Use { type: 'aws-iam' } only for clients that can sign the opening request with AWS Signature Version 4. It is usually unsuitable for ordinary browser clients.
Return a response to the calling client
WebSocket routes are one-way by default. For a simple request-response interaction on $default or a custom message route, set returnResponse: true and return a body from the Lambda handler:
Stacktape configures the API Gateway route response, and only the client that invoked the route receives the returned body. Lifecycle routes ($connect and $disconnect) cannot use returnResponse, because no established calling connection is available for that reply. Keep the default for broadcasts, delayed responses, and messages sent to a different connection; use the management endpoint for those cases.
Custom domains
Add customDomains when clients should connect through your own hostname:
Stacktape provisions the regional custom-domain mapping, certificate, and Route53 alias by default. Use disableDnsRecordCreation or customCertificateArn for externally managed DNS or certificates, as described in Custom domains.
AWS does not allow one API Gateway custom domain to mix WebSocket mappings with HTTP or REST API mappings. Stacktape rejects duplicate domain attachment in the config before deployment.
Logs
JSON access logs are enabled by default with connection ID, event type, route, status, source IP, request time, and integration error context. Payload data is not logged by default. Configure retention or forwarding through logging, or set logging.disabled: true.
API Gateway writes WebSocket access logs with a CloudWatch Logs role that is set once per AWS account and region, in the API Gateway settings. New accounts have none, and a stage with access logs then fails to deploy. Before such a deployment, Stacktape checks the setting. When no role is set, it creates the IAM role stacktape-api-gateway-cloudwatch-logs with the AWS managed policy AmazonAPIGatewayPushToCloudWatchLogs, registers it for the region, and says so in the output. The account has one such role, used by every region. Stacktape never replaces a role that is already set; when the set role no longer exists, the deployment stops and says so. The check needs apigateway:GET on /account; without it, Stacktape warns and deploys. Creating and registering the role needs iam:GetRole, iam:CreateRole, iam:AttachRolePolicy and iam:PassRole on that role and apigateway:PATCH on /account. The Console's connection role has all of them.
logging.logClass: 'infrequent-access' is available for newly created log groups when lower ingestion cost matters more than live log features. Infrequent Access logs require Logs Insights and cannot use log forwarding.
Dev mode
stacktape dev keeps the WebSocket gateway deployed and hot-swaps its Lambda handlers. Dev stages have no access logs. The dev UI shows the deployed wss:// URL. Stacktape does not emulate API Gateway's connection lifecycle locally, so test clients continue to use the deployed endpoint while code changes are updated quickly.
AWS limits to design around
API Gateway currently limits a connection to 2 hours with a 10-minute idle timeout. Frames are limited to 32 KB, messages to 128 KB, binary frames are unsupported, and integrations can run for at most 29 seconds. Split large payloads and design clients to reconnect.
Referenceable parameters
Use $ResourceParam('realtime', 'paramName') in configuration. connectTo injects these values into workloads automatically.
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
API Gateway ID
- Usage:
$ResourceParam('<<resource-name>>', 'apiId')
WebSocket client URL
- Usage:
$ResourceParam('<<resource-name>>', 'url')
HTTPS endpoint for sending messages to connected clients
- Usage:
$ResourceParam('<<resource-name>>', 'managementEndpoint')
AWS DNS target
- Usage:
$ResourceParam('<<resource-name>>', 'canonicalDomain')
Comma-separated list of custom domain names
- Usage:
$ResourceParam('<<resource-name>>', 'customDomains')
Comma-separated list of custom domain URLs
- Usage:
$ResourceParam('<<resource-name>>', 'customDomainUrls')
URL of the first custom domain
- Usage:
$ResourceParam('<<resource-name>>', 'customDomainUrl')
API Reference
WebSocketApiGatewayPropsWebSocketApiIntegrationProps