WebExpress 0.0.10‑alpha – Selective WebSocket Broadcasts

WebSockets are among the most versatile tools for building modern web applications that operate in a reactive, responsive and bidirectional manner. As soon as multiple clients are connected simultaneously, a challenge emerges that many frameworks underestimate. The server processes numerous parallel connections and requires the ability to target only those clients that meet specific criteria. A global broadcast is unsuitable for this purpose because it reaches all clients equally, regardless of whether the message is relevant to them.

In this scenario, clients transmit meta information when registering their WebSocket connection. This includes the current URI, the tenant, the language or other contextual data. The server uses this information to send messages not to all connected clients, but selectively and based on context.

A WebSocket is initially only a bidirectional connection without any knowledge of the context in which it is used. In modern applications, however, this context plays a central role. One client may be located on the route /dashboard, another works in the area /editor/42, another belongs to the tenant ACME and another uses an administrative interface. The server must understand these differences to communicate in a targeted manner.

The foundation for this selective communication is a WebSocket registry implemented in the MessageQueueManager. This registry acts as a compact in‑memory database that manages all active connections. It stores the WebSocket instance, a unique session ID and a dictionary containing the transmitted metadata, such as an entry like uri: /dashboard. This creates a structured collection of sessions that can be efficiently searched at any time to identify the appropriate clients.

The registration of metadata takes place immediately during connection establishment. The client sends an HTTP request containing the relevant information. The server reads this data, extracts the metadata and stores it in the registry. From this moment on, the full context of the connection is available.

WebExpress relies on type‑safe models and clear communication between server and client. To apply this principle consistently within WebSocket processing, the MessageQueueManager provides a send method that processes structured messages and enables precise addressing. The send method supports generic message types and forms the basis for different routing scenarios.

To implement this selectivity in a fully type‑safe manner, WebExpress uses a structured addressing model. Addressing is performed through clearly defined address objects that explicitly describe which client connection is used as the target. The MessageQueueManager centrally checks whether a client connection matches a specific address object and is therefore eligible as a recipient. Predefined address objects are available for common scenarios and can be extended as needed, forming a clear foundation for consistent routing.

An address object follows a shared abstract base:

public interface IAddress 

{ 

  bool Matches(IClientSession session); 

}

For common scenarios, concrete addressing types are available. Addressing by URI, for example, looks like this:

public sealed class UriAddress : IAddress 

{ 

  public string Uri { get; } 

  public UriAddress(string uri) 

  { 

    Uri = uri; 

  } 

  public bool Matches(IClientSession session) 

  { 

    return session.Meta.TryGetValue("uri", out var value) 

      && value == Uri; 

  } 

}

Based on this structure, a type‑safe send method emerges that processes structured messages and enables precise addressing:

public async Task SendAsync(IMessage message, IAddress address, CancellationToken cancellationToken = default) 

{ 

  // Serialization, selection of matching sessions and dispatch 

}

The architecture remains clearly structured. The message is a type‑safe model, the addressing is performed through a defined object and the MessageQueueManager handles the central evaluation. Communication remains traceable, extendable and consistent.

It provides room for further optimization and extension. Additional addressing types, more complex routing combinations or alternative strategies for selecting target connections build directly on the existing model. The structure supports continuous development and forms a stable basis for new requirements arising from real‑world projects.

WebExpress benefits from active participation within the developer community. Every idea for additional addressing mechanisms, improvements to the MessageQueueManager or alternative communication patterns strengthens the framework and expands its capabilities. The open architecture encourages the contribution of new concepts and supports a shared focus on a powerful, modern and type‑safe communication layer.