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 instead of a static auth value. The callback is invoked before every (re-)connection, so tokens are always fresh without any extra wiring:

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 real deployments.

Avoid returning Auth.basic(...) from authProvider — Basic auth is intended for the one-time login() upgrade flow.

Why authProvider?

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() has no effect when no authProvider is set.

Static auth — deprecated

Deprecated. The auth parameter is deprecated in favour of authProvider. Static credentials cannot refresh automatically; tokens will expire mid-session on reconnect. It continues to work but the dartdoc marks it as deprecated.

// ⚠️ Deprecated
final client = await KalamClient.connect(
  url: 'https://db.example.com',
  auth: Auth.jwt(token),  // token will go stale after expiry
);

Migrate by wrapping in authProvider:

// ✅ Preferred
final client = await KalamClient.connect(
  url: 'https://db.example.com',
  authProvider: () async => Auth.jwt(await getToken()),
);

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, use KalamClient.connect with Auth.basic (deprecated) and call login() once:

final client = await KalamClient.connect(
  url: 'https://db.example.com',
  auth: Auth.basic('alice', 'Secret123!'), // ⚠️ deprecated parameter
);
 
final session = await client.login('alice', 'Secret123!');
print(session.accessToken);
 
// Then switch to authProvider on next connect

For new code, prefer obtaining a JWT from your auth service and passing it directly through authProvider.

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}');