CasCap.Api.SignalCli 0.12.0

CasCap.Api.SignalCli

A .NET 10/11 client for sending, receiving and managing Signal messages through the signal-cli REST API. It provides typed REST operations, HTTP or WebSocket reception, health checks and dependency-injection registration.

Installation

dotnet package add CasCap.Api.SignalCli

Usage

In a Generic Host application, register the client against the host's configuration:

using CasCap.Abstractions;
using CasCap.Extensions;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddSignalCli(builder.Configuration);

using var host = builder.Build();
var client = host.Services.GetRequiredService<ISignalCliClient>();
var about = await client.GetAbout();
Console.WriteLine(about is null ? "API unavailable" : "API reachable");

Supply BaseAddress and the registered account's PhoneNumber as shown in Configuration Examples. The consuming application supplies logging, configuration providers and any telemetry exporters.

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.

using CasCap.Abstractions;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public sealed class ReceiveWorker(
    ISignalCliReceiver receiver,
    ILogger<ReceiveWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var message in receiver.StreamMessagesAsync(stoppingToken))
        {
            logger.LogInformation("Received envelope with data message: {HasDataMessage}",
                message.Envelope.DataMessage is not null);
        }
    }
}

Register the worker with builder.Services.AddHostedService<ReceiveWorker>() before building the host, then run it with await host.RunAsync(). This example consumes messages without sending a reply or logging their contents or sender identities.

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.

Observability

The library emits provider-neutral diagnostics and does not choose or configure an exporter. A consuming host registers the stable CasCap.Api.SignalCli meter and activity source alongside its configurable application meter. The library source name is deliberately fixed so dashboards and instrumentation registration do not vary between hosts. Count-like instruments use the UCUM unit 1.

The only dimensions are bounded phase/outcome values. Account numbers, endpoints, sender identities, and message content are never emitted as metric labels or trace attributes.

SendMessage diagnostics report acknowledgement or failure category without message text, recipient identifiers, response bodies or exception details. Hosts should also avoid HTTP body logging. A failed or cancelled send does not prove that the recipient received nothing; do not automatically repeat a send whose outcome is uncertain.

Controller

The MVC controller lives in a separate CasCap.Api.SignalCli.AspNetCore package. Worker services and console applications need not depend on MVC or API versioning.

API

Depend on ISignalCliClient rather than the concrete SignalCliRestClientService so the client can be substituted in tests. It resolves to SignalCliRestClientService in every transport mode; only message reception differs. The tables below summarize common operations; the interface provides the complete signatures, including poll and account-settings operations.

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.

Logs name only the failed operation and exception, never the request URI, account or recipient numbers, group names or identifiers, or server error bodies. Successful group and poll creation logs at Debug. Repeated receive polling logs the first failure as a Warning, later consecutive failures at Debug and one Information line on recovery. On the WebSocket transports the first retry of an outage is a Warning, further retries are Debug, a reconnection logs one Information line with the attempt count, and exhausting the attempts logs one Error. The initial connection logs only its first failure; when its attempts are exhausted the final exception propagates to the caller without an additional log.

SignalCliRestClientService is the HttpClient-backed implementation:

General

Messaging

Registration

Accounts

Contacts

Devices

Groups

Identities

Attachments

Profile

Search

Sticker Packs

Group Identifiers

Signal groups expose two opaque identifier forms. SignalGroup.Id is the group.-prefixed value required in SignalMessageRequest.Recipients when sending. SignalGroup.InternalId is the unprefixed value carried by inbound IReceivedNotification.GroupId; it cannot be derived by removing the prefix from Id. Use SignalGroup.Matches(groupId) when matching an identifier whose source is not known.

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 either credential is missing, resolution falls back to a registered IOptions<ApiAuthConfig> containing both values. Bind CasCap:ApiAuthConfig in the host when using that shared configuration; AddSignalCli does not bind it for you. If neither source has a complete pair, resolving the HTTP client or WebSocket transport throws InvalidOperationException. Use TLS outside trusted local development and store credentials in a secret-backed configuration provider.

Configuration Examples

Minimal

{
  "CasCap": {
    "SignalCliConfig": {
      "BaseAddress": "http://localhost:8080",
      "PhoneNumber": "+10000000000"
    }
  }
}

The account is synthetic; replace it through a secret-backed provider.

Receive and health-check settings

{
  "CasCap": {
    "SignalCliConfig": {
      "TransportMode": "JsonRpc",
      "BaseAddress": "http://localhost:8080",
      "HealthCheckUri": "v1/about",
      "HealthCheckExpectedHttpStatusCodes": [200, 204],
      "HealthCheck": "Readiness",
      "PhoneNumber": "+10000000000",
      "PhoneNumberDebug": "+10000000000",
      "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}.

Resilience

SignalCliRestClientService uses the standard resilience pipeline for REST calls. Health checks use a separate named HttpClient with retries disabled: a probe is a point-in-time result, and the orchestrator already repeats it on its own schedule.

Idempotent methods can be retried. POST and PATCH are retried only for failures indicating the request was not transmitted, not timeouts or server errors. In particular, a failed send may already have reached its recipient; do not blindly repeat it. SendTimeoutMs also sizes the REST client's resilience attempt and total timeout budgets.

Components

All modes use HTTP for sends and management. Only the receive transport changes:

flowchart LR
    Host["Consuming host"] --> Client["ISignalCliClient"]
    Client --> HTTP["REST client"]
    HTTP --> Server["signal-cli REST API"]
    Host --> Receiver["ISignalCliReceiver"]
    Receiver --> Mode{"TransportMode"}
    Mode -->|Normal or Native| Poll["HTTP polling"]
    Mode -->|JsonRpc or JsonRpcNative| WebSocket["Persistent WebSocket"]
    Poll --> Server
    WebSocket --> Server

License

Released under the MIT License.