Cocoar.SignalARRR.ProxyGenerator 5.0.0-beta.3

SignalARRR

Typed bidirectional RPC over ASP.NET Core SignalR.

Server and client call each other's methods through shared interfaces — with compile-time proxy generation, streaming, cancellation propagation, and ASP.NET Core authorization. Clients available for .NET, TypeScript/JavaScript, and Swift.

Read the full documentation

Upgrading from 4.x? v5 carries breaking changes from a full code review. Most need nothing from you; what does is in the migration guide, grouped by whether it is likely to affect you at all.

Packages

.NET

TypeScript / JavaScript

npm install @cocoar/signalarrr

Swift (iOS / macOS)

.package(url: "https://github.com/cocoar-dev/Cocoar.SignalARRR.git", from: "5.0.0")

Quick Start

Define shared interfaces, set up the server, and call methods with full type safety:

// Shared interface
[SignalARRRContract]
public interface IChatHub {
    Task SendMessage(string user, string message);
    Task<List<string>> GetHistory();
}

// Client usage — one line to get a typed proxy
var chat = connection.GetTypedMethods<IChatHub>();
await chat.SendMessage("Alice", "Hello!");

// TypeScript client
const history = await connection.invoke<string[]>('ChatMethods.GetHistory');

// Swift client — @HubProxy macro generates the proxy
@HubProxy protocol IChatHub { ... }
let chat = connection.getTypedMethods(IChatHubProxy.self)

For full setup guides, streaming, authorization, and server-to-client calls, see the documentation.

Features

• Typed bidirectional RPC — server and client call each other through shared interfaces
• Compile-time proxy generation — Roslyn source generator (zero reflection)
• Organized hub methods — split logic across ServerMethods<T> classes with full DI
• Streaming — IAsyncEnumerable<T>, IObservable<T>, ChannelReader<T> in both directions
• HTTP stream references — file download/upload through SignalR hub methods
• CancellationToken propagation — server can cancel client operations remotely
• Authorization — method-level, class-level, and hub-level [Authorize]
• Server-to-client calls from anywhere — inject ClientManager in controllers, background services, etc.
• Four clients — .NET, .NET Framework, TypeScript/JavaScript, Swift
• Typed broadcasts — WithHub<T>().WithGroup().SendAsync<T>() for groups and filtered clients
• Redis-compatible multi-node backplane — opt-in scale-out with Redis, Valkey, or Garnet

Redis-compatible backplane

SignalARRR stays pure in-memory by default. If you do not configure a backplane, behavior remains single-node and process-local exactly as before.

For multi-node scale-out, add the Cocoar.SignalARRR.Server.Backplane.Redis package and opt in. It is a separate package as of 5.0, so single-node applications do not carry StackExchange.Redis:

builder.Services.AddSignalARRR(b =>
    b.AddServerMethodsFrom(typeof(ChatHub).Assembly));

builder.Services.AddSignalARRRRedisBackplane(options => options
    .WithConnectionString("localhost:6379,abortConnect=false")
    .WithChannelPrefix("my-app")
    .WithNodeId($"{Environment.MachineName}-api-1"));

This works with Redis, Valkey, and Garnet because SignalARRR talks to a Redis-compatible backend via StackExchange.Redis.

What becomes cluster-aware

• GetTypedMethods<T>(connectionId) send/invoke across nodes
• WithHub<T>().SendAsync(...) across all nodes
• WithGroup(...), WithUser(...), and WithAttribute(...) across nodes
• InvokeAllAsync(...) and InvokeOneAsync(...) across nodes
• AddToGroupAsync(...) / RemoveFromGroupAsync(...) for remote connections
• Presence APIs on ClientManager:
  • GetConnectionsAsync<THub>()
  • GetConnectionsByUserAsync<THub>(...)
  • GetConnectionsInGroupAsync<THub>(...)
  • GetConnectionsByAttributeAsync<THub>(...)
  • GetOnlineUsersAsync<THub>()
  • IsUserOnlineAsync<THub>(...)

Cluster semantics

• Transient transport: the backplane distributes live messages; it is not a durable queue or event store.
• Eventual convergence: connection, group, user, and attribute metadata propagate quickly, but not atomically across all nodes. Right after connect/disconnect/group changes there can be a short convergence window.
• Crash cleanup: dead nodes are removed by heartbeat + timeout sweep. Tune WithHeartbeatInterval(...) and WithNodeTimeout(...) if you want faster stale-node cleanup.
• Safe fallback: without AddSignalARRRRedisBackplane(...), all APIs continue to use the old in-memory single-node path.

Connection loss semantics

What happens to in-flight work when a connection drops — worth knowing before you rely on it:

• Pending invocations fail immediately, and are not safely retryable. When the connection drops, every outstanding invoke fails right away — a 50 ms blip is no different from a long outage. After reconnecting it is a new connection with a new ConnectionId; the lost answer is gone for good. And if the drop happened after the server executed but before the response arrived, the caller cannot know whether the call took effect — retry only operations that are idempotent.
• SignalR's resilience features are available, but pass-through. MapSignalARRRHub<THub>(...) returns SignalR's HubEndpointConventionBuilder (so AllowStatefulReconnects() can be applied), and HARRRConnection.Create(...) hands you the real HubConnectionBuilder (so WithAutomaticReconnect() / WithStatefulReconnect() work as documented by SignalR). SignalARRR does not interfere with either: its own lifetime signals hang off SignalR's, which Stateful Reconnect extends. Under Stateful Reconnect the connection is resumed rather than replaced, keeping its ConnectionId, and SignalARRR's ClientManager registration — including group membership — comes through intact; there is an integration test for exactly that, severing the transport underneath a live connection. Note that a resume raises no Reconnecting/Reconnected events: the connection never counts as lost. Two pieces of connection-bound state are not covered by that test and remain unverified: an in-flight stream's ownership, and an outstanding upload slot. WithAutomaticReconnect() on its own always yields a new ConnectionId, so nothing connection-bound carries over there, by design.
• A fire-and-forget call to a client cannot report failure. For a contract member returning void or Task, the server's send completes when the message reaches the transport — before the client runs the method. If the handler then throws, the error is logged on the client and nowhere else; the server saw a successful send. Members returning Task<T> or T do surface client-side failures, as a HubException. Give a member a return value when the server needs to know it worked.
• Two deadlines run independently of connection state. The stream upload wait (StreamUploadTimeout, default 2 minutes) and the backplane invoke timeout (WithInvokeTimeout(...), default 15 seconds) keep ticking while a reconnect is bridging a gap — a long enough outage fails them even though the connection technically survives. Both are configurable; size them with reconnect windows in mind.

Framework Support

Building from Source

# .NET
dotnet build src/Cocoar.SignalARRR.slnx
dotnet test src/Cocoar.SignalARRR.slnx

# TypeScript
cd src/Cocoar.SignalARRR.Typescript && npm install && npm run build

# Swift
swift build && swift test

License

Apache License 2.0 — see LICENSE for details.

Contributing

See CONTRIBUTING.md for guidelines.