Token source (#901)

Author: hiroshihorie

.changes/token-source

@@ -0,0 +1 @@
+patch type="added" "Token source API with caching, endpoint helpers"

lib/livekit_client.dart

@@ -60,3 +60,11 @@ export 'src/types/video_encoding.dart';
 export 'src/types/video_parameters.dart';
 export 'src/widgets/screen_select_dialog.dart';
 export 'src/widgets/video_track_renderer.dart';
+export 'src/token_source/token_source.dart';
+export 'src/token_source/room_configuration.dart';
+export 'src/token_source/literal.dart';
+export 'src/token_source/endpoint.dart';
+export 'src/token_source/custom.dart';
+export 'src/token_source/caching.dart';
+export 'src/token_source/sandbox.dart';
+export 'src/token_source/jwt.dart';

lib/src/token_source/caching.dart

@@ -0,0 +1,176 @@
+// Copyright 2024 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'dart:async';
+
+import '../support/reusable_completer.dart';
+import 'jwt.dart';
+import 'token_source.dart';
+
+/// A validator function that determines if cached credentials are still valid.
+///
+/// The validator receives the original request options and cached response, and should
+/// return `true` if the cached credentials are still valid for the given request.
+///
+/// The default validator checks JWT expiration using [isResponseExpired].
+typedef TokenValidator = bool Function(TokenRequestOptions options, TokenSourceResponse response);
+
+/// A tuple containing the request options and response that were cached.
+class TokenStoreItem {
+  final TokenRequestOptions options;
+  final TokenSourceResponse response;
+
+  const TokenStoreItem({
+    required this.options,
+    required this.response,
+  });
+}
+
+/// Protocol for storing and retrieving cached token credentials.
+///
+/// Implement this abstract class to create custom storage solutions like
+/// SharedPreferences or secure storage for token caching.
+abstract class TokenStore {
+  /// Store credentials in the store.
+  ///
+  /// This replaces any existing cached credentials with the new ones.
+  Future<void> store(TokenRequestOptions options, TokenSourceResponse response);
+
+  /// Retrieve the cached credentials.
+  ///
+  /// Returns the cached credentials if found, null otherwise.
+  Future<TokenStoreItem?> retrieve();
+
+  /// Clear all stored credentials.
+  Future<void> clear();
+}
+
+/// A simple in-memory store implementation for token caching.
+///
+/// This store keeps credentials in memory and is lost when the app is terminated.
+/// Suitable for development and testing.
+class InMemoryTokenStore implements TokenStore {
+  TokenStoreItem? _cached;
+
+  @override
+  Future<void> store(TokenRequestOptions options, TokenSourceResponse response) async {
+    _cached = TokenStoreItem(options: options, response: response);
+  }
+
+  @override
+  Future<TokenStoreItem?> retrieve() async {
+    return _cached;
+  }
+
+  @override
+  Future<void> clear() async {
+    _cached = null;
+  }
+}
+
+/// Default validator that checks JWT expiration using [isResponseExpired].
+bool _defaultValidator(TokenRequestOptions options, TokenSourceResponse response) {
+  return !isResponseExpired(response);
+}
+
+/// A token source that caches credentials from any [TokenSourceConfigurable] using a configurable store.
+///
+/// This wrapper improves performance by avoiding redundant token requests when credentials are still valid.
+/// It automatically validates cached tokens and fetches new ones when needed.
+///
+/// The cache will refetch credentials when:
+/// - The cached token has expired (validated via [TokenValidator])
+/// - The request options have changed
+/// - The cache has been explicitly invalidated via [invalidate]
+class CachingTokenSource implements TokenSourceConfigurable {
+  final TokenSourceConfigurable _wrapped;
+  final TokenStore _store;
+  final TokenValidator _validator;
+  final Map<TokenRequestOptions, ReusableCompleter<TokenSourceResponse>> _inflightRequests = {};
+
+  /// Initialize a caching wrapper around any token source.
+  ///
+  /// - Parameters:
+  ///   - wrapped: The underlying token source to wrap and cache
+  ///   - store: The store implementation to use for caching (defaults to in-memory store)
+  ///   - validator: A function to determine if cached credentials are still valid (defaults to JWT expiration check)
+  CachingTokenSource(
+    this._wrapped, {
+    TokenStore? store,
+    TokenValidator? validator,
+  })  : _store = store ?? InMemoryTokenStore(),
+        _validator = validator ?? _defaultValidator;
+
+  @override
+  Future<TokenSourceResponse> fetch(TokenRequestOptions options) async {
+    final existingCompleter = _inflightRequests[options];
+    if (existingCompleter != null && existingCompleter.isActive) {
+      return existingCompleter.future;
+    }
+
+    final completer = existingCompleter ?? ReusableCompleter<TokenSourceResponse>();
+    _inflightRequests[options] = completer;
+    final resultFuture = completer.future;
+
+    try {
+      final cached = await _store.retrieve();
+      if (cached != null && cached.options == options && _validator(cached.options, cached.response)) {
+        completer.complete(cached.response);
+        return resultFuture;
+      }
+
+      final response = await _wrapped.fetch(options);
+      await _store.store(options, response);
+      completer.complete(response);
+      return resultFuture;
+    } catch (e, stackTrace) {
+      completer.completeError(e, stackTrace);
+      rethrow;
+    } finally {
+      _inflightRequests.remove(options);
+    }
+  }
+
+  /// Invalidate the cached credentials, forcing a fresh fetch on the next request.
+  Future<void> invalidate() async {
+    await _store.clear();
+  }
+
+  /// Get the cached credentials if one exists.
+  Future<TokenSourceResponse?> cachedResponse() async {
+    final cached = await _store.retrieve();
+    return cached?.response;
+  }
+}
+
+/// Extension to add caching capabilities to any [TokenSourceConfigurable].
+extension CachedTokenSource on TokenSourceConfigurable {
+  /// Wraps this token source with caching capabilities.
+  ///
+  /// The returned token source will reuse valid tokens and only fetch new ones when needed.
+  ///
+  /// - Parameters:
+  ///   - store: The store implementation to use for caching (defaults to in-memory store)
+  ///   - validator: A function to determine if cached credentials are still valid (defaults to JWT expiration check)
+  /// - Returns: A caching token source that wraps this token source
+  CachingTokenSource cached({
+    TokenStore? store,
+    TokenValidator? validator,
+  }) =>
+      CachingTokenSource(
+        this,
+        store: store,
+        validator: validator,
+      );
+}

lib/src/token_source/custom.dart

@@ -0,0 +1,35 @@
+// Copyright 2024 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'token_source.dart';
+
+/// Function signature for custom token generation logic.
+typedef CustomTokenFunction = Future<TokenSourceResponse> Function(TokenRequestOptions options);
+
+/// A custom token source that executes provided logic to fetch credentials.
+///
+/// This allows you to implement your own token fetching strategy with full control
+/// over how credentials are generated or retrieved.
+class CustomTokenSource implements TokenSourceConfigurable {
+  final CustomTokenFunction _function;
+
+  /// Initialize with a custom token generation function.
+  ///
+  /// The [function] will be called whenever credentials need to be fetched,
+  /// receiving [TokenRequestOptions] and returning a [TokenSourceResponse].
+  CustomTokenSource(CustomTokenFunction function) : _function = function;
+
+  @override
+  Future<TokenSourceResponse> fetch(TokenRequestOptions options) async => _function(options);
+}

lib/src/token_source/endpoint.dart

@@ -0,0 +1,114 @@
+// Copyright 2024 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'dart:convert';
+
+import 'package:http/http.dart' as http;
+
+import 'token_source.dart';
+
+/// Error thrown when the token server responds with a non-success HTTP status code.
+class TokenSourceHttpException implements Exception {
+  /// The endpoint that returned the error.
+  final Uri uri;
+
+  /// The HTTP status code returned by the endpoint.
+  final int statusCode;
+
+  /// The raw response body returned by the endpoint.
+  final String body;
+
+  const TokenSourceHttpException({
+    required this.uri,
+    required this.statusCode,
+    required this.body,
+  });
+
+  @override
+  String toString() {
+    return 'TokenSourceHttpException(statusCode: $statusCode, uri: $uri, body: $body)';
+  }
+}
+
+/// A token source that fetches credentials via HTTP requests from a custom backend.
+///
+/// This implementation:
+/// - Sends a POST request to the specified URL (configurable via [method])
+/// - Encodes the request parameters as [TokenRequestOptions] JSON in the request body
+/// - Includes any custom headers specified via [headers]
+/// - Expects the response to be decoded as [TokenSourceResponse] JSON
+/// - Validates HTTP status codes (200-299) and throws appropriate errors for failures
+class EndpointTokenSource implements TokenSourceConfigurable {
+  /// The URL endpoint for token generation.
+  /// This should point to your backend service that generates LiveKit tokens.
+  final Uri uri;
+
+  /// The HTTP method to use for the token request (defaults to "POST").
+  final String method;
+
+  /// Additional HTTP headers to include with the request.
+  final Map<String, String> headers;
+
+  /// Optional HTTP client for testing purposes.
+  final http.Client? client;
+
+  /// Initialize with endpoint configuration.
+  ///
+  /// - [url]: The URL endpoint for token generation
+  /// - [method]: The HTTP method (defaults to "POST")
+  /// - [headers]: Additional HTTP headers (optional)
+  /// - [client]: Custom HTTP client for testing (optional)
+  EndpointTokenSource({
+    required Uri url,
+    this.method = 'POST',
+    this.headers = const {},
+    this.client,
+  }) : uri = url;
+
+  @override
+  Future<TokenSourceResponse> fetch(TokenRequestOptions options) async {
+    final requestBody = jsonEncode(options.toRequest().toJson());
+    final requestHeaders = {
+      'Content-Type': 'application/json',
+      ...headers,
+    };
+
+    final httpClient = client ?? http.Client();
+    final shouldCloseClient = client == null;
+    late final http.Response response;
+
+    try {
+      final request = http.Request(method, uri);
+      request.headers.addAll(requestHeaders);
+      request.body = requestBody;
+      final streamedResponse = await httpClient.send(request);
+      response = await http.Response.fromStream(streamedResponse);
+    } finally {
+      if (shouldCloseClient) {
+        httpClient.close();
+      }
+    }
+
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+      throw TokenSourceHttpException(
+        uri: uri,
+        statusCode: response.statusCode,
+        body: response.body,
+      );
+    }
+
+    final responseBody = jsonDecode(response.body) as Map<String, dynamic>;
+    return TokenSourceResponse.fromJson(responseBody);
+  }
+}