Files
meshcore-open/lib/services/received_image_store.dart
T
zjs81 679116ed03 Key per-channel storage by PSK-derived channel ID
Channel messages, settings, region, order and images were persisted by
radio slot index, so a slot reused for a different channel inherited the
old channel's history and settings (#359).

- Channel.storageId: first 8 bytes of SHA-256("meshcore-channel:" + psk).
- All per-channel stores key by channel ID; in-memory state stays by slot.
- The connector keeps a slot -> channel ID map, diffs it against the saved
  map on every channel sync and reloads slots whose channel changed.
- Queued channel frames wait until this session's map is confirmed.
- One-shot per-radio migration from slot keys, using the cached channel
  list the legacy data was written under; rerun-safe if interrupted.
- Deleting a channel clears its data; a channel removed elsewhere keeps its
  history and gets it back when re-added. A PSK edit keeps its place in
  the custom order.
- Slots sharing a PSK share history and settings.
- Image entries record their channel ID; a slot change resets that slot's
  in-progress reassembly.
2026-10-11 17:52:59 -07:00

1735 lines
62 KiB
Dart

/// Receive-side state, persistence and decode scheduling for AEIC images that
/// arrive over `PAYLOAD_TYPE_GRP_DATA` (see `image_chunk_transport.dart`).
///
/// This file holds the whole receive model:
/// * [ReceivedImageRef] the sentinel that a channel message carries in its
/// `text` field instead of the pixels.
/// * [ReceivedImageState] the state machine every incoming image walks.
/// * [ReceivedImageEntry] one immutable snapshot of an image's state.
/// * [ReceivedImageStore] the `ChangeNotifier` the message list listens to:
/// intake, persistence, eviction and the decode queue.
///
/// ## Deliberate dependency shape
///
/// There is no `dart:io` here and no `package:flutter/material.dart`. Bytes go
/// through the [ReceivedImageBlobStore] seam (default:
/// [InMemoryReceivedImageBlobStore]) and decoding goes through the
/// [ReceivedImageDecoder] seam, which `ImageCodecService` satisfies
/// member-for-member (the wiring agent supplies the one-class adapter — this
/// file deliberately does not import the service, so a broken edit over there
/// cannot break the receive tests). That keeps the store unit-testable with no
/// temp directories, no `path_provider` and no 872 MB model, and it keeps the
/// file compilable on web where neither seam has an implementation.
///
/// `FileReceivedImageBlobStore` (`received_image_blob_store_io.dart`) is the
/// file-backed implementation; pass it as `blobs:` and received images survive
/// a restart. With the default in-memory store everything below works exactly
/// as specified but forgets its bytes on restart. Nothing else changes.
///
/// ## Decode policy (four gates)
///
/// The bitstream is ~156 B and already in hand, so decoding is only ever gated
/// on memory, never on bandwidth. Gates, all enforced here:
/// 0. [processAutomatically] — when false, an arrival is parked as
/// `reassembled + needsManualDecode` and waits
/// for a tap. Mirrors the "Process images
/// automatically" setting, which ships OFF.
/// 1. foreground only — [setForeground]; background decode is a ~2.7 GiB
/// peak and an OOM kill waiting to happen.
/// 2. strictly one at a time — and never while the codec is busy encoding for
/// the compose UI.
/// 3. burst cap — at most [burstCap] auto-decodes are queued; the
/// rest wait for a tap ([ReceivedImageEntry.needsManualDecode]).
library;
import 'dart:async';
import 'dart:convert';
import 'package:flutter/foundation.dart';
import '../models/image_codec_support.dart';
import '../widgets/image_send_codec_binding.dart';
import 'image_chunk_transport.dart';
// ---------------------------------------------------------------------------
// Sentinel
// ---------------------------------------------------------------------------
/// Encodes/parses the sentinel string a `ChannelMessage.text` carries in place
/// of an image.
///
/// Mirrors `GifHelper.encodeGif` (`lib/helpers/gif_helper.dart`): the message
/// record stays a short string, the bytes live beside it. The sentinel never
/// changes for the life of the image, so `ChannelMessage`'s `text.hashCode`
/// derived id stays stable and a per-chunk state change does not rewrite the
/// channel's whole prefs blob.
class ReceivedImageRef {
ReceivedImageRef._();
/// Versioned on purpose: a future wire-format change ships `aeic:2:`.
static const String scheme = 'aeic:1:';
static final RegExp _pattern = RegExp(r'^aeic:1:([0-9a-f]{14})$');
static String encode(String streamId) => '$scheme$streamId';
/// Returns the stream id, or null when [text] is not an image sentinel.
static String? parse(String text) =>
_pattern.firstMatch(text.trim())?.group(1);
/// `%04x%02x%08x` — 4 hex sender prefix, 2 hex img id, 8 hex epoch seconds.
///
/// 14 lowercase hex characters, unique in practice, and it doubles as the
/// on-disk filename stem.
static String streamIdFor({
required int senderPrefix,
required int imgId,
required DateTime firstSeen,
}) {
final seconds = firstSeen.millisecondsSinceEpoch ~/ 1000;
return (senderPrefix & 0xFFFF).toRadixString(16).padLeft(4, '0') +
(imgId & 0xFF).toRadixString(16).padLeft(2, '0') +
(seconds & 0xFFFFFFFF).toRadixString(16).padLeft(8, '0');
}
}
// ---------------------------------------------------------------------------
// State
// ---------------------------------------------------------------------------
/// Lifecycle of one received image. Legal transitions are enforced by
/// [ReceivedImageStore]; see the class doc there.
enum ReceivedImageState {
/// Chunks are arriving; nothing is on disk yet.
receiving,
/// The bitstream is complete and persisted, but not decoded.
reassembled,
/// A decode is running right now.
decoding,
/// A PNG exists. This is the ONLY state that shows synthesized pixels, and
/// therefore the only state that carries the R6 provenance label.
decoded,
/// The stream expired with chunks missing. Never retryable — the partial
/// bodies only ever lived in the reassembler's memory.
failedIncomplete,
/// The bitstream arrived whole but the decoder rejected it. User-retryable.
failedCorrupt,
/// No usable decoder (feature off, no weights, web, or no backend).
decoderUnavailable,
/// The PNG was reclaimed by the disk budget. Re-decodable while the
/// bitstream survives.
evicted,
}
extension ReceivedImageStateValue on ReceivedImageState {
String get value => name;
/// True when the UI must show the R6 synthesized-content label.
bool get showsSynthesizedPixels => this == ReceivedImageState.decoded;
bool get isFailure =>
this == ReceivedImageState.failedIncomplete ||
this == ReceivedImageState.failedCorrupt;
}
ReceivedImageState _parseState(Object? raw) {
if (raw is String) {
for (final state in ReceivedImageState.values) {
if (state.name == raw) return state;
}
}
return ReceivedImageState.failedIncomplete;
}
/// Immutable snapshot of one image. Handed to the widget layer; every mutation
/// goes through [ReceivedImageStore].
@immutable
class ReceivedImageEntry {
/// 14 hex chars; see [ReceivedImageRef.streamIdFor]. Also the filename stem.
final String streamId;
final int senderPrefix;
final int imgId;
final int channelIndex;
/// [Channel.storageId] of the channel the image belongs to. [channelIndex]
/// is the radio slot it arrived on, which another channel may reuse later.
/// Null only for entries written before channel IDs existed.
final String? channelId;
/// Local clock at the first chunk — code 27 carries no timestamp.
final DateTime firstSeen;
final ReceivedImageState state;
/// Data chunks accepted so far (parity chunks never counted).
final int receivedChunks;
/// Data chunks the sender announced (`total` in the chunk header).
final int totalChunks;
final AeicRatePoint rate;
final int resolution;
/// Index into [kImageAspectCodes]: the shape the sender's photo was before
/// the codec stretched it into a square. Used to letterbox back on render.
/// Defaults to 0 (square) when the sender said nothing.
final int aspectCode;
/// The source `width / height` to render at, or null to render square.
double? get displayAspectRatio {
final e = kImageAspectCodes[aspectCode & 0x0F];
final r = e[0] / e[1];
return r == 1.0 ? null : r;
}
/// True when chunk 0's metadata byte was unknown/unavailable and [rate] and
/// [resolution] are the shipped defaults rather than the sender's word.
final bool metadataAssumed;
/// One chunk was rebuilt from the XOR parity chunk.
final bool recoveredWithParity;
/// This is the local user's own send. Its PNG is their real 512x512 crop, so
/// [synthesized] is false and the R6 label must NOT be shown.
final bool isOutgoing;
/// Whether the pixels are generative-model output. Derived, never supplied:
/// `synthesized == !isOutgoing`.
bool get synthesized => !isOutgoing;
final int? decodeMs;
final String? error;
/// Auto-decode was skipped (burst cap); the bubble offers "Tap to decode".
final bool needsManualDecode;
final bool bitstreamStored;
final bool pngStored;
final int bitstreamByteCount;
final int pngByteCount;
/// Decoded PNG, cached in memory once read. Not persisted in the sidecar and
/// not part of [==]; callers must not hand these bytes onward without the R6
/// caption (see `received_image_message.dart`).
final Uint8List? pngBytes;
const ReceivedImageEntry({
required this.streamId,
required this.senderPrefix,
required this.imgId,
required this.channelIndex,
this.channelId,
required this.firstSeen,
required this.state,
required this.receivedChunks,
required this.totalChunks,
this.rate = AeicRatePoint.ft32,
this.resolution = kImageCodecSquareSize,
this.aspectCode = 0,
this.metadataAssumed = true,
this.recoveredWithParity = false,
this.isOutgoing = false,
this.decodeMs,
this.error,
this.needsManualDecode = false,
this.bitstreamStored = false,
this.pngStored = false,
this.bitstreamByteCount = 0,
this.pngByteCount = 0,
this.pngBytes,
});
ImageStreamKey get key => ImageStreamKey(
senderPrefix: senderPrefix,
imgId: imgId,
channelIndex: channelIndex,
);
/// Bytes this entry is currently costing on disk.
int get storedBytes =>
(bitstreamStored ? bitstreamByteCount : 0) +
(pngStored ? pngByteCount : 0);
/// `evicted`/`failedCorrupt` can be decoded again only while the ~156 B
/// bitstream survives.
bool get canRetryDecode => bitstreamStored;
static const Object _unset = Object();
ReceivedImageEntry copyWith({
String? channelId,
ReceivedImageState? state,
int? receivedChunks,
int? totalChunks,
AeicRatePoint? rate,
int? resolution,
int? aspectCode,
bool? metadataAssumed,
bool? recoveredWithParity,
Object? decodeMs = _unset,
Object? error = _unset,
bool? needsManualDecode,
bool? bitstreamStored,
bool? pngStored,
int? bitstreamByteCount,
int? pngByteCount,
Object? pngBytes = _unset,
}) {
return ReceivedImageEntry(
streamId: streamId,
senderPrefix: senderPrefix,
imgId: imgId,
channelIndex: channelIndex,
channelId: channelId ?? this.channelId,
firstSeen: firstSeen,
state: state ?? this.state,
receivedChunks: receivedChunks ?? this.receivedChunks,
totalChunks: totalChunks ?? this.totalChunks,
rate: rate ?? this.rate,
resolution: resolution ?? this.resolution,
aspectCode: aspectCode ?? this.aspectCode,
metadataAssumed: metadataAssumed ?? this.metadataAssumed,
recoveredWithParity: recoveredWithParity ?? this.recoveredWithParity,
isOutgoing: isOutgoing,
decodeMs: identical(decodeMs, _unset) ? this.decodeMs : decodeMs as int?,
error: identical(error, _unset) ? this.error : error as String?,
needsManualDecode: needsManualDecode ?? this.needsManualDecode,
bitstreamStored: bitstreamStored ?? this.bitstreamStored,
pngStored: pngStored ?? this.pngStored,
bitstreamByteCount: bitstreamByteCount ?? this.bitstreamByteCount,
pngByteCount: pngByteCount ?? this.pngByteCount,
pngBytes: identical(pngBytes, _unset)
? this.pngBytes
: pngBytes as Uint8List?,
);
}
Map<String, dynamic> toJson() => <String, dynamic>{
'streamId': streamId,
'senderPrefix': senderPrefix,
'imgId': imgId,
'channelIndex': channelIndex,
if (channelId != null) 'channelId': channelId,
'firstSeenMs': firstSeen.millisecondsSinceEpoch,
'state': state.name,
'receivedChunks': receivedChunks,
'totalChunks': totalChunks,
'rate': rate.wireValue,
'resolution': resolution,
'aspect_code': aspectCode,
'metadataAssumed': metadataAssumed,
'recoveredWithParity': recoveredWithParity,
'isOutgoing': isOutgoing,
'synthesized': synthesized,
'needsManualDecode': needsManualDecode,
'bitstreamStored': bitstreamStored,
'pngStored': pngStored,
'bitstreamByteCount': bitstreamByteCount,
'pngByteCount': pngByteCount,
if (decodeMs != null) 'decodeMs': decodeMs,
if (error != null) 'error': error,
};
factory ReceivedImageEntry.fromJson(Map<String, dynamic> json) {
return ReceivedImageEntry(
streamId: json['streamId'] as String? ?? '',
senderPrefix: json['senderPrefix'] as int? ?? 0,
imgId: json['imgId'] as int? ?? 0,
channelIndex: json['channelIndex'] as int? ?? 0,
channelId: json['channelId'] as String?,
firstSeen: DateTime.fromMillisecondsSinceEpoch(
json['firstSeenMs'] as int? ?? 0,
),
state: _parseState(json['state']),
receivedChunks: json['receivedChunks'] as int? ?? 0,
totalChunks: json['totalChunks'] as int? ?? 1,
rate: parseAeicRatePoint(json['rate'] as int? ?? 4),
resolution: json['resolution'] as int? ?? kImageCodecSquareSize,
aspectCode: json['aspect_code'] as int? ?? 0,
metadataAssumed: json['metadataAssumed'] as bool? ?? true,
recoveredWithParity: json['recoveredWithParity'] as bool? ?? false,
isOutgoing: json['isOutgoing'] as bool? ?? false,
decodeMs: json['decodeMs'] as int?,
error: json['error'] as String?,
needsManualDecode: json['needsManualDecode'] as bool? ?? false,
bitstreamStored: json['bitstreamStored'] as bool? ?? false,
pngStored: json['pngStored'] as bool? ?? false,
bitstreamByteCount: json['bitstreamByteCount'] as int? ?? 0,
pngByteCount: json['pngByteCount'] as int? ?? 0,
);
}
@override
String toString() =>
'ReceivedImageEntry($streamId, ${state.name}, '
'$receivedChunks/$totalChunks, ${rate.name})';
}
// ---------------------------------------------------------------------------
// Byte persistence seam
// ---------------------------------------------------------------------------
/// Where the three files of an image live. One implementation per platform.
///
/// Layout the file-backed implementation uses (application *support* dir, not
/// documents — these are derived caches, not user files):
/// `received_images/<streamId>.aeic|.png|.json`. See
/// `received_image_blob_store_io.dart`.
abstract class ReceivedImageBlobStore {
/// Returns false when the bytes could not be stored (disk full, unsafe id),
/// so the caller never records a file that is not there.
Future<bool> writeBitstream(String streamId, Uint8List bytes);
Future<Uint8List?> readBitstream(String streamId);
Future<void> deleteBitstream(String streamId);
/// Same contract as [writeBitstream].
Future<bool> writePng(String streamId, Uint8List bytes);
Future<Uint8List?> readPng(String streamId);
Future<void> deletePng(String streamId);
/// Byte length of the stored bitstream, or null when there is none.
///
/// Concrete on purpose: [load] only needs to know whether the bytes exist and
/// how big they are, and the default below would read every 400 KB PNG on the
/// device into memory at startup (200 images => ~80 MB of pointless I/O) just
/// to call `.length` on it. A file-backed store overrides both with `stat`.
Future<int?> bitstreamSize(String streamId) async =>
(await readBitstream(streamId))?.length;
/// Byte length of the stored PNG, or null when there is none.
Future<int?> pngSize(String streamId) async =>
(await readPng(streamId))?.length;
/// Sidecar write must be atomic (tmp + rename) so a kill cannot leave a
/// half-written record that `readSidecars` then discards.
Future<void> writeSidecar(String streamId, String json);
Future<void> deleteSidecar(String streamId);
/// streamId -> raw sidecar JSON, for the startup scan.
Future<Map<String, String>> readSidecars();
/// Absolute path of the PNG, or null where the platform has no file system.
String? pngPath(String streamId);
}
/// Default implementation: keeps everything in RAM.
///
/// Used by tests, by web (where there is no decoder either, so nothing ever
/// reaches [ReceivedImageState.decoded]) and as the fallback until the
/// file-backed store is wired in.
class InMemoryReceivedImageBlobStore implements ReceivedImageBlobStore {
final Map<String, Uint8List> _bitstreams = <String, Uint8List>{};
final Map<String, Uint8List> _pngs = <String, Uint8List>{};
final Map<String, String> _sidecars = <String, String>{};
@override
Future<bool> writeBitstream(String streamId, Uint8List bytes) async {
_bitstreams[streamId] = bytes;
return true;
}
@override
Future<Uint8List?> readBitstream(String streamId) async =>
_bitstreams[streamId];
@override
Future<void> deleteBitstream(String streamId) async {
_bitstreams.remove(streamId);
}
@override
Future<int?> bitstreamSize(String streamId) async =>
_bitstreams[streamId]?.length;
@override
Future<int?> pngSize(String streamId) async => _pngs[streamId]?.length;
@override
Future<bool> writePng(String streamId, Uint8List bytes) async {
_pngs[streamId] = bytes;
return true;
}
@override
Future<Uint8List?> readPng(String streamId) async => _pngs[streamId];
@override
Future<void> deletePng(String streamId) async {
_pngs.remove(streamId);
}
@override
Future<void> writeSidecar(String streamId, String json) async {
_sidecars[streamId] = json;
}
@override
Future<void> deleteSidecar(String streamId) async {
_sidecars.remove(streamId);
}
@override
Future<Map<String, String>> readSidecars() async =>
Map<String, String>.from(_sidecars);
@override
String? pngPath(String streamId) => null;
// Test/debug helpers.
bool hasBitstream(String streamId) => _bitstreams.containsKey(streamId);
bool hasPng(String streamId) => _pngs.containsKey(streamId);
bool hasSidecar(String streamId) => _sidecars.containsKey(streamId);
}
// ---------------------------------------------------------------------------
// Decoder seam
// ---------------------------------------------------------------------------
/// The slice of `ImageCodecService` the receive path needs.
///
/// `ImageCodecService` satisfies this shape member-for-member, so the adapter
/// the wiring agent writes is pure delegation:
///
/// ```dart
/// class ImageCodecServiceDecoder implements ReceivedImageDecoder {
/// final ImageCodecService service;
/// const ImageCodecServiceDecoder(this.service);
/// @override ImageCodecAvailability get availability => service.availability;
/// @override bool get isBusy => service.isBusy;
/// @override Future<ImageCodecResult?> decodeBitstream({
/// required Uint8List bitstream,
/// required AeicRatePoint ratePoint,
/// required int resolution,
/// }) => service.decodeBitstream(
/// bitstream: bitstream, ratePoint: ratePoint, resolution: resolution);
/// @override void cancelCodecJob() => service.cancelCodecJob();
/// }
/// ```
///
/// The interface also exists so the store can be tested without a 872 MB ONNX
/// graph.
abstract class ReceivedImageDecoder {
ImageCodecAvailability get availability;
/// True while an encode (compose UI) or another decode is running.
bool get isBusy;
/// Returns null when the codec cannot decode at all; a result with
/// `status == failed` when the bitstream was rejected.
Future<ImageCodecResult?> decodeBitstream({
required Uint8List bitstream,
required AeicRatePoint ratePoint,
required int resolution,
});
/// Cooperative cancel, used when we background mid-decode.
void cancelCodecJob();
}
// ---------------------------------------------------------------------------
// The store
// ---------------------------------------------------------------------------
/// Owns every received image: its state, its bytes, its place in the decode
/// queue and its share of the disk budget.
///
/// Legal transitions (nothing else is performed):
/// ```
/// (none) -> receiving first non-duplicate chunk
/// receiving -> receiving another data chunk
/// receiving -> reassembled completed; bitstream written FIRST
/// receiving -> failedIncomplete TTL/overflow eviction
/// reassembled -> decoding dequeued
/// reassembled -> decoderUnavailable no usable decoder at dequeue
/// decoding -> decoded completed && pngBytes != null
/// decoding -> failedCorrupt failed / throw / bad resolution
/// decoding -> decoderUnavailable decodeBitstream returned null
/// decoding -> reassembled cancelled (background / pressure)
/// decoderUnavailable -> decoding retry, or availability recovered
/// failedCorrupt -> decoding explicit user retry only
/// decoded -> evicted budget reclaimed the PNG
/// evicted -> decoding "Decode again", bitstream survives
/// ```
/// `failedIncomplete` is terminal: the partial bodies are gone.
class ReceivedImageStore extends ChangeNotifier {
final ReceivedImageBlobStore blobs;
ReceivedImageDecoder? decoder;
/// Hard cap on stored PNGs.
final int maxImages;
/// Hard cap on entries of any state. Undecoded entries hold no PNG, so
/// [maxImages] never counts them; without this a flood of one-packet images
/// grows the sidecars (and the startup scan) without bound.
final int maxEntries;
/// Hard cap on total bytes across all stored files.
final int maxBytes;
/// Images older than this are dropped from disk entirely.
final Duration maxAge;
/// How many auto-decodes may be queued before the rest need a tap.
final int burstCap;
/// When false, a completed bitstream is parked as
/// `reassembled + needsManualDecode` and waits for a tap. Mirrors the
/// "Process images automatically" app setting.
///
/// Defaults to TRUE at the store level on purpose: that is this class's
/// documented eager contract and what its unit tests assert. Production is
/// off-by-default because `main.dart` passes the (false-by-default) setting
/// explicitly and re-assigns this field whenever the setting changes.
///
/// Assignment affects FUTURE arrivals only. It deliberately does not kick the
/// queue and does not backfill: turning the setting on must not retro-decode
/// a backlog, which would be an unbounded burst of ~2.16 GiB jobs.
bool processAutomatically;
final DateTime Function() _clock;
final Map<String, ReceivedImageEntry> _entries =
<String, ReceivedImageEntry>{};
final Map<ImageStreamKey, String> _byKey = <ImageStreamKey, String>{};
final Map<String, ValueNotifier<ReceivedImageEntry?>> _listenables =
<String, ValueNotifier<ReceivedImageEntry?>>{};
final List<String> _queue = <String>[];
Future<void>? _pump;
/// Set synchronously for as long as [_drain]'s body is running. A plain
/// `_pump != null` check is NOT enough: the future stays non-null for one
/// extra microtask after the body has finished, and a chunk arriving in that
/// window used to be dropped on the floor with the queue non-empty and
/// nothing running.
bool _draining = false;
/// True when the queue stopped because the codec was busy encoding. Cleared
/// by anything that could plausibly have freed it.
bool _parkedOnBusyDecoder = false;
/// Set by [handleMemoryPressure] so the decode it cancels is parked rather
/// than reported as corrupt.
bool _cancelRequested = false;
/// Set by [setForeground] when backgrounding cancels a running decode, so it
/// goes back on the queue instead of being reported as corrupt.
bool _backgroundCancelled = false;
bool _foreground = true;
bool _disposed = false;
ReceivedImageStore({
ReceivedImageBlobStore? blobs,
this.decoder,
this.maxImages = 200,
this.maxEntries = 400,
this.maxBytes = 64 * 1024 * 1024,
this.maxAge = const Duration(days: 30),
this.burstCap = 3,
this.processAutomatically = true,
DateTime Function()? clock,
}) : blobs = blobs ?? InMemoryReceivedImageBlobStore(),
_clock = clock ?? DateTime.now;
// ---- reads ---------------------------------------------------------------
/// Newest first.
List<ReceivedImageEntry> get entries {
final list = _entries.values.toList()
..sort((a, b) => b.firstSeen.compareTo(a.firstSeen));
return List<ReceivedImageEntry>.unmodifiable(list);
}
ReceivedImageEntry? entryFor(String streamId) => _entries[streamId];
ReceivedImageEntry? entryForKey(ImageStreamKey key) {
final id = _byKey[key];
return id == null ? null : _entries[id];
}
/// Per-image listenable so one arriving chunk rebuilds one bubble instead of
/// the whole reversed `ListView`.
ValueListenable<ReceivedImageEntry?> listenableFor(String streamId) {
return _listenables.putIfAbsent(
streamId,
() => ValueNotifier<ReceivedImageEntry?>(_entries[streamId]),
);
}
/// Bytes currently held on disk by all entries.
int get totalBytes =>
_entries.values.fold<int>(0, (sum, e) => sum + e.storedBytes);
int get storedImageCount => _entries.values.where((e) => e.pngStored).length;
/// Stream ids waiting for an automatic decode, oldest request first.
List<String> get decodeQueue => List<String>.unmodifiable(_queue);
bool get isForeground => _foreground;
/// Availability of the decoder seam, or `unavailable` when none is wired.
///
/// Read-only passthrough so a bubble can pick its tap action (decode now vs.
/// send the user to the model download) without importing
/// `ImageCodecService`.
ImageCodecAvailability get decoderAvailability =>
decoder?.availability ?? ImageCodecAvailability.unavailable;
/// True while a decode is running or queued. Callers that want to grey out a
/// "Tap to process" affordance can use it; decodes are strictly serial, so a
/// second tap only lengthens the wall clock, never the peak RSS.
bool get isDecoding => _draining || _queue.isNotEmpty;
// ---- startup -------------------------------------------------------------
/// Loads sidecars and repairs states that cannot survive a process death.
///
/// receiving -> failedIncomplete (partials were never persisted)
/// decoding -> reassembled if the bitstream is there, else failedIncomplete
/// decoded -> evicted if the PNG is gone
Future<void> load() async {
final sidecars = await blobs.readSidecars();
for (final raw in sidecars.values) {
Map<String, dynamic> json;
try {
final decoded = jsonDecode(raw);
if (decoded is! Map<String, dynamic>) continue;
json = decoded;
} catch (_) {
continue;
}
var entry = ReceivedImageEntry.fromJson(json);
if (entry.streamId.isEmpty) continue;
// Sizes, not bytes: reattaching 200 images must not read ~80 MB of PNG
// into RAM on the startup path. The pixels are read lazily by
// [ensurePng] when a bubble actually scrolls into view.
final bitstreamBytes = await blobs.bitstreamSize(entry.streamId);
final pngBytes = await blobs.pngSize(entry.streamId);
entry = entry.copyWith(
bitstreamStored: bitstreamBytes != null,
bitstreamByteCount: bitstreamBytes ?? 0,
pngStored: pngBytes != null,
pngByteCount: pngBytes ?? entry.pngByteCount,
);
switch (entry.state) {
case ReceivedImageState.receiving:
entry = entry.copyWith(state: ReceivedImageState.failedIncomplete);
case ReceivedImageState.decoding:
entry = entry.copyWith(
state: entry.bitstreamStored
? ReceivedImageState.reassembled
: ReceivedImageState.failedIncomplete,
);
case ReceivedImageState.decoded:
if (!entry.pngStored) {
entry = entry.copyWith(state: ReceivedImageState.evicted);
}
case ReceivedImageState.reassembled:
if (!entry.bitstreamStored) {
entry = entry.copyWith(state: ReceivedImageState.failedIncomplete);
} else if (!processAutomatically) {
// load() never enqueues, so a `reassembled` entry restored with
// needsManualDecode == false (written by a session that had the
// setting on, or by an older build) would sit on "Waiting to
// decode" forever with no tap target. Give it one.
entry = entry.copyWith(needsManualDecode: true);
}
case ReceivedImageState.evicted:
case ReceivedImageState.failedIncomplete:
case ReceivedImageState.failedCorrupt:
case ReceivedImageState.decoderUnavailable:
break;
}
_entries[entry.streamId] = entry;
_claimKey(entry);
_publish(entry);
await _persist(entry);
}
await evictToBudget();
_notify();
}
// ---- intake --------------------------------------------------------------
/// Feeds one [ImageReassembler] outcome.
///
/// The caller owns the reassembler (the send path already builds one) and is
/// responsible for having dropped nothing: `malformed` and `fromSelf` are
/// ignored here too, so an unfiltered firehose is safe.
Future<ReceivedImageEntry?> handleOutcome(
ImageChunkOutcome outcome, {
required int channelIndex,
String? channelId,
DateTime? at,
}) async {
final now = at ?? _clock();
switch (outcome.status) {
case ImageChunkStatus.malformed:
case ImageChunkStatus.fromSelf:
return null;
case ImageChunkStatus.duplicate:
final header = outcome.header;
if (header == null) return null;
return entryForKey(
ImageStreamKey(
senderPrefix: header.senderPrefix,
imgId: header.imgId,
channelIndex: channelIndex,
),
);
case ImageChunkStatus.accepted:
case ImageChunkStatus.conflicting:
final header = outcome.header;
if (header == null) return null;
final key = ImageStreamKey(
senderPrefix: header.senderPrefix,
imgId: header.imgId,
channelIndex: channelIndex,
);
final counts = header.isParity ? 0 : 1;
final existing = entryForKey(key);
// `conflicting` means the reassembler threw the old stream away and
// restarted from this chunk. A stream that had already been surfaced
// keeps its id (and therefore its message) only if it was still
// receiving; anything else gets a fresh entry. The same goes for a
// plain `accepted`: once an entry is past `receiving` the reassembler
// reports its stragglers as `duplicate`, so an accepted chunk on that
// key is a new image reusing the 8-bit id and must not overwrite it.
final resets = outcome.status == ImageChunkStatus.conflicting;
if (existing != null &&
existing.state == ReceivedImageState.receiving) {
final updated = existing.copyWith(
state: ReceivedImageState.receiving,
receivedChunks: resets
? counts
: (existing.receivedChunks + counts)
.clamp(0, header.total)
.toInt(),
totalChunks: header.total,
error: null,
// A first chunk seen before its slot had an ID gets one now.
channelId: existing.channelId ?? channelId,
);
return _store(updated);
}
if (existing != null) {
_byKey.remove(key);
}
final streamId = _uniqueStreamId(
senderPrefix: header.senderPrefix,
imgId: header.imgId,
firstSeen: now,
);
final created = ReceivedImageEntry(
streamId: streamId,
senderPrefix: header.senderPrefix,
imgId: header.imgId,
channelIndex: channelIndex,
channelId: channelId,
firstSeen: now,
state: ReceivedImageState.receiving,
receivedChunks: counts,
totalChunks: header.total,
);
return _store(created);
case ImageChunkStatus.unsupportedFormat:
// Every chunk arrived but chunk 0 names a rate point or resolution this
// build cannot decode. The transport has already DISCARDED the bytes,
// and there is nothing to retry, so no bitstream is stored.
final header = outcome.header;
if (header == null) return null;
final entry = entryForKey(
ImageStreamKey(
senderPrefix: header.senderPrefix,
imgId: header.imgId,
channelIndex: channelIndex,
),
);
if (entry == null || entry.state != ReceivedImageState.receiving) {
return null;
}
_queue.remove(entry.streamId);
return _store(
entry.copyWith(
state: ReceivedImageState.failedCorrupt,
bitstreamStored: false,
error: 'Unsupported image format.',
),
);
case ImageChunkStatus.completed:
final result = outcome.result;
if (result == null) return null;
return _handleCompleted(result, now, channelId);
}
}
Future<ReceivedImageEntry> _handleCompleted(
ImageReassemblyResult result,
DateTime now,
String? channelId,
) async {
final key = result.key;
var entry = entryForKey(key);
// A one-chunk image completes without an `accepted` first, so the key may
// still point at an older, finished image that reused the id.
if (entry == null || entry.state != ReceivedImageState.receiving) {
final streamId = _uniqueStreamId(
senderPrefix: key.senderPrefix,
imgId: key.imgId,
firstSeen: now,
);
entry = ReceivedImageEntry(
streamId: streamId,
senderPrefix: key.senderPrefix,
imgId: key.imgId,
channelIndex: key.channelIndex,
channelId: channelId,
firstSeen: now,
state: ReceivedImageState.receiving,
receivedChunks: result.chunkCount,
totalChunks: result.chunkCount,
);
} else if (entry.channelId == null && channelId != null) {
entry = entry.copyWith(channelId: channelId);
}
final metadata = result.metadata;
// The reserved high rate (ft16) and any resolution but 512 cannot be
// decoded by the only model this build ships; storing them as
// `reassembled` would end in an endless "corrupt, retry" loop. Treat them
// like an undecodable metadata byte: nothing to retry, no bytes kept.
if (metadata != null &&
(metadata.rate != ImageCodecRatePoint.standard ||
metadata.squareSize != kImageCodecSquareSize)) {
_queue.remove(entry.streamId);
return _store(
entry.copyWith(
state: ReceivedImageState.failedCorrupt,
receivedChunks: result.chunkCount,
totalChunks: result.chunkCount,
bitstreamStored: false,
error: 'Unsupported image format.',
),
);
}
final tracked = _entries.containsKey(entry.streamId);
// Bitstream first, state second: a kill between the two must be
// recoverable, and `reassembled` with no file on disk is a lie.
final written = await blobs.writeBitstream(entry.streamId, result.data);
if (tracked && !_entries.containsKey(entry.streamId)) {
// Deleted (message removed, channel cleared) while the write was in
// flight. Storing now would resurrect it with no message to show it.
await blobs.deleteBitstream(entry.streamId);
return entry;
}
if (!written) {
return _store(
entry.copyWith(
state: ReceivedImageState.failedCorrupt,
receivedChunks: result.chunkCount,
totalChunks: result.chunkCount,
bitstreamStored: false,
error: 'Could not save the image data.',
),
);
}
final updated = entry.copyWith(
state: ReceivedImageState.reassembled,
receivedChunks: result.chunkCount,
totalChunks: result.chunkCount,
rate: metadata == null
? AeicRatePoint.ft32
: aeicRatePointForUi(metadata.rate),
aspectCode: metadata?.aspectCode ?? 0,
resolution: metadata?.squareSize ?? kImageCodecSquareSize,
metadataAssumed: metadata == null,
recoveredWithParity: result.recoveredWithParity,
bitstreamStored: true,
bitstreamByteCount: result.data.length,
error: null,
);
if (!processAutomatically) {
// Park it: the card shows "N bytes · M packets" and "Tap to process".
// A 2.16 GiB decode is never started off the back of a radio packet
// unless the user asked for that.
final parked = await _store(updated.copyWith(needsManualDecode: true));
await _enforceEntryCap(protect: parked.streamId);
return parked;
}
final stored = await _store(updated);
await _enforceEntryCap(protect: stored.streamId);
_enqueue(stored.streamId);
return stored;
}
/// A stream the reassembler gave up on (TTL or concurrency overflow).
Future<ReceivedImageEntry?> handleFailure(
ImageReassemblyFailure failure,
) async {
final entry = entryForKey(failure.key);
if (entry == null) return null;
if (entry.state != ReceivedImageState.receiving) {
// Already completed by a later chunk; the failure is stale.
return entry;
}
final failed = await _store(
entry.copyWith(
// `isCorrupt` means every chunk arrived but the bytes were unusable
// (CRC-16 mismatch or an undecodable metadata byte). The UI must say
// "corrupt", not "incomplete".
state: failure.isCorrupt
? ReceivedImageState.failedCorrupt
: ReceivedImageState.failedIncomplete,
receivedChunks: failure.receivedDataChunks,
totalChunks: failure.total,
error: failure.isCorrupt ? failure.reason.name : null,
),
);
await evictToBudget(protect: failed.streamId);
return failed;
}
/// Records the local user's own send so the outgoing bubble can show the real
/// 512x512 crop. [previewPng] is a photograph, not a decode, so the entry is
/// never [ReceivedImageEntry.synthesized] and carries no R6 label.
///
/// The send path must call this BEFORE it posts the message, and put the
/// returned id in the message text — that sentinel is the only link between
/// the `ChannelMessage` and these pixels:
///
/// ```dart
/// final entry = await receivedImageStore.registerOutgoing(
/// channelIndex: channelIndex,
/// channelId: channel.storageId,
/// senderPrefix: selfPrefix, // same 16 bits the chunk header carries
/// imgId: chunkSet.imgId,
/// previewPng: preview.croppedPngBytes, // the 512x512 crop, NOT a decode
/// rate: kImageSendRatePoint,
/// chunkCount: chunkSet.dataChunkCount,
/// );
/// await connector.sendChannelMessage(
/// channelIndex, ReceivedImageRef.encode(entry.streamId));
/// ```
///
/// Nothing is ever decoded for an outgoing entry: it lands in `decoded`
/// directly and never enters the queue, so sending an image costs no model
/// memory beyond the encode that already ran.
Future<ReceivedImageEntry> registerOutgoing({
required int channelIndex,
String? channelId,
required int senderPrefix,
required int imgId,
required Uint8List previewPng,
required AeicRatePoint rate,
required int chunkCount,
int aspectCode = 0,
DateTime? at,
}) async {
final now = at ?? _clock();
final streamId = _uniqueStreamId(
senderPrefix: senderPrefix,
imgId: imgId,
firstSeen: now,
);
// A failed write still shows the photo for this session (the bytes stay
// cached on the entry); the next launch then reports it as evicted rather
// than pointing at a file that was never written.
final pngWritten = await blobs.writePng(streamId, previewPng);
final entry = ReceivedImageEntry(
streamId: streamId,
senderPrefix: senderPrefix,
imgId: imgId,
channelIndex: channelIndex,
channelId: channelId,
firstSeen: now,
state: ReceivedImageState.decoded,
receivedChunks: chunkCount,
totalChunks: chunkCount,
rate: rate,
// The preview is the same stretched 512x512 square the receiver gets,
// so the sender's bubble needs the source shape to undo it too.
aspectCode: aspectCode,
metadataAssumed: false,
isOutgoing: true,
pngStored: pngWritten,
pngByteCount: pngWritten ? previewPng.length : 0,
pngBytes: previewPng,
);
final stored = await _store(entry);
await evictToBudget(protect: stored.streamId);
return stored;
}
// ---- decode scheduling ---------------------------------------------------
/// App lifecycle gate. Backgrounding cancels an in-flight decode and returns
/// the entry to `reassembled` — never to a failure state.
void setForeground(bool value) {
if (_foreground == value) return;
_foreground = value;
if (!value) {
// Only cancel OUR decode: the codec is shared with the send sheet, and an
// encode it is running is not this store's to stop.
if (_decodeInFlight) {
_backgroundCancelled = true;
decoder?.cancelCodecJob();
}
} else {
_parkedOnBusyDecoder = false;
_kick();
}
_notify();
}
/// Call when the codec's availability or busy flag changes: a queue parked on
/// a busy encoder resumes, and images that were parked as
/// `decoderUnavailable` get another go now that a decoder exists.
void notifyDecoderChanged() {
_parkedOnBusyDecoder = false;
final decoder = this.decoder;
if (decoder != null &&
decoder.availability == ImageCodecAvailability.ready) {
for (final entry in _entries.values.toList()) {
if (entry.state != ReceivedImageState.decoderUnavailable) continue;
if (!entry.bitstreamStored) continue;
_storeSync(
entry.copyWith(
state: ReceivedImageState.reassembled,
needsManualDecode: !processAutomatically,
),
);
// Without this guard, finishing an 835 MB download would immediately
// fire one decode per image received while the model was missing —
// exactly what the setting exists to prevent.
if (processAutomatically) _queue.add(entry.streamId);
}
}
_kick();
}
/// Cancels the running decode and stops the queue; the entry goes back to
/// `reassembled` and will be picked up again later.
Future<void> handleMemoryPressure() async {
_cancelRequested = true;
decoder?.cancelCodecJob();
_queue.clear();
for (final entry in _entries.values.toList()) {
if (entry.state == ReceivedImageState.reassembled &&
!entry.needsManualDecode) {
await _store(entry.copyWith(needsManualDecode: true));
}
}
}
/// User tapped "Decode" / "Try again" / "Decode again".
Future<void> requestDecode(String streamId) async {
final entry = _entries[streamId];
if (entry == null) return;
switch (entry.state) {
case ReceivedImageState.reassembled:
case ReceivedImageState.failedCorrupt:
case ReceivedImageState.decoderUnavailable:
case ReceivedImageState.evicted:
break;
case ReceivedImageState.receiving:
case ReceivedImageState.decoding:
case ReceivedImageState.decoded:
case ReceivedImageState.failedIncomplete:
return;
}
if (!entry.bitstreamStored) return;
await _store(
entry.copyWith(
state: ReceivedImageState.reassembled,
needsManualDecode: false,
error: null,
),
);
_parkedOnBusyDecoder = false;
_enqueue(streamId, force: true);
await settle();
}
/// Completes when the decode queue has stopped making progress. Test hook;
/// production code never needs to await it.
Future<void> settle() async {
var guard = 0;
while (guard++ < 1000) {
final pump = _pump;
if (pump != null) {
await pump;
continue;
}
if (_disposed ||
_queue.isEmpty ||
_draining ||
_parkedOnBusyDecoder ||
!_foreground) {
return;
}
_kick();
if (_pump == null) return;
}
}
void _enqueue(String streamId, {bool force = false}) {
if (_queue.contains(streamId)) return;
// A new arrival is worth one more look at a codec that was busy.
_parkedOnBusyDecoder = false;
_queue.add(streamId);
if (!force) {
// Burst cap: keep the newest `burstCap` requests, park the rest behind a
// tap so a repeater storm cannot spend minutes of CPU.
while (_queue.length > burstCap) {
final dropped = _queue.removeAt(0);
final entry = _entries[dropped];
if (entry != null && entry.state == ReceivedImageState.reassembled) {
_storeSync(entry.copyWith(needsManualDecode: true));
}
}
}
_kick();
}
void _kick() {
if (_disposed) return;
if (_queue.isEmpty) return;
if (_draining) return;
if (_parkedOnBusyDecoder) return;
_draining = true;
_pump = _drain().whenComplete(() {
_pump = null;
});
}
Future<void> _drain() async {
try {
while (_queue.isNotEmpty && _foreground && !_disposed) {
final decoder = this.decoder;
final streamId = _queue.first;
final entry = _entries[streamId];
if (entry == null || entry.state != ReceivedImageState.reassembled) {
_queue.removeAt(0);
continue;
}
if (decoder == null ||
decoder.availability != ImageCodecAvailability.ready) {
_queue.removeAt(0);
await _store(
entry.copyWith(state: ReceivedImageState.decoderUnavailable),
);
continue;
}
if (decoder.isBusy) {
// The compose UI is encoding. Leave the queue intact; the next
// notifyDecoderChanged()/chunk resumes it.
_parkedOnBusyDecoder = true;
return;
}
_queue.removeAt(0);
await _decodeOne(entry, decoder);
}
} finally {
// Synchronous with the end of the body, unlike the future's completion.
_draining = false;
}
}
/// Belt to [_draining]'s braces. A decode peaks around 2.16 GiB, so two at
/// once is not a slow app, it is an OOM kill. If this ever trips, the queue
/// invariant is broken somewhere and the right answer is still to run one.
bool _decodeInFlight = false;
Future<void> _decodeOne(
ReceivedImageEntry entry,
ReceivedImageDecoder decoder,
) async {
if (_decodeInFlight) {
assert(false, 'ReceivedImageStore: concurrent decode attempted');
debugPrint('received_image_store: refusing a concurrent decode');
_queue.remove(entry.streamId);
return;
}
_decodeInFlight = true;
try {
await _decodeOneExclusive(entry, decoder);
} finally {
_decodeInFlight = false;
}
}
Future<void> _decodeOneExclusive(
ReceivedImageEntry entry,
ReceivedImageDecoder decoder,
) async {
final bitstream = await blobs.readBitstream(entry.streamId);
// Every await below is a window in which the user may delete the image
// (message removed, channel cleared). Re-read the live entry after each
// one and stop if it is gone, or the decode would store it back.
final live = _entries[entry.streamId];
if (live == null) return;
if (bitstream == null || bitstream.isEmpty) {
await _store(
live.copyWith(
state: ReceivedImageState.failedCorrupt,
bitstreamStored: false,
error: 'Bitstream missing.',
),
);
return;
}
final started = _clock();
_cancelRequested = false;
_backgroundCancelled = false;
await _store(live.copyWith(state: ReceivedImageState.decoding));
ImageCodecResult? result;
Object? failure;
try {
result = await decoder.decodeBitstream(
bitstream: bitstream,
ratePoint: live.rate,
resolution: live.resolution,
);
} catch (error) {
failure = error;
}
final current = _entries[entry.streamId];
if (current == null) return;
final png = result?.pngBytes;
final completed =
failure == null &&
result != null &&
result.status == ImageCodecStatus.completed &&
png != null;
if (!completed) {
if (_cancelRequested) {
// Memory pressure: the codec reports a killed job as `failed`, but
// the bitstream is fine. Park it behind a tap.
await _store(
current.copyWith(
state: ReceivedImageState.reassembled,
needsManualDecode: true,
),
);
return;
}
if (_backgroundCancelled || !_foreground) {
// Backgrounded mid-decode: back to the front of the queue, so coming
// back to the app picks it up again.
await _store(current.copyWith(state: ReceivedImageState.reassembled));
if (!_queue.contains(current.streamId)) {
_queue.insert(0, current.streamId);
}
return;
}
if (failure == null && result == null) {
// canDecode false — the codec cannot run at all.
await _store(
current.copyWith(state: ReceivedImageState.decoderUnavailable),
);
return;
}
await _store(
current.copyWith(
state: ReceivedImageState.failedCorrupt,
error: failure?.toString() ?? 'Decoder rejected the bitstream.',
),
);
return;
}
// A completed result is a finished decode even if the app went to the
// background in the meantime; throwing the pixels away would only make
// the user wait for a second 2 GiB run.
final written = await blobs.writePng(current.streamId, png);
final afterWrite = _entries[entry.streamId];
if (afterWrite == null) {
await blobs.deletePng(current.streamId);
return;
}
await _store(
afterWrite.copyWith(
state: ReceivedImageState.decoded,
// A failed write keeps the pixels cached for this session; the next
// launch reports the image as evicted ("Decode again") instead.
pngStored: written,
pngByteCount: written ? png.length : 0,
pngBytes: png,
decodeMs: result.durationMs > 0
? result.durationMs
: _clock().difference(started).inMilliseconds,
needsManualDecode: false,
error: null,
),
);
// Without `protect` the freshly decoded image is the budget's own victim
// whenever it is also the oldest: decode -> evict -> "Decode again" ->
// evict, forever.
await evictToBudget(protect: afterWrite.streamId);
}
// ---- pixels --------------------------------------------------------------
/// Reads (and caches) the decoded PNG for a `decoded` entry. Returns null for
/// every other state, so a failed or corrupt image can never present as
/// decoded pixels.
Future<Uint8List?> ensurePng(String streamId) async {
final entry = _entries[streamId];
if (entry == null) return null;
if (entry.state != ReceivedImageState.decoded) return null;
final cached = entry.pngBytes;
if (cached != null) return cached;
if (!entry.pngStored) return null;
final bytes = await blobs.readPng(streamId);
if (bytes == null) {
await _store(
entry.copyWith(state: ReceivedImageState.evicted, pngStored: false),
);
return null;
}
await _store(entry.copyWith(pngBytes: bytes, pngByteCount: bytes.length));
return bytes;
}
/// Absolute PNG path, for a share/save action. Null on platforms with no file
/// system, and null unless the entry is decoded.
String? pngPath(String streamId) {
final entry = _entries[streamId];
if (entry == null || entry.state != ReceivedImageState.decoded) return null;
return blobs.pngPath(streamId);
}
// ---- deletion and eviction ----------------------------------------------
/// Removes an image and all three of its files. Called when the user deletes
/// the message (or clears the conversation), otherwise ~400 KB is orphaned
/// forever.
Future<void> deleteImage(String streamId) async {
final entry = _entries.remove(streamId);
_queue.remove(streamId);
// Only unlink the key if it still points here: a newer image reusing the
// same sender/id/channel owns it now, and losing that mapping strands the
// newer one on "receiving" while its next chunk opens a third entry.
if (entry != null && _byKey[entry.key] == streamId) {
_byKey.remove(entry.key);
}
await blobs.deletePng(streamId);
await blobs.deleteBitstream(streamId);
await blobs.deleteSidecar(streamId);
final listenable = _listenables[streamId];
if (listenable != null) {
listenable.value = null;
}
_notify();
}
/// Deletes every image of one channel. Call this when the conversation is
/// cleared or the channel removed, otherwise each image leaks ~400 KB until
/// the 30-day age budget finally reaps it.
///
/// Returns the stream ids that were removed, so the caller can strip their
/// sentinels from the channel's message list in one pass.
Future<List<String>> deleteImagesForChannelId(String channelId) async {
final doomed = _entries.values
.where((e) => e.channelId == channelId)
.map((e) => e.streamId)
.toList();
for (final streamId in doomed) {
await deleteImage(streamId);
}
return doomed;
}
/// Images of [channelId], newest first.
List<ReceivedImageEntry> entriesForChannel(String? channelId) {
if (channelId == null) return const <ReceivedImageEntry>[];
return entries.where((e) => e.channelId == channelId).toList();
}
/// Gives entries saved before channel IDs existed the ID of the channel
/// their slot held then ([slotIds], from the radio's cached channel list).
/// The store is app-wide, so with several radios the first one migrated
/// claims the unstamped images.
Future<void> stampLegacyChannelIds(Map<int, String> slotIds) async {
for (final entry in _entries.values.toList()) {
if (entry.channelId != null) continue;
final channelId = slotIds[entry.channelIndex];
if (channelId == null) continue;
await _store(entry.copyWith(channelId: channelId));
}
}
/// Forgets which in-progress streams arrived on [channelIndex] after the
/// radio slot was given to another channel, so a new image on that slot
/// never continues an old one.
void forgetChannelSlot(int channelIndex) {
_byKey.removeWhere((key, _) => key.channelIndex == channelIndex);
}
/// Deletes an image for each sentinel that is still present in a channel's
/// message list, and drops everything else this store holds for that channel.
///
/// Convenience for the single-message delete path: the caller has a
/// `ChannelMessage.text`, not a stream id.
Future<void> deleteImageForSentinel(String text) async {
final streamId = ReceivedImageRef.parse(text);
if (streamId == null) return;
await deleteImage(streamId);
}
/// Brings the store back inside [maxImages] / [maxBytes] / [maxAge].
///
/// Order matters: PNGs (~400 KB) go before bitstreams (~156 B), and oldest
/// `firstSeen` first. An evicted entry keeps its message and its
/// `evicted` state so the bubble can offer "Decode again".
Future<List<String>> evictToBudget({String? protect}) async {
final evicted = <String>[];
final now = _clock();
// 1. Age budget: nothing survives, not even the bitstream. A failed image
// has no bubble worth keeping, so it goes entirely, sidecar included.
for (final entry in _entries.values.toList()) {
if (now.difference(entry.firstSeen) <= maxAge) continue;
if (entry.state.isFailure) {
await deleteImage(entry.streamId);
evicted.add(entry.streamId);
continue;
}
if (!entry.pngStored && !entry.bitstreamStored) continue;
await blobs.deletePng(entry.streamId);
await blobs.deleteBitstream(entry.streamId);
await _store(
entry.copyWith(
state: ReceivedImageState.evicted,
pngStored: false,
bitstreamStored: false,
pngBytes: null,
),
);
_queue.remove(entry.streamId);
evicted.add(entry.streamId);
}
// 2. Size/count budget.
var guard = 0;
while ((storedImageCount > maxImages || totalBytes > maxBytes) &&
guard++ < 10000) {
final pngHolders =
_entries.values
.where((e) => e.pngStored && e.streamId != protect)
.toList()
..sort((a, b) => a.firstSeen.compareTo(b.firstSeen));
if (pngHolders.isNotEmpty) {
final victim = pngHolders.first;
await blobs.deletePng(victim.streamId);
await _store(
victim.copyWith(
state: victim.state == ReceivedImageState.decoded
? ReceivedImageState.evicted
: victim.state,
pngStored: false,
pngBytes: null,
),
);
evicted.add(victim.streamId);
continue;
}
// Only bitstreams of already-evicted entries may go; a `reassembled`
// entry still needs its bytes to decode.
final bitstreamHolders =
_entries.values
.where(
(e) =>
e.bitstreamStored &&
(e.state == ReceivedImageState.evicted ||
e.state == ReceivedImageState.failedCorrupt),
)
.toList()
..sort((a, b) => a.firstSeen.compareTo(b.firstSeen));
if (bitstreamHolders.isEmpty) break;
final victim = bitstreamHolders.first;
await blobs.deleteBitstream(victim.streamId);
await _store(
victim.copyWith(
state: ReceivedImageState.evicted,
bitstreamStored: false,
),
);
evicted.add(victim.streamId);
}
// 3. Failed entries hold no PNG, so the loop above never counts them; cap
// them by entry count, oldest first, or a noisy mesh grows the sidecars
// (and the startup load) without bound.
if (_entries.length > maxImages) {
final failures =
_entries.values
.where((e) => e.state.isFailure && e.streamId != protect)
.toList()
..sort((a, b) => a.firstSeen.compareTo(b.firstSeen));
for (final victim in failures) {
if (_entries.length <= maxImages) break;
await deleteImage(victim.streamId);
evicted.add(victim.streamId);
}
}
evicted.addAll(await _enforceEntryCap(protect: protect));
if (evicted.isNotEmpty) _notify();
return evicted;
}
/// Brings the entry count inside [maxEntries], oldest first: failures, then
/// entries with nothing left on disk, then undecoded incoming images. Never
/// touches an outgoing image that still has data on disk, a running decode
/// or a stream still receiving.
Future<List<String>> _enforceEntryCap({String? protect}) async {
final removed = <String>[];
if (_entries.length <= maxEntries) return removed;
int rank(ReceivedImageEntry e) {
if (e.state.isFailure) return 0;
if (e.state == ReceivedImageState.evicted && !e.bitstreamStored) {
return 1;
}
return 2;
}
final victims =
_entries.values
.where(
(e) =>
e.streamId != protect &&
// An outgoing image may go once nothing of it is left on
// disk (age eviction only marks it evicted), or it failed;
// otherwise frequent senders grow sidecars without bound.
(!e.isOutgoing ||
e.state.isFailure ||
(e.state == ReceivedImageState.evicted &&
!e.pngStored &&
!e.bitstreamStored)) &&
(e.state.isFailure ||
e.state == ReceivedImageState.evicted ||
e.state == ReceivedImageState.reassembled ||
e.state == ReceivedImageState.decoderUnavailable),
)
.toList()
..sort((a, b) {
final byRank = rank(a).compareTo(rank(b));
return byRank != 0 ? byRank : a.firstSeen.compareTo(b.firstSeen);
});
for (final victim in victims) {
if (_entries.length <= maxEntries) break;
await deleteImage(victim.streamId);
removed.add(victim.streamId);
}
return removed;
}
// ---- plumbing ------------------------------------------------------------
String _uniqueStreamId({
required int senderPrefix,
required int imgId,
required DateTime firstSeen,
}) {
// Second-resolution ids collide when the same sender reuses an img_id
// inside one second (id wrap, or a restart re-rolling the allocator seed).
var at = firstSeen;
var id = ReceivedImageRef.streamIdFor(
senderPrefix: senderPrefix,
imgId: imgId,
firstSeen: at,
);
var bump = 0;
while (_entries.containsKey(id) && bump++ < 64) {
at = at.add(const Duration(seconds: 1));
id = ReceivedImageRef.streamIdFor(
senderPrefix: senderPrefix,
imgId: imgId,
firstSeen: at,
);
}
return id;
}
Future<ReceivedImageEntry> _store(ReceivedImageEntry entry) async {
_storeSync(entry);
await _persist(entry);
return entry;
}
void _storeSync(ReceivedImageEntry entry) {
_entries[entry.streamId] = entry;
_claimKey(entry);
_publish(entry);
_notify();
}
/// Points the entry's key at it unless a newer image already holds the key.
/// Updating an old entry (eviction, a late decode) must not steal the key
/// back from a newer stream that reused the same 8-bit id.
void _claimKey(ReceivedImageEntry entry) {
final holderId = _byKey[entry.key];
if (holderId != null && holderId != entry.streamId) {
final holder = _entries[holderId];
if (holder != null && holder.firstSeen.isAfter(entry.firstSeen)) {
return;
}
}
_byKey[entry.key] = entry.streamId;
}
Future<void> _persist(ReceivedImageEntry entry) async {
try {
await blobs.writeSidecar(entry.streamId, jsonEncode(entry.toJson()));
} catch (error) {
debugPrint('received_image_store: sidecar write failed: $error');
}
}
void _publish(ReceivedImageEntry entry) {
final listenable = _listenables[entry.streamId];
if (listenable != null) {
listenable.value = entry;
}
}
void _notify() {
if (_disposed) return;
notifyListeners();
}
@override
void dispose() {
_disposed = true;
_queue.clear();
for (final listenable in _listenables.values) {
listenable.dispose();
}
_listenables.clear();
super.dispose();
}
}