xue_hua_video_cache 1.2.2

Video caching plugin with XueHUAEVideoCache.initialize entry and a Rust core.

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.2.2 - 2026-07-10

Fixed

• 修复 Android current_thread FRB handler 未驱动 Tokio 导致 initialize() 挂起。

1.2.1 - 2026-07-09

Changed

• Android 使用 current_thread FRB handler，避免多插件并存时 pthread_key 耗尽。

1.2.0 - 2026-07-03

Added

• ContentLengthProbe — deduplicated origin content-length resolution (cache → single in-flight GET per URI); shared by range playback, precache, and isCached
• Dedicated content-length metadata slot — CacheKey::for_content_length stores file size separately so the bytes=0-1 probe range stays free for real data; legacy metadata in the old slot is migrated on read
• hls_key_for_url() — canonical HLS playlist directory key via normalized URL (to_safe_uri → MD5); ADR-0001 documents invariants for precache, proxy, and removal
• removeCacheByUrl(..., headers: ...) — optional request headers (required when custom_cache_id host override was used during precache)
• Range responder paths — explicit probe_fast / bounded_range / probe_get dispatch with diagnostic logging; HTTP 502 via write_bad_gateway when a probe cannot resolve asset size
• Tests — download_stream_test.dart; Rust coverage for cache-key stability, content-length migration, HLS key normalization, precache orchestrator, and range response helpers

Changed

• Default segment size — 2 MB → 512 KB for lower first-byte latency (initialize(segmentSize:) still overrides in MB units)
• RangeResponder rewrite — removed HEAD-based head(); uses ContentLengthProbe; emits Content-Range only on 206; bounded ranges can stream body length without a known file total
• HTTPS / TLS — reqwest now trusts bundled Mozilla root certs (webpki-root-certs) instead of rustls-platform-verifier, giving uniform TLS behavior across platforms and avoiding Android CertPathValidator rejecting certs without an OCSP responder as Revoked
• MP4 cache keys — ranged entry MD5 serializes query parameters in sorted key order so keys are stable across process restarts
• HLS precache / isCached — playlist keys use hls_key_for_url; queued HLS precache waits via segment-level hls_segments_cached instead of re-probing content length
• downloadStream — returns the same stream instance across accesses (cached in _DownloadBridge)
• Download pool debounce — scheduler round debounce 500 ms → 30 ms
• Precache progress — HLS and MP4 parallel precache emit progress only after a segment is actually cached; a failed download aborts the batch

Fixed

• Probe-fast playback — when origin content-length probe fails, respond with 502 instead of bytes 0-1/*, which AVFoundation and similar players reject as malformed
• removeCacheByUrl(singleFile: true) — purges full-file entry, content-length metadata, all ranged segments, legacy bytes=0-1 slot, and matching HLS segment entries
• HLS precache counting — already-cached segments no longer inflate failure counts or emit spurious progress events
• Android minSdk — restored to 19 (no longer raised to 22 for the removed platform-verifier AAR)

Removed

• Android JNI TLS initializer — XueHuaTls.java, android_tls.rs, and ProGuard consumer rules (superseded by bundled root certs)
• RangeResponder::head() — superseded by ContentLengthProbe

Migration notes

• Segment size default changed — existing on-disk ranged segments keyed under the old 2 MB boundaries will not match new 512 KB segments; clear cache or bump cache keys if you rely on persisted segments after upgrade
• HLS playlist keys changed — keys now derive from normalized URLs; re-precache HLS content after upgrade if you depend on persisted playlist directories
• removeCacheByUrl — pass the same optional headers used during precache when custom_cache_id host override is enabled

1.1.0 - 2026-06-29

Changed

• Dart layer — merged shallow DownloadManager and LruCacheSingleton wrappers into XueHuaVideoCache; DownloadTask moved to lib/src/download_task.dart. Public barrel API unchanged.
• Rust runtime seam — introduced ProxyRuntime bundle (AppContext + DownloadManager + LruCache); parsers receive injected runtime via UrlParserFactory; FRB api uses require_runtime(). Parser layer no longer calls require_state() or LruCacheSingleton::instance().
• Range parser modules — split RangeParserCommon into SegmentResolver, SegmentFetcher, RangeResponder, and PrecacheOrchestrator; MP4/Default parsers delegate to the four modules.
• Precache progress (breaking) — XueHuaVideoCache.precache with progressListen: true now returns Stream<PrecacheProgressEvent>? instead of StreamController<Map>?; use PrecacheProgressEvent from the main barrel.
• HLS parser modules — split UrlParserM3U8 into hls_registry, hls_playlist_resolver, hls_concurrent_orchestrator, and hls_playlist_rewriter; UrlParserM3U8 is a thin router; HLS cache delegates to SegmentResolver::resolve.

Evaluated / No change

• Rust api vs domain layer — evaluated merging rust/src/api/ with parser/video_caching.rs; decided to keep both: api/ remains the FRB seam (DTO conversion, StreamSink wiring, require_runtime()); parser/video_caching.rs stays as domain dispatch via UrlParserFactory.

1.0.1 - 2026-06-28

Fixed

• Hot restart — calling XueHuaVideoCache.initialize() after a Flutter hot restart no longer throws XueHUAEVideoCache already initialized; native state is reused and the proxy is restarted idempotently
• RustLib.init() — skip re-initialization when flutter_rust_bridge is already loaded in the same process

Added

• Regression test test/hot_restart_init_test.dart and Rust unit test init_twice_is_idempotent

1.0.0 - 2026-06-28

First stable release with a Rust core and unified Dart entry point.

Added

• XueHuaVideoCache — unified static API for proxy init, pre-cache, download control, and cache removal
• XueHuaVideoCache.initialize() — starts local proxy, LRU cache, and download pool
• Rust core — local HTTP proxy, LRU memory/disk cache, streaming Range downloads, MP4/M3U8 parsers
• Pre-cache & cache check — XueHuaVideoCache.precache / isCached / parseHlsMasterPlaylist
• Download helpers — downloadStream, allDownloadTasks, pause / resume / cancel by id or URL; HLS-aware cancelTaskAboutUrl
• URL extensions — String.toLocalUri() / toLocalUrl() and related helpers
• ignoreQueryKeys — stable cache keys when query params vary (e.g. token)
• Health monitor — 10s proxy health check with full restart() on failure
• Example app — butterfly.mp4 demo with video_player
• Tests — Rust unit tests; opt-in butterfly network E2E; ./scripts/test_butterfly.sh smoke script
• Documentation — bilingual README (EN / zh-CN) and this changelog

Platform support

• Android, iOS, macOS, Linux, Windows (FFI plugin via Cargokit)

Known limitations

• No custom UrlMatcher / HttpClientBuilder on the Dart side (use ignoreQueryKeys instead)
• Dart LRU introspection API is minimal (removeCacheByUrl only)
• HLS long-video cancellation and download_now: false queueing should be validated in production workloads
• Large segment files are read fully into memory on download completion (memory pressure for very large segments)