FlintClient Guide

Retry and Cache

final client = FlintClient(
  baseUrl: 'https://api.example.com',
  defaultRetryConfig: RetryConfig(
    maxAttempts: 3,
    delay: const Duration(milliseconds: 250),
    maxRetryTime: const Duration(seconds: 2),
    honorRetryAfter: true,
  ),
  defaultCacheConfig: const CacheConfig(maxAge: Duration(minutes: 2)),
);

Cancellation

Cancellation means stopping a request before it finishes. Use it when user leaves a page, presses cancel, or the response is no longer needed.

final token = CancelToken();
final pending = client.get<String>('/reports/slow', cancelToken: token);

token.cancel('user aborted');
final response = await pending;
if (response.isError) {
  print(response.error?.kind); // FlintErrorKind.cancelled
}

What Is Cancellation? Why and When?

Cancellation means stopping an API request before it finishes.

Why use it?

• User leaves page/screen.
• User changes search/filter quickly.
• Request is slow and no longer needed.
• Prevents old responses from overwriting new UI data.

When to use it?

• Live search/autocomplete
• Navigation between pages
• Long exports/downloads
• Rapid repeated requests

client.request() Explained

client.request() is the generic request method. get/post/put/patch/delete are convenience shortcuts.

Use request() when:

• HTTP method is dynamic at runtime.
• You want one reusable request function.
• You want full control via RequestOptions.

final response = await client.request<Map<String, dynamic>>(
  'POST',
  '/users',
  options: RequestOptions<Map<String, dynamic>>(
    body: {'name': 'Ada'},
    headers: {'Content-Type': 'application/json'},
    parseMode: ResponseParseMode.lenient,
    cancelToken: CancelToken(),
  ),
);

Quick model: get() is quick shortcut, request() is full-control entrypoint.

WebSocket vs Socket.IO (Important)

FlintClient supports WebSocket only. It can look like Socket.IO style because it uses event-style emit/on writing, but it does not implement Socket.IO protocol.

With FlintDart, you can create a simple “glue” convention: event names + JSON payload format, so it feels Socket.IO-like while staying pure WebSocket.

final ws = client.ws('/chat');
await ws.connect();

ws.on('message', (data) => print(data));
ws.emit('message', {'text': 'Hello from client'});

WebSocket Auth (Client Examples)

You can authenticate WebSocket connections in 3 common ways: Bearer header, query token, or app-level auth event.

final client = FlintClient(
  baseUrl: 'http://localhost:8080',
  headers: {'Authorization': 'Bearer your-token'},
);

final ws = client.ws('/ws');
await ws.connect();

final ws = FlintWebSocketClient(
  'ws://localhost:8080/ws',
  sendTokenAsQuery: true,
  queryTokenKey: 'token',
  tokenProvider: () async => await loadTokenFromStorage(),
);

await ws.connect();

final ws = FlintWebSocketClient(
  'ws://localhost:8080/ws',
  autoAuthEvent: true,
  authEventName: 'auth',
  authPayload: {'token': 'your-token'},
);

await ws.connect();

Run the WebSocket Auth Example

For a full runnable demo (header auth + query auth + auth event), use:

dart run example/lib/websocket_auth_example.dart

Keep tests in test/ and usage examples in example/lib/.

Full WebSocket Auth Example Code

import 'dart:async';
import 'dart:convert';
import 'dart:io';

import 'package:flint_client/flint_client.dart';

Future<void> main() async {
  final server = await _startMockWsServer();
  final httpBaseUrl = 'http://localhost:${server.port}';
  final wsUrl = 'ws://localhost:${server.port}/ws';

  await _headerAuthExample(httpBaseUrl);
  await _queryAuthExample(wsUrl);
  await _authEventExample(wsUrl);

  await server.close(force: true);
}

Future<void> _headerAuthExample(String httpBaseUrl) async {
  final client = FlintClient(
    baseUrl: httpBaseUrl,
    headers: {'Authorization': 'Bearer header-token-123'},
    debug: true,
  );

  final ws = client.ws('/ws', params: {'example': 'header'});
  ws.on('connect', (_) => print('Connected with header token'));
  ws.on('ack', (data) => print('Server ack: $data'));

  await ws.connect();
  ws.emit('message', {'text': 'hello from header auth'});

  await Future<void>.delayed(const Duration(milliseconds: 300));
  ws.dispose();
  client.dispose();
}

Future<void> _queryAuthExample(String wsUrl) async {
  final ws = FlintWebSocketClient(
    wsUrl,
    params: {'example': 'query'},
    sendTokenAsQuery: true,
    queryTokenKey: 'token',
    tokenProvider: () async => 'query-token-456',
    debug: true,
  );

  ws.on('connect', (_) => print('Connected with query token'));
  ws.on('ack', (data) => print('Server ack: $data'));

  await ws.connect();
  ws.emit('message', {'text': 'hello from query auth'});

  await Future<void>.delayed(const Duration(milliseconds: 300));
  ws.dispose();
}

Future<void> _authEventExample(String wsUrl) async {
  final ws = FlintWebSocketClient(
    wsUrl,
    params: {'example': 'event'},
    autoAuthEvent: true,
    authEventName: 'auth',
    authPayload: {'token': 'event-token-789'},
    debug: true,
  );

  ws.on('connect', (_) => print('Connected, auth event will auto-send'));
  ws.on('authed', (data) => print('Auth accepted: $data'));
  ws.on('ack', (data) => print('Server ack: $data'));

  await ws.connect();
  ws.emit('message', {'text': 'hello after auth event'});

  await Future<void>.delayed(const Duration(milliseconds: 300));
  ws.dispose();
}

Future<HttpServer> _startMockWsServer() async {
  final server = await HttpServer.bind('localhost', 0);

  server.listen((request) async {
    if (request.uri.path != '/ws') {
      request.response
        ..statusCode = 404
        ..write('Not found')
        ..close();
      return;
    }

    final authHeader = request.headers.value(HttpHeaders.authorizationHeader);
    final tokenFromQuery = request.uri.queryParameters['token'];
    final exampleType = request.uri.queryParameters['example'] ?? 'unknown';

    final socket = await WebSocketTransformer.upgrade(request);
    socket.add(
      jsonEncode({
        'event': 'ack',
        'data': {
          'example': exampleType,
          'authHeader': authHeader,
          'tokenFromQuery': tokenFromQuery,
        },
      }),
    );

    socket.listen((raw) {
      try {
        final msg = jsonDecode(raw.toString()) as Map<String, dynamic>;
        final event = msg['event']?.toString() ?? '';
        final data = msg['data'];

        if (event == 'auth') {
          socket.add(jsonEncode({'event': 'authed', 'data': data}));
          return;
        }
        if (event == 'ping') {
          socket.add(jsonEncode({'event': 'pong'}));
          return;
        }

        socket.add(
          jsonEncode({
            'event': 'message',
            'data': {'echo': data},
          }),
        );
      } catch (_) {}
    });
  });

  return server;
}

Strict vs Lenient Parse Modes

Parse mode controls how FlintClient handles response data type mismatches.

// Global default
final strictClient = FlintClient(
  baseUrl: 'https://api.example.com',
  defaultParseMode: ResponseParseMode.strict,
);

// Per-request override
final response = await strictClient.get<int>(
  '/stats/value',
  parseMode: ResponseParseMode.lenient,
);

Observability Hooks and Context

Observability means seeing what your HTTP client is doing in real time: request start, retry events, cache hits, errors, and request end.

RequestContext is the shared request state that flows through hooks/interceptors. It carries things like correlation ID, attempt number, timing, and cache metadata.

final client = FlintClient(
  baseUrl: 'https://api.example.com',
  lifecycleHooks: RequestLifecycleHooks(
    onRequestStart: (ctx) => print('START ${ctx.correlationId}'),
    onRetry: (ctx, err, delay) => print('RETRY ${ctx.attempt} in $delay'),
    onCacheHit: (ctx, key, _) => print('CACHE HIT $key'),
    onError: (ctx, err, willRetry) =>
        print('ERROR ${err.kind} willRetry=$willRetry'),
    onRequestEnd: (ctx, response, error) =>
        print('END status=${response?.statusCode} duration=${ctx.totalDuration}'),
  ),
  contextualRequestInterceptor: (request, ctx) async {
    request.headers.set('X-Correlation-Id', ctx.correlationId);
  },
);

Run Full Local Demo

Use the end-to-end mock server example in the client repo to test cache/retry/cancel/hook behavior quickly.

dart run example/lib/full_observability_mock_example.dart

dart run example/lib/http_methods_and_download_example.dart