WS

WS (atlas.ws) is the package responsible for providing a unified, environment-agnostic abstraction over WebSocket operations within Atlas applications.

It centralizes all WebSocket-related infrastructure concerns — such as message delivery, connection lifecycle management, and environment detection — allowing application and domain code to remain clean, declarative, and free from platform-specific logic.

The package is designed to work transparently across:

• Local debug environments, using an in-memory WebSocket manager.
• AWS deployments, using the ApiGatewayManagementApi.

By delegating these responsibilities to atlas.ws, Atlas ensures consistent WebSocket behavior across environments while preventing duplication and conditional logic scattered throughout the codebase.

Below are the descriptions of the classes provided by this package.

WSGateway

Unified WebSocket utility layer for Atlas.

This class provides a single, environment-agnostic API for common WebSocket operations such as sending messages and disconnecting clients.

It transparently routes operations to

• A local in-memory WebSocket manager during local development, or
• AWS ApiGatewayManagementApi in deployed environments.

This abstraction prevents environment-specific logic from leaking into application code or WebSocket action handlers.

disconnect(request_ctx) staticmethod

Terminates a WebSocket connection.

This method schedules an asynchronous disconnection request that will either close the local WebSocket connection (debug mode) or instruct AWS API Gateway to delete the connection in production.

It is safe to call multiple times and ignores errors related to already-terminated connections.

Parameters:

Name	Type	Description	Default
request_ctx	dict	A WebSocket request context dictionary. Only the following entries are read: - connectionId (str): The unique identifier of the WebSocket connection. - domainName (str): The WebSocket API domain name, used to determine whether the execution is local or remote.	required

resolve_ws_domain_name(request_ctx) staticmethod

Resolves the WebSocket management endpoint to be used when sending messages to connected clients.

This method abstracts the differences between execution contexts (local debug, WebSocket Lambda, and REST Lambdas) and returns the appropriate domain name for message delivery.

Resolution rules

• If running in the local debug environment, the domainName from the request context is returned, since domains are irrelevant for WS local execution environment.
• If the invocation originates from a WebSocket route (presence of routeKey in the request context), the domainName from the request context is returned.
• Otherwise (e.g. REST endpoints, background jobs, or async workflows), the WebSocket management endpoint is read from the WS_MANAGEMENT_ENDPOINT environment variable.

The value returned by this method must NOT include a protocol prefix (e.g. "wss://" or "https://"), as it will be injected into the ApiGatewayManagementApi client as: https://{resolved_domain}

Parameters:

Name	Type	Description	Default
request_ctx	dict	The request context associated with the current	required

Returns:

Type	Description
str	str | None: The resolved WebSocket management domain name, or None
str	if no valid endpoint could be determined.

send(payload, request_ctx) staticmethod

Sends a message to a WebSocket client.

This method can be safely invoked from synchronous code. The message is dispatched asynchronously and routed to the appropriate backend based on the execution context (local debug or AWS).

Message delivery failures caused by closed or stale connections are silently ignored.

Parameters:

Name	Type	Description	Default
payload	dict	The JSON-serializable message payload to be sent to the WebSocket client.	required
request_ctx	dict	A WebSocket request context dictionary. Only the following entries are read: - connectionId (str): The unique identifier of the WebSocket connection. - domainName (str): The WebSocket API domain name, used to resolve the API Gateway management endpoint and to detect whether the execution environment is local or remote.	required