V- Modal AI: Visual Video / Image Search - Flutter Video SDK
Dart android-sdkflutterflutter-appflutter-packageflutter-sdkflutter-videoflutter-video-editingflutter-video-playerflutter-video-sdkflutter-videosflutter-videosdkmobile-videomobile-video-editor-sdkmobile-video-sdkvideo-editingvideo-sdkvideo-searchvideo-search-enginevideo-streaming
import 'dart:async';
import 'dart:convert';
import 'api_key_provider.dart';
import 'config.dart';
import 'errors.dart';
import 'http.dart';
import 'transport.dart';
import 'upload.dart';
import 'user_session.dart';
/// Observable VModal connection lifecycle; host login remains host-owned.
enum BackendConnectionState {
ready,
refreshing,
unavailable,
expired,
invalidated,
closed,
}
/// Immutable exact resource grant returned by the VModal issuer.
final class ScopedGrant {
ScopedGrant._(
this.grantId,
this.collectionId,
this.streamName,
this.mode,
Set<UserAction> actions,
this.collectionWide,
) : actions = Set<UserAction>.unmodifiable(actions);
factory ScopedGrant.fromJson(Map<String, Object?> json) {
_fields(json, const {
'grant_id',
'collection_id',
'stream_name',
'mode',
'actions',
'collection_wide',
});
final values = json['actions'];
if (values is! List || values.isEmpty) _invalid();
final actions = <UserAction>{};
for (final value in values) {
if (value is! String) _invalid();
final matches = UserAction.values.where((a) => a.name == value);
if (matches.isEmpty || !actions.add(matches.single)) _invalid();
}
if (json['collection_wide'] is! bool) _invalid();
return ScopedGrant._(
_identifier(json, 'grant_id', 128),
_selector(json, 'collection_id'),
_selector(json, 'stream_name'),
_selector(json, 'mode'),
actions,
json['collection_wide']! as bool,
);
}
final String grantId, collectionId, streamName, mode;
final Set<UserAction> actions;
final bool collectionWide;
ContentMapping get mapping => ContentMapping.opaque(
collectionId: collectionId,
streamName: streamName,
mode: mode,
actions: actions,
collectionWide: collectionWide,
);
Map<String, Object?> toJson() => {
'grant_id': grantId,
'collection_id': collectionId,
'stream_name': streamName,
'mode': mode,
'actions': actions.map((a) => a.name).toList()..sort(),
'collection_wide': collectionWide,
};
@override
String toString() => 'ScopedGrant(actions=${actions.length})';
}
/// Strict version-1 server envelope. The bearer stays in memory.
final class ScopedTokenEnvelope {
ScopedTokenEnvelope._({
required this.accessToken,
required this.expiresIn,
required this.issuedAt,
required this.expiresAt,
required this.principalId,
required this.tenantId,
required this.projectId,
required this.appUserId,
required this.policyRevision,
required this.delegationRevision,
required List<ScopedGrant> grants,
}) : grants = List<ScopedGrant>.unmodifiable(grants);
factory ScopedTokenEnvelope.fromJson(Map<String, Object?> json) {
_fields(json, const {
'version',
'auth_mode',
'access_token',
'token_type',
'expires_in',
'issued_at',
'expires_at',
'principal_id',
'tenant_id',
'project_id',
'app_user_id',
'policy_revision',
'delegation_revision',
'grants',
});
if (json['version'] is! int ||
json['version'] != 1 ||
json['auth_mode'] != 'developer_backend' ||
json['token_type'] != 'Bearer') {
_invalid();
}
final lifetime = json['expires_in'];
final revision = json['delegation_revision'];
if (lifetime is! int ||
lifetime < 60 ||
lifetime > 900 ||
revision is! int ||
revision < 1) {
_invalid();
}
final issued = _time(json, 'issued_at');
final expires = _time(json, 'expires_at');
if (expires.difference(issued) != Duration(seconds: lifetime)) _invalid();
final token = json['access_token'];
if (token is! String || token.trim() != token) _invalid();
strApiKey(token);
if (!RegExp(
r'^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$',
).hasMatch(token)) {
_invalid();
}
return ScopedTokenEnvelope._(
accessToken: token,
expiresIn: lifetime,
issuedAt: issued,
expiresAt: expires,
principalId: _identifier(json, 'principal_id', 256),
tenantId: _identifier(json, 'tenant_id', 256),
projectId: _identifier(json, 'project_id', 256),
appUserId: _identifier(json, 'app_user_id', 256),
policyRevision: _identifier(json, 'policy_revision', 128),
delegationRevision: revision,
grants: _grants(json['grants']),
);
}
int get version => 1;
String get authMode => 'developer_backend';
String get tokenType => 'Bearer';
final String accessToken,
principalId,
tenantId,
projectId,
appUserId,
policyRevision;
final int expiresIn, delegationRevision;
final DateTime issuedAt, expiresAt;
final List<ScopedGrant> grants;
String get _binding =>
jsonEncode([principalId, tenantId, projectId, appUserId]);
String get _policy =>
jsonEncode([policyRevision, delegationRevision, _grantPolicy(grants)]);
@override
String toString() =>
'ScopedTokenEnvelope(version=1, grants=${grants.length}, [REDACTED])';
}
/// Thin owner of a guarded user session and its scoped credential lifecycle.
final class BackendConnection {
BackendConnection._(this._source, this._manager);
final _ScopedCredentialSource _source;
final UserSessionManager _manager;
Future<void>? _closing;
UserSession get session {
_source._check();
final value = _manager.current;
if (value == null) throw const SessionInvalidated();
return value;
}
BackendConnectionState get state {
if (_source.state == BackendConnectionState.ready &&
_source._envelope != null &&
!_source.clock().isBefore(_source._envelope!.expiresAt)) {
_source._emit(BackendConnectionState.expired);
}
return _source.state;
}
Stream<BackendConnectionState> get states => _source.states.stream;
UserScope scope(String grantId) {
final active = session;
final grants = _source.envelope.grants.where((g) => g.grantId == grantId);
if (grants.isEmpty) throw const ValidationException('Unknown grant ID');
return active.scope(grants.single.mapping);
}
Future<void> refresh() => _source.refresh();
Future<void> close() {
if (_closing != null) return _closing!;
final done = Completer<void>();
_closing = done.future;
// Retire guards before publishing closed to reentrant stream listeners.
final cleanup = _manager.close();
_source.close();
unawaited(cleanup.then(done.complete, onError: done.completeError));
return done.future;
}
/// @nodoc
static Future<BackendConnection> connect({
required String expectedAppUserId,
required String expectedProjectId,
required Future<ScopedTokenEnvelope> Function() loadToken,
Uri? baseUri,
Duration timeout = const Duration(seconds: 30),
int maxRetries = 1,
Duration refreshLeeway = const Duration(seconds: 60),
ScopedTokenEnvelope? initialToken,
DateTime Function()? clock,
DelayStrategy? delay,
VmodalTransport Function(SdkConfig)? transportFactory,
SignedUploadTransport Function(SdkConfig)? signedUploadTransportFactory,
}) async {
if (expectedAppUserId.isEmpty ||
expectedProjectId.isEmpty ||
refreshLeeway.isNegative) {
_invalid();
}
final config = SdkConfig(
baseUrl: baseUri?.toString(),
timeout: timeout,
maxRetries: maxRetries,
);
final source = _ScopedCredentialSource(
config,
expectedAppUserId,
expectedProjectId,
loadToken,
refreshLeeway,
clock ?? DateTime.now,
delay ?? Future<void>.delayed,
transportFactory ?? HttpVmodalTransport.new,
);
UserSessionManager? manager;
try {
await source.refresh(initialToken: initialToken);
manager = UserSessionManager(
config: config,
credentialSource: source,
transportFactory: transportFactory,
signedUploadTransportFactory: signedUploadTransportFactory,
);
source.onInvalidated = () {
unawaited(manager!.logout());
};
final envelope = source.envelope;
await manager.openUserSession(
tenantId: envelope.tenantId,
appUserId: envelope.appUserId,
allowedContentMapping: envelope.grants.map((g) => g.mapping),
policyRevision: envelope.policyRevision,
);
return BackendConnection._(source, manager);
} on Object {
source.close();
await manager?.close();
rethrow;
}
}
}
class _ScopedCredentialSource implements SessionCredentialSource {
_ScopedCredentialSource(
this.config,
this.expectedAppUserId,
this.expectedProjectId,
this.loadToken,
this.leeway,
this.clock,
this.delay,
this.transportFactory,
);
final SdkConfig config;
final String expectedAppUserId, expectedProjectId;
final Future<ScopedTokenEnvelope> Function() loadToken;
final Duration leeway;
final DateTime Function() clock;
final DelayStrategy delay;
final VmodalTransport Function(SdkConfig) transportFactory;
final states = StreamController<BackendConnectionState>.broadcast();
BackendConnectionState state = BackendConnectionState.refreshing;
ScopedTokenEnvelope? _envelope;
ScopedTokenEnvelope get envelope {
_check();
return _envelope!;
}
int revision = 0, _generation = 0;
int? _rejectedRevision;
final Map<int, DateTime> _expiries = {};
final Set<int> _rejections = {};
Future<void>? _pending;
final CancellationToken _lifetime = CancellationToken();
void Function()? onInvalidated;
final Set<_ScopedProvider> _providers = {};
@override
String get serviceNamespace => SessionContext.serviceNamespaceFor(config);
@override
String get tenantId => envelope.tenantId;
@override
String get expectedPrincipal => envelope.principalId;
@override
String? get projectId => expectedProjectId;
bool get usable =>
_envelope != null &&
clock().isBefore(_envelope!.expiresAt) &&
_rejectedRevision != revision;
void _check() {
if (state == BackendConnectionState.closed ||
state == BackendConnectionState.invalidated) {
throw const SessionInvalidated();
}
}
void _emit(BackendConnectionState next) {
if (state == next) return;
state = next;
states.add(next);
}
void _invalidate() {
++_generation;
_lifetime.cancel();
state = BackendConnectionState.invalidated;
onInvalidated?.call();
if (state == BackendConnectionState.invalidated && !states.isClosed) {
states.add(BackendConnectionState.invalidated);
}
}
@override
MutableApiKeyProvider createProvider({required bool Function() isActive}) {
_check();
final provider = _ScopedProvider(this, isActive);
_providers.add(provider);
return provider;
}
Future<void> ensureReady() async {
_check();
if (!usable) {
if (_envelope != null && !clock().isBefore(_envelope!.expiresAt)) {
_emit(BackendConnectionState.expired);
}
await refresh();
_check();
if (!usable) {
throw const BackendAuthException(BackendAuthFailure.unavailable);
}
return;
}
final effective = Duration(
microseconds: leeway.inMicroseconds < envelope.expiresIn * 500000
? leeway.inMicroseconds
: envelope.expiresIn * 500000,
);
if (!clock().add(effective).isBefore(envelope.expiresAt)) {
unawaited(refresh().catchError((Object _) {}));
}
}
void reject(int failedRevision) {
_check();
_rejections.add(failedRevision);
if (failedRevision == revision) _rejectedRevision = revision;
}
Future<void> recover(int failedRevision) async {
_check();
if (failedRevision < revision && usable) return;
reject(failedRevision);
await refresh();
}
Future<void> refresh({ScopedTokenEnvelope? initialToken}) {
_check();
if (_pending != null) return _pending!;
final generation = _generation;
_emit(BackendConnectionState.refreshing);
final done = Completer<void>();
final future = done.future;
_pending = future;
final probeCancellation = CancellationToken();
final removeCancel = _lifetime.onCancel(probeCancellation.cancel);
unawaited(
_acquire(generation, initialToken, probeCancellation)
.timeout(
config.timeout,
onTimeout: () {
probeCancellation.cancel();
throw const BackendAuthException(BackendAuthFailure.unavailable);
},
)
.then((candidate) {
_check();
if (generation != _generation) throw const SessionInvalidated();
if (!clock().isBefore(candidate.expiresAt)) {
throw const BackendAuthException(
BackendAuthFailure.invalidResponse,
);
}
_envelope = candidate;
revision++;
_expiries[revision] = candidate.expiresAt;
_expiries.removeWhere((_, expiry) => !clock().isBefore(expiry));
_rejections.removeWhere(
(revision) => !_expiries.containsKey(revision),
);
_rejectedRevision = null;
_emit(BackendConnectionState.ready);
})
.then(
(_) => done.complete(),
onError: (Object error, StackTrace stack) {
if (state == BackendConnectionState.closed ||
state == BackendConnectionState.invalidated) {
done.completeError(const SessionInvalidated(), stack);
} else if (error is OperationCanceled ||
error is BackendAuthException &&
error.failure != BackendAuthFailure.unavailable ||
error is ValidationException) {
_invalidate();
done.completeError(error, stack);
} else {
_emit(BackendConnectionState.unavailable);
done.completeError(
const BackendAuthException(BackendAuthFailure.unavailable),
stack,
);
}
},
)
.whenComplete(() {
removeCancel();
if (identical(_pending, future)) _pending = null;
}),
);
return future;
}
Future<T> _live<T>(Future<T> work, CancellationToken cancellation) async {
cancellation.throwIfCanceled();
final result = await Future.any<T>([
work,
cancellation.whenCanceled.then<T>((_) => throw const OperationCanceled()),
]);
cancellation.throwIfCanceled();
_check();
return result;
}
Future<ScopedTokenEnvelope> _acquire(
int generation,
ScopedTokenEnvelope? seed,
CancellationToken cancellation,
) async {
for (var attempt = 0; attempt < 3; attempt++) {
try {
final candidate =
seed ??
await _live<ScopedTokenEnvelope>(
Future<ScopedTokenEnvelope>.sync(loadToken),
cancellation,
);
_check();
cancellation.throwIfCanceled();
if (generation != _generation) throw const SessionInvalidated();
if (candidate.appUserId != expectedAppUserId ||
candidate.projectId != expectedProjectId ||
!clock().isBefore(candidate.expiresAt) ||
candidate.issuedAt.isAfter(
clock().add(const Duration(seconds: 30)),
)) {
throw const BackendAuthException(BackendAuthFailure.invalidResponse);
}
if (_envelope != null &&
(candidate._binding != envelope._binding ||
candidate._policy != envelope._policy)) {
throw const BackendAuthException(BackendAuthFailure.invalidResponse);
}
await _live(_verify(candidate, cancellation), cancellation);
if (!clock().isBefore(candidate.expiresAt)) {
throw const BackendAuthException(BackendAuthFailure.invalidResponse);
}
return candidate;
} on Object catch (error) {
cancellation.throwIfCanceled();
_check();
if (error is OperationCanceled) rethrow;
if (error is ValidationException ||
error is BackendAuthException &&
error.failure != BackendAuthFailure.unavailable) {
rethrow;
}
if ((error is AuthException && error is! BackendAuthException) ||
error is ApiException && error.statusCode == 403) {
throw const BackendAuthException(BackendAuthFailure.invalidResponse);
}
if (attempt == 2 || seed != null) rethrow;
var wait = Duration(milliseconds: attempt == 0 ? 250 : 1000);
if (error is BackendAuthException && error.retryAfter != null) {
final retry = error.retryAfter!;
if (retry > wait) {
wait = retry > config.timeout ? config.timeout : retry;
}
}
await _live(delay(wait), cancellation);
}
}
throw const BackendAuthException(BackendAuthFailure.unavailable);
}
Future<void> _verify(
ScopedTokenEnvelope candidate,
CancellationToken cancellation,
) async {
final probeConfig = config.copyWith(
token: candidate.accessToken,
maxRetries: 0,
);
final transport = transportFactory(probeConfig);
Future<void>? closing;
Future<void> closeProbe() => closing ??= Future<void>.sync(transport.close);
final removeCancel = cancellation.onCancel(() {
unawaited(closeProbe().catchError((Object _) {}));
});
try {
final json = await VmodalHttp(
probeConfig,
transport,
).requestUsers('GET', '/api/v1/auth/me', cancellation: cancellation);
if (json['auth_mode'] != 'developer_backend' ||
json['type'] != 'scoped_user' ||
_time(json, 'expires_at') != candidate.expiresAt ||
json['user_id'] != candidate.principalId ||
json['principal_id'] != candidate.principalId ||
json['tenant_id'] != candidate.tenantId ||
json['project_id'] != candidate.projectId ||
json['app_user_id'] != candidate.appUserId ||
json['policy_revision'] != candidate.policyRevision ||
json['delegation_revision'] is! int ||
json['delegation_revision'] != candidate.delegationRevision ||
_grantPolicy(_grants(json['grants'])) !=
_grantPolicy(candidate.grants)) {
throw const BackendAuthException(BackendAuthFailure.invalidResponse);
}
} finally {
removeCancel();
await closeProbe();
}
}
void close() {
if (state == BackendConnectionState.closed) return;
++_generation;
_lifetime.cancel();
_emit(BackendConnectionState.closed);
for (final provider in _providers.toList()) {
provider.close();
}
_envelope = null;
unawaited(states.close());
}
}
class _ScopedProvider extends MutableApiKeyProvider
implements AsyncCredentialProvider {
_ScopedProvider(this.source, this.isActive)
: super(source.envelope.accessToken);
final _ScopedCredentialSource source;
final bool Function() isActive;
void _check() {
if (isClosed || !isActive()) throw const SessionInvalidated();
source._check();
}
@override
int get revision {
_check();
return source.revision;
}
@override
String current() {
_check();
if (!source.usable) {
throw const BackendAuthException(BackendAuthFailure.unavailable);
}
return source.envelope.accessToken;
}
@override
Future<void> ensureReady() async {
_check();
await source.ensureReady();
_check();
}
@override
bool isRevisionUsable(int revision) {
_check();
final expiry = source._expiries[revision];
return expiry != null &&
source.clock().isBefore(expiry) &&
!source._rejections.contains(revision);
}
@override
void reject(int revision) {
_check();
source.reject(revision);
}
@override
Future<void> recover(int failedRevision) async {
_check();
await source.recover(failedRevision);
_check();
}
@override
void rotate(String newKey) =>
throw const AuthException('Scoped credentials require backend renewal');
@override
void close() {
source._providers.remove(this);
super.close();
}
}
Never _invalid() =>
throw const ValidationException('Invalid scoped token contract');
void _fields(Map<String, Object?> json, Set<String> fields) {
if (json.length != fields.length || !json.keys.every(fields.contains)) {
_invalid();
}
}
String _identifier(Map<String, Object?> json, String key, int limit) {
final value = json[key];
if (value is! String ||
value.trim().isEmpty ||
utf8.encode(value).length > limit ||
value.runes.any((n) => n < 32 || (n >= 127 && n <= 159))) {
_invalid();
}
return value;
}
String _selector(Map<String, Object?> json, String key) {
final value = _identifier(json, key, 80);
if (!RegExp(r'^[a-zA-Z0-9_]{1,80}$').hasMatch(value)) _invalid();
return value;
}
DateTime _time(Map<String, Object?> json, String key) {
final value = json[key];
if (value is! String ||
!RegExp(
r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$',
).hasMatch(value)) {
_invalid();
}
final time = DateTime.tryParse(value);
if (time == null ||
time.toIso8601String().substring(0, 19) != value.substring(0, 19)) {
_invalid();
}
return time;
}
List<ScopedGrant> _grants(Object? raw) {
if (raw is! List || raw.isEmpty || raw.length > 16) _invalid();
final ids = <String>{}, selectors = <String>{};
return raw.map((value) {
if (value is! Map<String, Object?>) _invalid();
final grant = ScopedGrant.fromJson(value);
if (!ids.add(grant.grantId) ||
!selectors.add(
jsonEncode([grant.collectionId, grant.streamName, grant.mode]),
)) {
_invalid();
}
return grant;
}).toList();
}
String _grantPolicy(List<ScopedGrant> grants) {
final values = grants.map((g) => jsonEncode(g.toJson())).toList()..sort();
return jsonEncode(values);
}