WebSockets

1. System Context

Developers use Nitric to declare 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 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

ClientNitric SDKNitric RuntimeCloud WebSocket Gateway (e.g., AWS API Gateway, GCP WebSocket Gateway)loop[Real-Time Communication]alt[Disconnect]Connect to WebSocket endpointForward connection requestEstablish WebSocket connectionSend or receive WebSocket messageForward messageRelay messageForward response or broadcast messageRelay message to the clientDeliver messageDisconnect from WebSocketNotify runtimeClose WebSocket connectionClientNitric SDKNitric RuntimeCloud WebSocket Gateway (e.g., AWS API Gateway, GCP WebSocket Gateway)

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 Terraform reference modules:

Edit this page on GitHub
Last updated on Jan 24, 2025