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 'dart:io';
import 'dart:typed_data';
import 'package:http/http.dart' as http;
import 'package:http_parser/http_parser.dart';
import 'config.dart';
import 'errors.dart';
import 'utils.dart';
/// Expected response representation for a [VmodalRequest].
enum VmodalResponseMode {
/// Decode a bounded structured response.
json,
/// Return bounded binary bytes.
bytes,
}
/// Cooperative cancellation signal shared with an in-flight operation.
class CancellationToken {
final Completer<void> _abort = Completer<void>();
final Set<void Function()> _callbacks = <void Function()>{};
/// Whether [cancel] has been called.
bool get isCanceled => _abort.isCompleted;
/// Completes once cancellation is requested.
Future<void> get whenCanceled => _abort.future;
/// Requests cancellation. Repeated calls have no effect.
void cancel() {
if (_abort.isCompleted) return;
_abort.complete();
final callbacks = List<void Function()>.from(_callbacks);
_callbacks.clear();
Object? failure;
StackTrace? trace;
for (final callback in callbacks) {
try {
callback();
} on Object catch (error, stack) {
failure ??= error;
trace ??= stack;
}
}
if (failure != null) Error.throwWithStackTrace(failure, trace!);
}
/// @nodoc
void Function() onCancel(void Function() callback) {
if (isCanceled) {
callback();
return () {};
}
_callbacks.add(callback);
return () => _callbacks.remove(callback);
}
/// Throws [OperationCanceled] after cancellation has been requested.
void throwIfCanceled() {
if (isCanceled) throw const OperationCanceled();
}
}
/// Replayable file part used by multipart SDK operations.
class VmodalFilePart {
/// Creates a part backed by [opener].
///
/// Names, content type, and non-negative [contentLength] are validated.
VmodalFilePart({
required this.fieldName,
required this.fileName,
required this.contentLength,
required Stream<List<int>> Function() opener,
this.contentType = 'application/octet-stream',
}) : _opener = opener {
strMultipartValue('field name', fieldName, 128);
strMultipartValue('file name', fileName, 1024);
strMultipartValue('content type', contentType, 255);
if (contentLength < 0) {
throw const ValidationException('content_length must not be negative');
}
}
/// Creates a replayable part from an in-memory byte list.
factory VmodalFilePart.bytes({
required String fieldName,
required String fileName,
required List<int> bytes,
String contentType = 'application/octet-stream',
}) {
final stable = Uint8List.fromList(bytes);
return VmodalFilePart(
fieldName: fieldName,
fileName: fileName,
contentLength: stable.length,
contentType: contentType,
opener: () => Stream<List<int>>.value(stable),
);
}
/// Form field associated with the file.
final String fieldName;
/// File name reported to the service.
final String fileName;
/// Exact number of bytes produced by [open].
final int contentLength;
/// Media type for the part.
final String contentType;
final Stream<List<int>> Function() _opener;
/// Opens a fresh byte stream for this part.
Stream<List<int>> open() => _opener();
}
/// Creates a replayable part from [file].
///
/// Throws [ValidationException] when the file does not exist.
VmodalFilePart filePart(String fieldName, File file, {String? contentType}) {
if (!file.existsSync()) {
throw const ValidationException('file must exist');
}
return VmodalFilePart(
fieldName: fieldName,
fileName: file.uri.pathSegments.last,
contentLength: file.lengthSync(),
contentType: contentType ?? guessContentType(file.path),
opener: file.openRead,
);
}
/// Creates a replayable part from a caller-provided stream factory.
VmodalFilePart streamPart({
required String fieldName,
required String fileName,
required int contentLength,
required Stream<List<int>> Function() opener,
String? contentType,
}) => VmodalFilePart(
fieldName: fieldName,
fileName: fileName,
contentLength: contentLength,
contentType: contentType ?? guessContentType(fileName),
opener: opener,
);
/// Infers a conservative media type from [name].
String guessContentType(String name) {
final ext = name.contains('.') ? name.split('.').last.toLowerCase() : '';
return switch (ext) {
'json' || 'jsonl' => 'application/json',
'txt' => 'text/plain',
'jpg' || 'jpeg' => 'image/jpeg',
'png' => 'image/png',
'mp4' => 'video/mp4',
_ => 'application/octet-stream',
};
}
/// Transport-neutral request supplied to [VmodalTransport].
///
/// Applications normally use resource methods instead of constructing this
/// type. Custom transport implementations can inspect its immutable fields.
class VmodalRequest {
/// Creates a request, assigning a fresh cancellation token when omitted.
VmodalRequest({
required this.method,
required this.uri,
this.headers = const <String, String>{},
this.jsonBody,
this.formFields = const <String, Object?>{},
this.files = const <VmodalFilePart>[],
this.responseMode = VmodalResponseMode.json,
CancellationToken? cancellation,
}) : cancellation = cancellation ?? CancellationToken();
final String method;
final Uri uri;
final Map<String, String> headers;
final Object? jsonBody;
final Map<String, Object?> formFields;
final List<VmodalFilePart> files;
final VmodalResponseMode responseMode;
final CancellationToken cancellation;
@override
String toString() =>
'VmodalRequest('
'method=$method, '
'pathType=${uri.hasScheme ? 'absolute' : 'relative'}, '
'queryParameterKeys=${uri.queryParametersAll.keys}, '
'headerNames=${headers.keys}, '
'hasJsonBody=${jsonBody != null}, '
'formFieldNames=${formFields.keys}, '
'fileCount=${files.length})';
}
/// Streaming transport response consumed by the SDK.
class VmodalResponse {
/// Creates a response with immutable status and metadata.
const VmodalResponse({
required this.statusCode,
required this.body,
this.headers = const <String, String>{},
this.contentLength = -1,
});
final int statusCode;
final Stream<List<int>> body;
final Map<String, String> headers;
final int contentLength;
@override
String toString() =>
'VmodalResponse('
'statusCode=$statusCode, headerNames=${headers.keys}, '
'contentLength=$contentLength)';
}
/// Pluggable request transport owned by [VmodalClient].
abstract interface class VmodalTransport {
/// Sends [request] and returns its streaming response.
Future<VmodalResponse> send(VmodalRequest request);
/// Releases transport resources. Implementations should be idempotent.
Future<void> close();
}
class HttpVmodalTransport implements VmodalTransport {
HttpVmodalTransport(SdkConfig config, {http.Client? client})
: _config = config,
_client = client ?? http.Client();
final SdkConfig _config;
final http.Client _client;
bool _closed = false;
@override
Future<VmodalResponse> send(VmodalRequest request) async {
if (_closed) throw const TransportException();
request.cancellation.throwIfCanceled();
final http.BaseRequest wire = request.files.isNotEmpty
? _multipart(request)
: _ordinary(request);
wire.followRedirects = false;
wire.headers.addAll(request.headers);
wire.headers.putIfAbsent('Accept', () => 'application/json');
try {
final response = await _client.send(wire).timeout(_config.timeout);
final headers = <String, String>{};
response.headers.forEach((String key, String value) {
headers[key] = value;
});
return VmodalResponse(
statusCode: response.statusCode,
body: response.stream,
headers: headers,
contentLength: response.contentLength ?? -1,
);
} on http.RequestAbortedException {
throw const OperationCanceled();
} on TimeoutException catch (error) {
request.cancellation.cancel();
throw TransportException(error);
} on SocketException catch (error) {
throw TransportException(error);
} on http.ClientException catch (error) {
throw TransportException(error);
}
}
http.BaseRequest _ordinary(VmodalRequest request) {
final wire = http.AbortableRequest(
request.method,
request.uri,
abortTrigger: request.cancellation.whenCanceled,
);
if (request.jsonBody != null) {
wire.headers['Content-Type'] = 'application/json';
wire.bodyBytes = utf8.encode(jsonEncode(request.jsonBody));
} else if (request.formFields.isNotEmpty) {
wire.headers['Content-Type'] = 'application/x-www-form-urlencoded';
wire.bodyFields = _formStrings(request.formFields);
}
return wire;
}
http.BaseRequest _multipart(VmodalRequest request) {
final wire = http.AbortableMultipartRequest(
request.method,
request.uri,
abortTrigger: request.cancellation.whenCanceled,
);
request.formFields.forEach((String key, Object? value) {
strMultipartValue('field name', key, 128);
if (value == null) return;
if (value is Iterable) {
for (final item in value) {
if (item != null) {
wire.files.add(http.MultipartFile.fromString(key, '$item'));
}
}
} else {
wire.fields[key] = '$value';
}
});
for (final part in request.files) {
wire.files.add(
http.MultipartFile(
part.fieldName,
http.ByteStream(part.open()),
part.contentLength,
filename: part.fileName,
contentType: MediaType.parse(part.contentType),
),
);
}
return wire;
}
Map<String, String> _formStrings(Map<String, Object?> values) {
final out = <String, String>{};
values.forEach((String key, Object? value) {
if (value != null) out[key] = '$value';
});
return out;
}
@override
Future<void> close() async {
_closed = true;
_client.close();
}
}
Future<Uint8List> readBounded(
VmodalResponse response,
int limitBytes, {
CancellationToken? cancellation,
Duration? idleTimeout,
}) async {
if (limitBytes <= 0) {
throw const ValidationException('response limit is invalid');
}
if (response.contentLength < -1) {
throw const MalformedResponse('invalid Content-Length');
}
if (response.contentLength > limitBytes) {
cancellation?.cancel();
throw ResponseTooLarge(limitBytes, response.contentLength);
}
final builder = BytesBuilder(copy: false);
var total = 0;
await for (final chunk in _bodyWithIdleTimeout(
response.body,
cancellation,
idleTimeout,
)) {
cancellation?.throwIfCanceled();
if (chunk.length > limitBytes - total) {
cancellation?.cancel();
throw ResponseTooLarge(limitBytes, total + chunk.length);
}
builder.add(chunk);
total += chunk.length;
}
return builder.takeBytes();
}
Future<Map<String, Object?>> readJsonObjectBounded(
VmodalResponse response,
int limitBytes, {
CancellationToken? cancellation,
Duration? idleTimeout,
}) async {
if (limitBytes <= 0) {
throw const ValidationException('response limit is invalid');
}
if (response.contentLength < -1) {
throw const MalformedResponse('invalid Content-Length');
}
if (response.contentLength > limitBytes) {
cancellation?.cancel();
throw ResponseTooLarge(limitBytes, response.contentLength);
}
var byteCount = 0;
var valueCount = 0;
Object? decoded;
Stream<List<int>> counted() async* {
await for (final chunk in _bodyWithIdleTimeout(
response.body,
cancellation,
idleTimeout,
)) {
cancellation?.throwIfCanceled();
if (chunk.length > limitBytes - byteCount) {
cancellation?.cancel();
throw ResponseTooLarge(limitBytes, byteCount + chunk.length);
}
byteCount += chunk.length;
yield chunk;
}
}
try {
final text = utf8.decoder.bind(counted());
await for (final value in json.decoder.bind(text)) {
valueCount++;
decoded = value;
}
} on FormatException {
if (byteCount == 0) return <String, Object?>{};
throw const MalformedResponse();
}
if (byteCount == 0) return <String, Object?>{};
if (valueCount != 1 || decoded is! Map<Object?, Object?>) {
throw const MalformedResponse('JSON object response required');
}
final value = decoded;
if (value.keys.any((Object? key) => key is! String)) {
throw const MalformedResponse('JSON object keys must be strings');
}
return Map<String, Object?>.from(value);
}
Future<void> writeBounded(
VmodalResponse response,
IOSink sink,
int limitBytes, {
CancellationToken? cancellation,
Duration? idleTimeout,
}) async {
if (limitBytes <= 0) {
throw const ValidationException('response limit is invalid');
}
if (response.contentLength < -1) {
throw const MalformedResponse('invalid Content-Length');
}
if (response.contentLength > limitBytes) {
cancellation?.cancel();
throw ResponseTooLarge(limitBytes, response.contentLength);
}
var total = 0;
Stream<List<int>> bounded() async* {
await for (final chunk in _bodyWithIdleTimeout(
response.body,
cancellation,
idleTimeout,
)) {
cancellation?.throwIfCanceled();
if (chunk.length > limitBytes - total) {
cancellation?.cancel();
throw ResponseTooLarge(limitBytes, total + chunk.length);
}
total += chunk.length;
yield chunk;
}
}
await sink.addStream(bounded());
}
Stream<List<int>> _bodyWithIdleTimeout(
Stream<List<int>> body,
CancellationToken? cancellation,
Duration? idleTimeout,
) {
if (idleTimeout == null) return body;
return body.timeout(
idleTimeout,
onTimeout: (EventSink<List<int>> sink) {
sink.addError(
TransportException(TimeoutException('response body idle timeout')),
);
sink.close();
cancellation?.cancel();
},
);
}