connectanum_client #

connectanum_client is the Dart and Flutter WAMP client package from the Connectanum workspace.

It supports:

• WebSocket and RawSocket transports
• JSON, MessagePack, and CBOR serializers
• ticket, WAMP-CRA, SCRAM, and cryptosign authentication
• progressive RPC and advanced pub/sub features
• optional native RawSocket and native WebSocket transports on Linux and macOS

Status: active development. The API is usable, but the wider project is still settling release and packaging conventions.

Install #

dart pub add connectanum_client

Quick Start #

import 'package:connectanum_client/connectanum.dart';
import 'package:connectanum_client/json.dart';

Future<void> main() async {
  final client = Client(
    realm: 'demo.realm',
    transport: WebSocketTransport(
      'ws://127.0.0.1:8080/ws',
      Serializer(),
      WebSocketSerialization.serializationJson,
    ),
  );

  final session = await client.connect().first;

  final registration = await session.register('demo.ping');
  registration.onInvoke(
    (invocation) => invocation.respondWith(arguments: ['pong']),
  );

  final result = await session.callSingle('demo.ping');
  print(result.arguments?.first);

  await session.close();
  await client.disconnect();
}

More examples live under example/.

For a curated repo-level examples page, see ../../docs/examples.md.

Transport Options #

Use WebSocketTransport for standard WAMP-over-WebSocket and SocketTransport for WAMP-over-RawSocket.

For the native client path on Linux and macOS, use NativeRawSocketTransport or NativeWebSocketTransport. Those transports use the Rust ct_ffi runtime through FFI and are intended for higher-throughput or lower-allocation deployments.

Native Runtime Setup #

During dart run and dart test, the build hook can compile ct_ffi automatically when a Rust toolchain is available.

If you want to use a published prebuilt bundle instead, configure the hook from the application pubspec.yaml:

hooks:
  user_defines:
    connectanum_client:
      CONNECTANUM_NATIVE_RELEASE_TAG: <release-tag>

From a source checkout, you can also prefetch the current host bundle and use the printed path as a CONNECTANUM_NATIVE_LIB hook user define:

dart packages/connectanum_client/tool/install_native.dart --tag <release-tag>

The package also supports:

• CONNECTANUM_NATIVE_LIB Use an already-installed shared library. Paths may be absolute or relative to the application pubspec.
• CONNECTANUM_NATIVE_RELEASE_TAG Let the build hook download a hosted prebuilt bundle.
• CONNECTANUM_NATIVE_RELEASE_REPOSITORY Override the default GitHub Releases source.
• CONNECTANUM_SKIP_NATIVE_BUILD Skip Cargo entirely when your deployment provides ct_ffi itself.

For the complete deployment flow, see the repo-level deployment guide.

Authentication And Advanced Features #

The client supports the current Connectanum feature set for:

• ticket authentication
• WAMP-CRA
• SCRAM
• cryptosign
• progressive call results
• call cancellation (skip, killnowait, kill)
• shared registrations
• pattern-based subscriptions
• payload passthrough mode

CRA and SCRAM authentication strings use UTF-8 by default. For a legacy peer that expects Dart UTF-16 code units, select compatibility mode explicitly on the connecting side; both peers must derive and verify credentials with the same mode:

final cra = CraAuthentication(
  'secret',
  stringEncoding: AuthenticationStringEncoding.utf16,
);
final scram = ScramAuthentication(
  'secret',
  stringEncoding: AuthenticationStringEncoding.utf16,
);

Progressive Results And Cancellation #

Progressive RPC callers should use Session.call(...) with CallOptions(receiveProgress: true) and inspect result.progress:

final stream = session.call(
  'bench.progressive',
  options: CallOptions(receiveProgress: true),
);

await for (final result in stream) {
  if (result.progress) {
    print('partial: ${result.arguments}');
  } else {
    print('final: ${result.arguments}');
  }
}

If the caller may need to stop an in-flight call, pass cancelCompleter (dart:async):

final cancel = Completer<String>();

final stream = session.call(
  'bench.slow',
  cancelCompleter: cancel,
);

cancel.complete(CancelOptions.modeKillNoWait);

Supported cancellation modes today are:

• CancelOptions.modeSkip
• CancelOptions.modeKillNoWait
• CancelOptions.modeKill

modeKill waits for the callee-side cancellation/error acknowledgement. modeKillNoWait interrupts the callee and completes the caller immediately. modeSkip stops waiting locally without interrupting the callee.

Lazy Payload And Native Fast Path #

Use the lazy/payload APIs when you need to keep encoded args / kwargs bytes intact for as long as possible:

• publishLazyPayload(...)
• callSingleLazyPayload(...)
• subscribeLazyPayloadHandler(...)
• registerLazyPayloadHandler(...)

On same-serializer and native direct paths, those APIs keep payload bytes lazy until first access and can avoid allocating full Event / Invocation / Result wrappers. Materialized APIs and mixed-serializer paths may still decode and re-encode payloads when required by the route.

The shared protocol and serializer primitives live in connectanum_core.

Project Context #

This package is part of the main Connectanum monorepo:

• repo overview: ../../README.md
• router package: ../connectanum_router/README.md
• auth server package: ../connectanum_auth_server/README.md