WebSockets

1. System Context

Developers use Nitric to define required WebSocket APIs within their application.

  • App code interacts with the WebSocket resource through defined routes and integrations.
  • Developers implement backend logic to handle WebSocket connections, messages, and disconnections.

Operations use default or overridden IaC (e.g Terraform modules) to provision the necessary resources for their target cloud.

Example AWS Provider
  • AWS API Gateway v2 manages WebSocket API endpoints and routes.
  • AWS Lambda functions handle WebSocket events such as connection, message reception, and disconnection.
  • AWS IAM manages roles and policies for secure access between API Gateway and Lambda functions.
Code
Terraform
Create WebSocket API
Configure Integrations
Deploy Lambda Functions
Invoke Lambda/Handle Events
Manage Permissions
Developer
Operations
nitric up
AWS API Gateway v2
(WebSocket API)
AWS Lambda Functions
AWS IAM

2. Sequence

Build Sequence

Here is the sequence of events that occur when a developer registers an Websocket API with Nitric, including the registration of handlers for connection, message, and disconnection events.

App Worker(s)Nitric SDKNitric CLINitric Provider (plugin)IaC (e.g. Terraform)Register Websocket(s)Register Websocket(s)Register Connection HandlerRegister Connection HandlerRegister Message HandlerRegister Message HandlerRegister Disconnection HandlerRegister Disconnection HandlerForward Nitric SpecProvision Websocket APIProvision IAMApp Worker(s)Nitric SDKNitric CLINitric Provider (plugin)IaC (e.g. Terraform)

Runtime Sequence

Here is the sequence of events that occur at runtime when a websocket connection is established, messages are sent and received, and the connection is closed.

ClientWebSocket Gateway (e.g. AWS API Gateway)Nitric Runtime (plugin)Nitric SDKApp Codealt[Client Message][Server Message]loop[Real-Time Communication]Connect to ws:// endpointForward Connection EventConnection CallbackSend WS MessageForward MessageForward MessageMessage CallbackSend WS MessageForward MessageForward MessageDeliver MessageDisconnectForward Disconnection EventDisconnection CallbackClientWebSocket Gateway (e.g. AWS API Gateway)Nitric Runtime (plugin)Nitric SDKApp Code

3. Component

WebSocket API Module

  • Dynamically creates and manages WebSocket APIs to enable real-time, bidirectional communication between clients and servers.
  • Configures API properties such as protocol type, route selection expressions, and tags for governance and management.
  • Automatically provisions and links backend integrations to handle events for connection establishment ($connect), message handling ($default), and disconnections ($disconnect).
  • Grants permissions to enable secure communication between the WebSocket gateway and backend services, adhering to the principle of least privilege.
  • Supports deployment of WebSocket APIs with automatic handling of stage configurations and versioning for seamless updates.
  • Abstracts cloud-specific WebSocket services, ensuring a consistent developer experience across providers.
  • Ensures fault-tolerant and scalable handling of WebSocket connections, supporting high-throughput scenarios with minimal configuration.

4. Code

Developers write application code that uses the WebSocket resource from the SDK and implement backend logic to handle WebSocket connections, messages, and disconnections.

SDK Reference by language -

Operations will use or extend the Nitric infrastructure modules, including both Terraform and Pulumi:

Edit this page on GitHub
Last updated on Feb 15, 2025