From connection to application.

lily_websocket lets you build WebSocket applications with namespaces and typed actions. These guides access the published component through the lilyrs facade's websocket feature and lilyrs::websocket imports. The shared DI container creates services; the application manages startup, connection admission, message-processing scopes, and shutdown.

Three levels of ownership#

An application accepts many connections. Each connection carries many messages. These three levels have different lifetimes:

WsApp
  → Controllers and shared services
  → WebSocket connection: namespace, identity, room memberships
      → Message: DI scope, middleware, guard, action, result
      → Next message: new scope and identity snapshot

A controller is created once per application. Identity data retained for the connection is an owned snapshot. Scoped services are resolved afresh for each message and cleaned up when processing completes. Cloning an Arc does not change this resource ownership.

What can you build?#

This guide distinguishes the framework's built-in mechanisms from services your application provides. For example, Lily runs identity middleware; your verifier service performs JWT or session verification. A Redis backplane carries live broadcasts; persistent message history and an offline inbox require a separate data model.

Follow the guide#

Start by running the first application and connecting from the browser. Then read the lifecycle and DI pages to learn who manages each resource. After connection admission and the message protocol, continue to middleware, guards, and broadcasting examples.

The shared foundation with HTTP is lily_injection, lily_injectable_derive, and lily_injection_registry. Do not equate an HTTP request scope with the lifetime of a WebSocket connection: WebSocket handshakes, individual messages, and lifecycle hooks use separate scopes.

Protocol and scope#

The default transport is HTTP/1.1 Upgrade with the Lily v2 envelope. A raw WebSocket client cannot simply send { "text": "merhaba" }; the envelope must specify the message's route and content type.

Binary content is supported. Multipart uploads, file storage, resumable transfers, and SSE are not built-in surfaces of this server; use the relevant HTTP guides or your own application protocol. AsyncAPI support in this version is limited to metadata registration. See the reference for the source revision, defaults, and differences from older documents.