CasCap.Comms 1.3.0

CasCap.Comms

The Signalizr communications pipeline shared by applications that talk to Signal Messenger through a signalizr gateway. It combines Redis event delivery, inbound messages, optional voice processing and a bounded reply queue for .NET 10/11 hosts.

Installation and Host Setup

dotnet add package CasCap.Comms

Register the pipeline in a host that already supplies configuration, logging and TimeProvider:

using Microsoft.Extensions.DependencyInjection;

services.AddCasCapCaching(configuration);
services.AddComms(configuration);

AddComms registers an IBgFeature, not an independently started hosted service. Your host must run that feature through its feature dispatcher. The signalizr host is a concrete integration, with an additional AI responder; it is not the library's default behavior. AddComms(configuration, lite: true) registers dependencies without the background feature.

Redis is required for stream/media storage and inbound duplicate suppression. An existing gateway must serve your configured groups. Voice modes remain disabled until you configure their providers. The Release dependency graph uses Common 5.2.0 and Voice 0.3.0; its Signalizr client remains aligned with this package's repository version.

For producer-only processes, register AddCommsStreamSink() instead of starting a consumer. Resolve IEventSink<CommsEvent> and write a notification:

using CasCap.Common.Abstractions;

await sink.WriteEvent(new CommsEvent
{
    Source = "ExampleJob",
    Message = "Scheduled task completed",
    Environment = "Development",
    TimestampUtc = DateTime.UtcNow
}, cancellationToken);

The producer must also register caching, a clock and its host environment. AddTrackedOperations() adds the stream sink and a hosted progress/timeout reporter for ITrackedOperationService.

Purpose

CommunicationsBgService is the single component of an application that talks to Signal. It:

• consumes CommsEvent entries that any pod writes to a Redis Stream, applying flood protection (a token-bucket rate limit and a stale-event cut-off, both announced by a drop notice);
• routes each event to the chat group or an operator-only monitor group, attaching media cached in Redis;
• subscribes to inbound group messages, suppresses redeliveries, acknowledges them with reactions, and transcribes voice notes;
• answers through an optional ICommsResponder via a bounded reply queue, with typing indicators and optional spoken replies.

Without an available responder, chat-bound events are formatted and sent directly and inbound messages are ignored, recorded at Debug by length and attachment count only. With StreamEventTurnsEnabled set to false, chat-bound events are sent directly even when a responder answers inbound messages; DirectDeliverySources does the same for selected event sources only. CasCap.Comms.AI provides the AI agent responder.

Event Flow

flowchart LR
    PRODUCER(["Event producers"]) --> REDIS[("Redis stream and media")]
    REDIS --> ROUTE["Filter, throttle and route"]
    ROUTE --> DIRECT["Direct chat or monitor send"]
    ROUTE --> TURN["Optional responder turn"]
    INBOUND(["Gateway subscription"]) --> DEDUP["Group filter and duplicate suppression"]
    DEDUP --> TURN
    TURN --> REPLY["Bounded reply queue"]
    REPLY --> GATEWAY(["Signalizr REST"])
    DIRECT --> GATEWAY
    classDef storage fill:#fef3c7,stroke:#d97706,color:#78350f
    class REDIS storage

Public Surface

ICommsEventFormatter, ICommsGroupRouter, CommsEvent and MediaReference live in CasCap.Common.Abstractions. Register a formatter, router or deduplicator before AddComms to replace the default.

Configuration

CommsConfig binds from CasCap:CommsConfig. Group names must match the gateway's configured groups exactly, including spaces and case.

Configuration Examples

Minimal pipeline settings for a local gateway, with stream consumption disabled. Supply a Redis connection through CasCap:CachingConfig:RemoteCacheConnectionString:

{
  "CasCap": {
    "CommsConfig": {
      "GroupName": "My Test Group Name",
      "StreamConsumptionEnabled": false
    },
    "SignalizrClientConfig": {
      "BaseAddress": "http://localhost:8080",
      "GrpcAddress": "http://localhost:5001",
      "SubscriberName": "example-comms"
    }
  }
}

With an operator monitor group and operational sources:

{
  "CasCap": {
    "CommsConfig": {
      "GroupName": "My Test Group Name",
      "MonitorGroupName": "My Test Monitor Group Name",
      "StreamConsumptionEnabled": true,
      "MonitorSources": ["ExampleJob"],
      "DirectDeliverySources": ["ExampleNotification"],
      "StreamSendRatePerMinute": 20,
      "ReplyQueueCapacity": 100
    }
  }
}

Monitor messages persist in Signal history on every member device. Enable MonitorContentEnabled or EchoTranscriptToDebugChat only while diagnosing a problem. The monitor group should contain only the operator. Stream throttling drops excess events and stale events; it is not durable guaranteed delivery of every producer notification. Inbound cursor acknowledgements and Redis duplicate suppression are separate mechanisms.

AddComms also registers CasCap:CommsMetricsConfig, CasCap:SignalizrClientConfig, CasCap:SpeechToTextConfig and CasCap:TextToSpeechConfig; voice processing does no work until its Mode enables it.

Dependencies

For deterministic consumer fixtures, see the Comms test guide.