CasCap.Api.SignalCli 0.10.31

CasCap.Api.SignalCli

A .NET library that wraps the signal-cli REST API (generated against v0.98), providing a typed SignalCliRestClientService for sending and managing Signal encrypted messages, together with a health check and DI registration.

Installation

dotnet add package CasCap.Api.SignalCli

Transport Modes

TransportMode has four values, mirroring the MODE environment variable of the signal-cli REST API server, and must match whatever the server is running. Client-side there are only two behaviours: Normal and Native poll over HTTP, while JsonRpc and JsonRpcNative receive pushed frames over a WebSocket. The performance and memory characteristics below are properties of the server mode, not of this client.

On the WebSocket transports the connection is persistent and reconnects automatically with exponential backoff (2 s → 2 min, up to 10 attempts); every non-receive operation still goes over HTTP via the underlying SignalCliRestClientService. Registration, verification and device-linking endpoints are unavailable while the server runs in either JSON-RPC mode, per upstream documentation.

Receiving Messages

Both transports implement ISignalCliReceiver, so inbound messages are consumed the same way regardless of TransportMode. Switching between HTTP polling and the WebSocket push stream is a configuration change, not a code change.

public sealed class EchoWorker(ISignalCliReceiver receiver, ISignalCliClient client,
    IOptions<SignalCliConfig> options) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var account = options.Value.PhoneNumber;
        await foreach (var msg in receiver.StreamMessagesAsync(stoppingToken))
        {
            var sender = msg.Envelope.Source;
            var text = msg.Envelope.DataMessage?.Message;
            if (sender is null || string.IsNullOrWhiteSpace(text))
                continue;

            await client.SendMessage(new SignalMessageRequest
            {
                Number = account,
                Recipients = [sender],
                Message = $"echo: {text}"
            }, stoppingToken);
        }
    }
}

StreamMessagesAsync is a cold stream: enumeration starts the transport (connecting the WebSocket where applicable) and abandoning the enumerator stops it. Cancelling the token ends the stream by throwing OperationCanceledException, per the usual IAsyncEnumerable convention. Only one active enumeration per instance is expected; concurrent consumers compete for messages rather than each receiving a copy.

Calling ConnectAsync first is optional but surfaces connection failures at startup instead of on the first message. On the REST transport it is a no-op.

Controller

The MVC controller lives in a separate package, CasCap.Api.SignalCli.AspNetCore, so that worker services, console apps and daemons can consume this library without taking a dependency on MVC or API versioning.

Purpose

ISignalCliClient is the abstraction over the full signal-cli REST API surface. Depend on it rather than the concrete SignalCliRestClientService so the client can be substituted with a fake in tests. It resolves to SignalCliRestClientService in every transport mode, since only message reception differs between them.

Every method returns null or false on failure and logs the cause; failures are not thrown. The exception is caller-requested cancellation, which propagates as OperationCanceledException so an abandoned call is never mistaken for an API error.

SignalCliRestClientService is the HttpClient-backed implementation:

General

Messaging

Registration

Accounts

Contacts

Devices

Groups

Identities

Attachments

Profile

Search

Sticker Packs

Configuration

Registered via IServiceCollection.AddSignalCli(). Configuration section: CasCap:SignalCliConfig.

Basic authentication

When the signal-cli REST API sits behind an authenticating reverse proxy, set BasicAuthEnabled and supply Username and Password. The credentials are applied to both the HttpClient and the JSON-RPC WebSocket handshake.

If Username and Password are left unset, the library falls back to CasCap:ApiAuthConfig, which suits hosts that already bind a single set of ingress credentials for every API they call. When neither source yields credentials, registration throws an InvalidOperationException naming both configuration keys rather than failing later with an opaque 401.

Configuration Examples

Minimal

{
  "CasCap": {
    "SignalCliConfig": {
      "BaseAddress": "http://signalcli.monitoring.svc.cluster.local",
      "PhoneNumber": "+49151..."
    }
  }
}

Fully configured

{
  "CasCap": {
    "SignalCliConfig": {
      "TransportMode": "JsonRpc",
      "BaseAddress": "http://signalcli.monitoring.svc.cluster.local",
      "HealthCheckUri": "v1/about",
      "HealthCheck": "Readiness",
      "PhoneNumber": "+49151...",
      "PhoneNumberDebug": "+49151...",
      "SendTimeoutMs": 180000,
      "ChannelCapacity": 256,
      "ReceivePollIntervalMs": 1000,
      "MaxReconnectAttempts": 10,
      "InitialReconnectDelayMs": 2000,
      "MaxReconnectDelayMs": 120000,
      "ReceiveStalenessTimeoutMs": 0
    }
  }
}

Health Check

SignalCliConnectionHealthCheck – Verifies that the signal-cli REST API is reachable by issuing a GET request to {BaseAddress}/{HealthCheckUri}.

Class Hierarchy

classDiagram
    direction LR

    HttpClientBase <|-- SignalCliRestClientService
    HttpEndpointCheckBase <|-- SignalCliConnectionHealthCheck
    ISignalCliClient <|.. SignalCliRestClientService
    ISignalCliReceiver <|.. SignalCliRestClientService
    ISignalCliReceiver <|.. SignalCliJsonRpcClientService
    SignalCliJsonRpcClientService ..> SignalCliRestClientService : delegates

    class ISignalCliClient {
        <<interface>>
        +GetAbout(CancellationToken) SignalAbout?
        +SendMessage(SignalMessageRequest, CancellationToken) SignalMessageResponse?
        +ReceiveMessages(number, CancellationToken) SignalReceivedMessage[]?
        +ListGroups(number, CancellationToken) SignalGroup[]?
        +ListContacts(number, allRecipients, CancellationToken) SignalContact[]?
    }

    class ISignalCliReceiver {
        <<interface>>
        +ConnectAsync(CancellationToken) Task
        +StreamMessagesAsync(CancellationToken) IAsyncEnumerable~SignalReceivedMessage~
    }

    class SignalCliRestClientService {
        -SignalCliConfig _config
        +GetAbout() SignalAbout?
        +SendMessage(SignalMessageRequest) SignalMessageResponse?
        +ReceiveMessages(number) SignalReceivedMessage[]?
        +ListAccounts() string[]?
        +ListGroups(number) SignalGroup[]?
        +ListContacts(number) SignalContact[]?
        +ListIdentities(number) SignalIdentity[]?
        +ListLinkedDevices(number) SignalDevice[]?
        +ListAttachments() string[]?
        +ListStickerPacks(number) SignalStickerPack[]?
        +SearchNumbers(number, numbers) SearchResult[]?
        -GetAsync~T~(requestUri) T?
        -PostAsync~T~(requestUri, body) T?
        -PostBoolAsync(requestUri, body) bool
        -PutAsync(requestUri, body) bool
        -DeleteAsync(requestUri, body) bool
        -DeleteAsync~T~(requestUri, body) T?
    }

    class SignalCliJsonRpcClientService {
        -SignalCliRestClientService _restClient
        -ClientWebSocket? _webSocket
        +ConnectAsync(CancellationToken) Task
        +StreamMessagesAsync(CancellationToken) IAsyncEnumerable~SignalReceivedMessage~
        -ReceiveLoopWithReconnectAsync(CancellationToken) Task
        +BuildWebSocketUri(baseAddress, phoneNumber)$ Uri
    }

    class SignalCliConnectionHealthCheck {
        +Name$ string
    }

    class SignalCliConfig {
        +TransportMode SignalCliTransport
        +BaseAddress string
        +HealthCheckUri string
        +HealthCheck KubernetesProbeTypes
        +SendTimeoutMs int
        +PhoneNumber string
        +PhoneNumberDebug string?
        +ChannelCapacity int
        +ReceivePollIntervalMs int
        +MaxReconnectAttempts int
        +InitialReconnectDelayMs int
        +MaxReconnectDelayMs int
        +BasicAuthEnabled bool
        +Username string?
        +Password string?
    }

    SignalCliRestClientService ..> SignalCliConfig : reads
    SignalCliJsonRpcClientService ..> SignalCliConfig : reads
    SignalCliConnectionHealthCheck ..> SignalCliConfig : reads

DI Registration Flow

flowchart LR
    A["AddSignalCli()"] --> B["Bind SignalCliConfig"]
    A --> C["Register HttpClient"]
    A --> J["ISignalCliClient \u2192 SignalCliRestClientService"]
    A --> D{"TransportMode?"}
    A --> E["Register SignalCliConnectionHealthCheck"]
    D -->|Normal / Native| F["INotifier + ISignalCliReceiver \u2192 SignalCliRestClientService"]
    D -->|JsonRpc / JsonRpcNative| G["INotifier + ISignalCliReceiver \u2192 SignalCliJsonRpcClientService"]
    G --> H["delegates non-receive ops"]
    H --> F2["SignalCliRestClientService"]
    C --> I["IHttpClientFactory"]
    I --> F
    I --> G
    I --> E

Dependencies

NuGet packages

Project references

License

This project is released under The Unlicense. See the LICENSE file for details.