Authentication

KalamDB supports HTTP Basic credentials and JWT bearer tokens. For long-lived apps, prefer JWT + refresh flows.

Auth types

import 'package:kalam_link/kalam_link.dart';
 
Auth.basic('username', 'password'); // HTTP Basic
Auth.jwt('eyJhbGci...');            // JWT bearer token
Auth.none();                         // No auth (localhost bypass)

authProvider — recommended

Use authProvider as the source of credentials. The callback is invoked when the client is created, and you can re-run it with refreshAuth() when your token changes or before an explicit reconnect path:

final client = await KalamClient.connect(
  url: 'https://db.example.com',
  authProvider: () async {
    final token = await myApp.getOrRefreshJwt();
    return Auth.jwt(token);
  },
);

The AuthProvider typedef is:

typedef AuthProvider = Future<Auth> Function();

Provider return guidance

Return Auth.jwt(...) for normal deployments.

The Dart SDK also supports:

• Auth.basic(...) when you want the client to exchange Basic credentials for a JWT before the first query or WebSocket connect
• Auth.none() for local anonymous access

There is no separate auth: parameter on KalamClient.connect(...) in the Dart SDK. Auth flows go through authProvider, login(...), and refreshToken(...).

refreshAuth()

Call refreshAuth() to proactively push fresh credentials to the Rust layer without waiting for the next reconnect — useful for scheduled token rotation:

// Refresh tokens every 55 minutes
Timer.periodic(const Duration(minutes: 55), (_) => client.refreshAuth());

refreshAuth() re-runs the configured authProvider and pushes the refreshed credentials into the Rust client.

disableCompression

Disable gzip compression on WebSocket messages for easier local debugging:

final client = await KalamClient.connect(
  url: 'http://localhost:8080',
  authProvider: () async => Auth.jwt(await getToken()),
  disableCompression: true, // appends ?compress=false to the WS URL
);

The server will respond with plain-text JSON frames instead of compressed binary frames, making inspection in Wireshark or proxy tools straightforward.

Do not use in production. Compression significantly reduces bandwidth. Only enable for local debugging.

Login (Basic → JWT upgrade)

If your server requires an explicit login step, create a temporary client, perform login(), then reconnect with the returned access token:

final bootstrap = await KalamClient.connect(
  url: 'https://db.example.com',
  authProvider: () async => Auth.none(),
);
 
final session = await bootstrap.login('alice', 'Secret123!');
await bootstrap.dispose();
 
final client = await KalamClient.connect(
  url: 'https://db.example.com',
  authProvider: () async => Auth.jwt(session.accessToken),
);

If you return Auth.basic(...) from authProvider, the SDK will also perform the Basic-to-JWT exchange automatically before the first query or WebSocket connection.

Refresh token

If you have a refresh token and want a new access token:

final fresh = await client.refreshToken(refreshToken);
print('new access token: ${fresh.accessToken}');