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
Release Flutter SDK from c3426840f3c0c5245b0028fa9bca2a29c336b77e
vmodal-release-app4ef3a72a0bab
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ec454f4..6ee528f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,7 @@## 1.1.0+- Added ordered asynchronous batch search with mini-batch ownership, bounded+ worker concurrency, preflight validation, and cooperative cancellation.- Streamed signed upload bodies with awaited socket backpressure, exact fileranges, source-version checks, and bounded body/response timeouts.- Enforced one signed-upload concurrency budget across bulk multipart tasks anddiff --git a/RELEASE_METADATA b/RELEASE_METADATAindex e4cf292..040271f 100644--- a/RELEASE_METADATA+++ b/RELEASE_METADATA@@ -1 +1 @@-Source-vmx-api: 7dd88239fd2e7a3f0c94b89e18ceaa003f233a32+Source-vmx-api: c3426840f3c0c5245b0028fa9bca2a29c336b77ediff --git a/SOURCE_MANIFEST.sha256 b/SOURCE_MANIFEST.sha256index 5c5629d..c4d91de 100644--- a/SOURCE_MANIFEST.sha256+++ b/SOURCE_MANIFEST.sha256@@ -2,19 +2,19 @@ e789cd4d1bed8a78ec8014c5c5913e300f81b63ea56a56aacb0dfec3b5e7ce2b ./.flutter-verfbbda2e7e29bbd860539a9ca18c478f3b02de140f25a872c19a6dbecd11bc94b ./.github/workflows/publish.ymla98f72526420d47e76b9b4e67ac86acd06b7088ad1f4c35617b11b09e59346ea ./.gitleaks.toml5115d06bd9913f466d50fcbf8ad8890372349060c54a4581f3481ea084cfdec6 ./.pubignore-c2d0f70729c0293aaf35ea6c0d701dbda4a97b0bc0f7d08b7e29845b24944255 ./CHANGELOG.md+8087660c63935bd64fedee0cbf615a7aa706dea9649b945d7404903df03332af ./CHANGELOG.md37b7148216ac6090e36adfb699d642b8dd1e1b8ba99870e65e88733947a59fa6 ./LICENSEd63378f391ef251ea0afb8841c6886841cab25352d845630c1a117f83e281723 ./README.md-a7c75e0532999a4f8c486aa112bf83d89461b1a0fdfc18a55a4e41553b63f705 ./RELEASE_METADATA+58968890f9f778e6301b09005e9a9cbf60f9714c696e5e371ac9bab3fda8553c ./RELEASE_METADATAdef7e4f643adff5b01b877b6a7fa5b2381612b693c0bf06bd232ee0f7197d342 ./analysis_options.yaml8c2d096dc399d9bea2fcc5ae19d987e7458c8503cf2a7edf1f1497ae00d681aa ./build.sh4f18642680fb433554a5523d00bd99e0d650af340bcaebe628f59f63ac84e458 ./dartdoc_options.yaml75461620cf3a062f4dad10e034952b82cca461b483788de1f46c539aca8b0f0f ./doc/manage_api_key.mda66d39da0983a994474fa516f81fd41bbb131efbd69c955891a41781a76daf24 ./doc/performance.mdcae6114908952cf81a908b7fcc8c0ba4ce3f866e9dbaf974303273f334e0e3f6 ./doc/release.md-7d849dcf1d4c8537ee33e8fdd6282d3bbe2244e68a9c997dcaf77f23db1b5562 ./doc/sdk_contract.md+79ef7a2c5e695699a5d784af5ec72a515401bf7d21f632a2ccc1e973db230e10 ./doc/sdk_contract.md2c07c5319044416d722732f731cc709fc6f6f3e375861bb6b5326a8768258de5 ./doc/sdk_doc.md-6139d92cf19577ec2d920daa5416d2982e425f63639f858201c91caf39b109bf ./doc/search_app.md+c0f878afdfd9f8b9914d60ce1c7bc15a54d2c8631826a3a6d17907d4c2ada846 ./doc/search_app.md7b0acfc01cfa4c8bf3af8aeb19741e65b8e9406935d9ab8e0f4cb84547483e55 ./doc/transcode_360.mde246ed229511a24a1ee7e98529c203ef90d1d352290ce8486caebe05683db3a0 ./env.shc5ce516b547327aab5b6fa27a523d4c76e66294ada3248b293c54b9595cd3a87 ./example/01_full_app/.metadata@@ -103,7 +103,7 @@ d3e03d9a72a499659c70f2296115d1d3138b9370a017e027d8255f85f7fb1c5c ./lib/src/cont873d969cfed5c725d34df0fd0c8769462b56992cf523710fcf741a81fa1bbcad ./lib/src/errors.dart027174edd680e69e067453695f62680fd90b16c78f74a6999ab926cd2fd257dc ./lib/src/http.dart7670598bf28a23808d0e0bd3e3ea1ec7270fbc450caef2ecc1c0ab0921d17538 ./lib/src/models.dart-248cc2f57edbcd5c8686ea03854403d704a3d8c18086dc525a5609226728ad92 ./lib/src/resources.dart+92d2769b42db1062f91c49573af5537793ec98de07c0cf71de074a288816aabd ./lib/src/resources.dart43770c621bffccf69eacebd1e3b297503ca288093c848f0e8ccbd118d7f0d88a ./lib/src/routes.dart27056230065682f3ea3aa747c39c08950dcdca87387f4733adfad18f4b345b06 ./lib/src/routes.g.dart42331852249c8f99874a5e3889c752fd344ad8a5301ede246d5a4fbccb4191f2 ./lib/src/transcode.dart@@ -131,7 +131,7 @@ d132b6dceb89804a47418245845547a25fcf8f89f56b292ee70a404d63364865 ./test/fakes.d959b19196513005ffd19bded8e4a2867a0fa84c8e85eae84aeebcc7fc70f8f88 ./test/multipart_upload_test.dart348b9581f6262acaaf96012a3d57685b0b45c3663c1497f14135663de7a60954 ./test/new_api_surface_test.dart58222c7f00e8aa8070df89d59278ce0d18842f53a7544261aa4a63ae4b1dd608 ./test/regression_manifest_test.dart-13fc92ce0d804731aaee7a3bf3b145cb213d67a2ff18ebc271a32f2aba404679 ./test/resources_models_test.dart+8c87a4645a2e329477d070277f64b617da14ac90163bb734fbb5326c1a97a5c3 ./test/resources_models_test.dart8619ce113bb8669612f9a2a16b1b334ac68435c5972e84828a789511467fcb77 ./test/shell_scripts_test.dartdeacf67ef61894d8fd7d3cdd7648bace527917fe2097c65140286d324ec8b1aa ./test/transcode_upload_test.dart7f62ef6965a51fee7123689003432dd013936b4189504222333cedb55c82dcc2 ./test/transport_test.dartdiff --git a/doc/sdk_contract.md b/doc/sdk_contract.mdindex e9f3ee5..4dcca63 100644--- a/doc/sdk_contract.md+++ b/doc/sdk_contract.md@@ -10,7 +10,7 @@ behavior. `test/fixtures/routes_contract.json` is the reviewed normalized mirror| Scoped facade | `VModal.configure`, `VModal.fromClient`, `VModalProject.scope`, `listCollections`, `close` | Preferred additive API || Scoped operations | `upload`, `uploadMetadata`, `search`, `addAssets`, `updateAsset`, index lifecycle, collection deletion | Immutable organization; delegates to resources || Client/auth | `health`, `authCheck`, `auth.me` | Active; gateway bearer only |-| Searches | `searchVideo(SearchRequest)` | Active; exact Python/Android defaults |+| Searches | `searchVideo(SearchRequest)`, `searchBatch(List<SearchRequest>)` | Active; exact single-search contract and bounded client-side batch scheduling || Collections | `listGroups`, `uploadFile`, `uploadMetadataJsonl`, `addAssets`, `updateDescription`, `delete` | Active || Signed upload | `videoUpload`, `videoUploadBulk` | Active; signed single is default || Indexes | `jobsList`, `createIndex`, `indexStatus`, `deleteIndex` | Active |diff --git a/doc/search_app.md b/doc/search_app.mdindex c6103b2..36f009c 100644--- a/doc/search_app.md+++ b/doc/search_app.md@@ -92,3 +92,23 @@ application client merely because a page was disposed.If application logic inspects a structured error body, server filesystem pathsare replaced with `****` before the exception reaches the application. Do notrender the remaining raw server detail as user-facing copy.++For independent low-level searches, use `client.searches.searchBatch(...)`.+`batchSize` controls the contiguous mini-batch owned by a worker, while+`nWorker` is the maximum number of search requests in flight. Results retain+the input order even when network responses complete in another order:++```dart+final cancellation = CancellationToken();+final results = await client.searches.searchBatch(+ requests,+ batchSize: 8,+ nWorker: 3,+ cancellation: cancellation,+);+```++Keep the token with the screen, controller, or session that owns the batch.+Cancel and await active batches before clearing or replacing authentication+credentials, logging out, or closing `VmodalClient`. The batch helper never+cancels a caller-owned token after an item failure and does not retry searches.diff --git a/lib/src/resources.dart b/lib/src/resources.dartindex cb95b39..7ae2406 100644--- a/lib/src/resources.dart+++ b/lib/src/resources.dart@@ -71,6 +71,95 @@ class SearchesResource {),);}++ /// Runs [batchQueryInput] through [searchVideo] with bounded concurrency.+ ///+ /// Each worker processes contiguous mini-batches of [batchSize] requests+ /// serially. At most [nWorker] searches are in flight, and results retain+ /// their input order. The caller owns [cancellation] and may share it with+ /// other operations.+ Future<List<SearchResponse>> searchBatch(+ List<SearchRequest> batchQueryInput, {+ int batchSize = 10,+ int nWorker = 4,+ CancellationToken? cancellation,+ }) async {+ if (batchSize <= 0) {+ throw const ValidationException('batchSize must be greater than zero');+ }+ if (nWorker <= 0) {+ throw const ValidationException('nWorker must be greater than zero');+ }++ final requests = List<SearchRequest>.of(batchQueryInput, growable: false);+ for (final request in requests) {+ request.validate();+ }+ if (requests.isEmpty) return <SearchResponse>[];++ final results = List<SearchResponse?>.filled(requests.length, null);+ final failures = <_BatchFailure>[];+ var nextStart = 0;+ var stopped = false;++ void recordFailure(int index, Object error, StackTrace stackTrace) {+ failures.add(_BatchFailure(index, error, stackTrace));+ stopped = true;+ }++ Future<void> worker() async {+ while (true) {+ if (stopped) return;+ try {+ cancellation?.throwIfCanceled();+ } on Object catch (error, stackTrace) {+ recordFailure(nextStart, error, stackTrace);+ return;+ }+ if (stopped || nextStart >= requests.length) return;++ final start = nextStart;+ final end = min(start + batchSize, requests.length);+ nextStart = end;+ for (var index = start; index < end; index++) {+ if (stopped) return;+ try {+ cancellation?.throwIfCanceled();+ results[index] = await searchVideo(+ requests[index],+ cancellation: cancellation,+ );+ } on Object catch (error, stackTrace) {+ recordFailure(index, error, stackTrace);+ return;+ }+ }+ }+ }++ final batchCount = (requests.length + batchSize - 1) ~/ batchSize;+ await Future.wait(<Future<void>>[+ for (var index = 0; index < min(nWorker, batchCount); index++) worker(),+ ]);++ if (failures.isNotEmpty) {+ failures.sort(+ (_BatchFailure left, _BatchFailure right) =>+ left.index.compareTo(right.index),+ );+ final failure = failures.first;+ Error.throwWithStackTrace(failure.error, failure.stackTrace);+ }+ return <SearchResponse>[for (final result in results) result!];+ }+}++final class _BatchFailure {+ const _BatchFailure(this.index, this.error, this.stackTrace);++ final int index;+ final Object error;+ final StackTrace stackTrace;}/// Collection discovery, mutation, and media-upload operations.diff --git a/test/resources_models_test.dart b/test/resources_models_test.dartindex 6b79093..d514221 100644--- a/test/resources_models_test.dart+++ b/test/resources_models_test.dart@@ -1,3 +1,4 @@+import 'dart:async';import 'dart:convert';import 'dart:io';@@ -6,6 +7,14 @@ import 'package:vmodal_sdk_flutter/vmodal_sdk_flutter.dart';import 'fakes.dart';+int searchIndex(VmodalRequest request) {+ final body = request.jsonBody! as Map<String, Object?>;+ return int.parse((body['query_text']! as String).split('-').last);+}++VmodalResponse searchResponse(int index) =>+ jsonResponse('{"data":[],"cnt_actual":$index,"cnt_total":$index}');+void main() {test('search serialization preserves exact defaults and snake case',@@ -30,6 +39,282 @@ void main() {},);+ test('batch search preserves input order after mixed completion', () async {+ final started = Completer<void>();+ final gates = List<Completer<void>>.generate(3, (_) => Completer<void>());+ var calls = 0;+ final fake = HandlerTransport((VmodalRequest _) async {+ final index = calls;+ calls++;+ if (calls == 3) started.complete();+ await gates[index].future;+ return searchResponse(index);+ });+ final client = VmodalClient(+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),+ transport: fake,+ signedUploadTransport: FakeSignedUploadTransport(),+ );+ final future = client.searches.searchBatch(+ List<SearchRequest>.generate(+ 3,+ (_) => const SearchRequest(queryText: 'duplicate'),+ ),+ batchSize: 1,+ nWorker: 3,+ );+ await started.future;+ gates[2].complete();+ gates[0].complete();+ gates[1].complete();+ final results = await future;+ expect(results.map((SearchResponse value) => value.cntActual), <int>[+ 0,+ 1,+ 2,+ ]);+ });++ test('batch search keeps worker concurrency at or below nWorker', () async {+ final started = List<Completer<void>>.generate(+ 11,+ (_) => Completer<void>(),+ );+ final gates = List<Completer<void>>.generate(11, (_) => Completer<void>());+ var active = 0;+ var maxActive = 0;+ final fake = HandlerTransport((VmodalRequest request) async {+ final index = searchIndex(request);+ active++;+ if (active > maxActive) maxActive = active;+ started[index].complete();+ try {+ await gates[index].future;+ return searchResponse(index);+ } finally {+ active--;+ }+ });+ final client = VmodalClient(+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),+ transport: fake,+ signedUploadTransport: FakeSignedUploadTransport(),+ );+ final future = client.searches.searchBatch(+ List<SearchRequest>.generate(+ 11,+ (int index) => SearchRequest(queryText: 'query-$index'),+ ),+ batchSize: 2,+ nWorker: 3,+ );++ await Future.wait(<Future<void>>[+ started[0].future,+ started[2].future,+ started[4].future,+ ]);+ gates[0].complete();+ gates[2].complete();+ gates[4].complete();+ await Future.wait(<Future<void>>[+ started[1].future,+ started[3].future,+ started[5].future,+ ]);+ gates[1].complete();+ gates[3].complete();+ gates[5].complete();+ await Future.wait(<Future<void>>[+ started[6].future,+ started[8].future,+ started[10].future,+ ]);+ gates[6].complete();+ gates[8].complete();+ gates[10].complete();+ await Future.wait(<Future<void>>[started[7].future, started[9].future]);+ gates[7].complete();+ gates[9].complete();+ expect(await future, hasLength(11));+ expect(maxActive, 3);+ });++ test('batch search executes each worker mini-batch serially', () async {+ final started = List<Completer<void>>.generate(4, (_) => Completer<void>());+ final gates = List<Completer<void>>.generate(4, (_) => Completer<void>());+ final fake = HandlerTransport((VmodalRequest request) async {+ final index = searchIndex(request);+ started[index].complete();+ await gates[index].future;+ return searchResponse(index);+ });+ final client = VmodalClient(+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),+ transport: fake,+ signedUploadTransport: FakeSignedUploadTransport(),+ );+ final future = client.searches.searchBatch(+ List<SearchRequest>.generate(+ 4,+ (int index) => SearchRequest(queryText: 'query-$index'),+ ),+ batchSize: 2,+ nWorker: 2,+ );+ await Future.wait(<Future<void>>[started[0].future, started[2].future]);+ expect(started[1].isCompleted, isFalse);+ expect(started[3].isCompleted, isFalse);+ gates[0].complete();+ await started[1].future;+ expect(started[3].isCompleted, isFalse);+ gates[1].complete();+ gates[2].complete();+ await started[3].future;+ gates[3].complete();+ expect(await future, hasLength(4));+ });++ test('batch search empty and invalid inputs stay local', () async {+ final fake = FakeTransport();+ final client = VmodalClient(+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),+ transport: fake,+ signedUploadTransport: FakeSignedUploadTransport(),+ );+ expect(await client.searches.searchBatch(<SearchRequest>[]), isEmpty);+ await expectLater(+ client.searches.searchBatch(<SearchRequest>[], batchSize: 0),+ throwsA(isA<ValidationException>()),+ );+ await expectLater(+ client.searches.searchBatch(<SearchRequest>[], nWorker: 0),+ throwsA(isA<ValidationException>()),+ );+ await expectLater(+ client.searches.searchBatch(const <SearchRequest>[+ SearchRequest(queryText: 'valid'),+ SearchRequest(),+ ]),+ throwsA(isA<ValidationException>()),+ );+ expect(fake.requests, isEmpty);+ });++ test('batch failure stops scheduling and reports lowest input', () async {+ final started = List<Completer<void>>.generate(8, (_) => Completer<void>());+ final gates = List<Completer<void>>.generate(8, (_) => Completer<void>());+ final token = CancellationToken();+ final fake = HandlerTransport((VmodalRequest request) async {+ final index = searchIndex(request);+ started[index].complete();+ await gates[index].future;+ if (index == 2 || index == 4) {+ throw ApiException('failure-$index', statusCode: 500);+ }+ return searchResponse(index);+ });+ final client = VmodalClient(+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),+ transport: fake,+ signedUploadTransport: FakeSignedUploadTransport(),+ );+ final future = client.searches.searchBatch(+ List<SearchRequest>.generate(+ 8,+ (int index) => SearchRequest(queryText: 'query-$index'),+ ),+ batchSize: 2,+ nWorker: 3,+ cancellation: token,+ );+ final expected = expectLater(+ future,+ throwsA(+ isA<ApiException>().having(+ (ApiException value) => value.message,+ 'message',+ 'failure-2',+ ),+ ),+ );+ await Future.wait(<Future<void>>[+ started[0].future,+ started[2].future,+ started[4].future,+ ]);+ gates[4].complete();+ gates[2].complete();+ gates[0].complete();+ await expected;+ expect(fake.requests, hasLength(3));+ expect(token.isCanceled, isFalse);+ });++ test(+ 'batch cancellation reaches active requests and stops scheduling',+ () async {+ final started = <Completer<void>>[Completer<void>(), Completer<void>()];+ final fake = HandlerTransport((VmodalRequest request) async {+ final index = searchIndex(request);+ started[index == 0 ? 0 : 1].complete();+ await request.cancellation.whenCanceled;+ request.cancellation.throwIfCanceled();+ return searchResponse(index);+ });+ final token = CancellationToken();+ final client = VmodalClient(+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),+ transport: fake,+ signedUploadTransport: FakeSignedUploadTransport(),+ );+ final future = client.searches.searchBatch(+ List<SearchRequest>.generate(+ 6,+ (int index) => SearchRequest(queryText: 'query-$index'),+ ),+ batchSize: 2,+ nWorker: 2,+ cancellation: token,+ );+ final expected = expectLater(future, throwsA(isA<OperationCanceled>()));+ await Future.wait(<Future<void>>[started[0].future, started[1].future]);+ token.cancel();+ await expected;+ expect(fake.requests, hasLength(2));+ expect(+ fake.requests.every(+ (VmodalRequest request) => request.cancellation.isCanceled,+ ),+ isTrue,+ );+ },+ );++ test('batch search reuses the normal route and request JSON', () async {+ final fake = FakeTransport()+ ..addResponse(jsonResponse('{"data":[],"cnt_actual":0,"cnt_total":0}'));+ final client = VmodalClient(+ config: SdkConfig(baseUrl: 'https://gateway.test', token: 'key'),+ transport: fake,+ signedUploadTransport: FakeSignedUploadTransport(),+ );+ const input = SearchRequest(+ queryText: 'batch contract',+ groupName: 'travel',+ streamName: 'camera',+ limit: 7,+ );+ expect(+ await client.searches.searchBatch(<SearchRequest>[input]),+ hasLength(1),+ );+ final request = fake.requests.single;+ expect(request.method, 'POST');+ expect(request.uri.path, endsWith('/api/external/v1/search'));+ expect(request.jsonBody, input.toJson());+ });+test('model validation and numeric coercion match mobile contract', () {expect(() => const SearchRequest().validate(),