ewox-service-fastapi

WebSockets

ServiceApp can expose a typed WebSocket route backed by a pluggable session manager. The default manager stores live sessions in the current process.

from ewoxcore.constants.server_env import ServerEnv
from ewoxservicefastapi.service_app import ServiceApp
from ewoxservicefastapi.websocket.websocket_settings import WebSocketSettings


class APIServer(ServiceApp):
    def __init__(self) -> None:
        super().__init__(service_name="api")

        settings = WebSocketSettings(
            environment=ServerEnv.LOCALHOST,
            public_host="localhost",
            public_port=8804,
            allowed_origins=["http://localhost:3000"],
        )
        self.addWebSocket(settings)

The public URL is ws://localhost:8804/ws for the localhost environment. All other environments return a client-facing wss:// URL. Cloudflare terminates TLS and proxies the WebSocket upgrade to Uvicorn over the private origin connection, so the service does not load or configure SSL certificate files. WebSocket transport settings are code-owned and are not read from .env.

An external package can replace the in-memory manager by implementing IWebSocketSessionManager and passing a factory:

self.addWebSocket(
    settings,
    session_manager_factory=lambda websocket_settings: ExternalSessionManager(
        websocket_settings
    ),
)

The package has no Redis dependency. A Redis-backed implementation can live in another package and use this factory boundary for distributed registry and message coordination while keeping live socket objects in each API process.

Container scaling

ServiceApp starts one Uvicorn process per container and does not configure Uvicorn's multi-worker mode. Production capacity is increased by running more containers behind Cloudflare and the platform load balancer.

The default in-memory manager is intended for local development or a single-container deployment. A multi-container deployment must provide an external IWebSocketSessionManager implementation. The external manager must keep each live WebSocket object inside its owning container and use its distributed transport to route direct messages and broadcasts to the correct container. A shared registry alone is not sufficient.

Transport models are serialized with JsonUtil. Application event models should use @Serializable and be registered once through ClassRegistry.

Durable delivery protocol

Distributed adapters can use WebSocketDeliveryModel[TData] to mark a server message as requiring client acknowledgement:

delivery = WebSocketDeliveryModel[WebSocketEventModel](
    delivery_id=delivery_id,
    data=event,
)
await session.send_model(delivery)

The serialized message has type="delivery", a stable deliveryId, and typed data. After processing it, the client returns a WebSocketAcknowledgementModel with type="ack" and the same deliveryId. The external session manager decides when that acknowledgement removes its durable entry. The framework package does not assume Redis or acknowledge a delivery merely because send_text(...) completed.

Metadata

Release files for ewoxservicefastapi 1.7.29

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ewoxservicefastapi 1.7.29
File	Size	Uploaded
ewoxservicefastapi-1.7.29.tar.gz	22.9 kB	Oct 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ewoxservicefastapi 1.7.29
File	Interpreter	ABI	Platform	Reset
ewoxservicefastapi-1.7.29-py3-none-any.whl 43.4 kB Oct 8, 2026	Python 3	none	any	Details

Total release size: 66.3 kB

Release files / ewoxservicefastapi-1.7.29.tar.gz

Download URL	ewoxservicefastapi-1.7.29.tar.gz
Size	22.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`c6817f4a7a5cd14abc565b28382a16a15915d261a2ecac37c28b5f39af2a020b`
BLAKE2b-256 checksum How to use checksums	`28d57488ba2be450f97d6a3d84bbd745b7222d1211e7e8cc0494628eed144c02`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.3`

Release files / ewoxservicefastapi-1.7.29-py3-none-any.whl

Download URL	ewoxservicefastapi-1.7.29-py3-none-any.whl
Size	43.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`16d4ed543cb14d0120c5ca0d2cad8525fddfcd0fe244e34b12d6be1bf7f1c091`
BLAKE2b-256 checksum How to use checksums	`acc7a15b08dd1554823dedfbb4e10ccd846a769566ea0b51b7d5bafee8c38ede`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.3`