open static method

Future<JsonlSessionStorage> open(
  1. FileSystem fs,
  2. String filePath, {
  3. SessionParseExecutor? parseExecutor,
  4. SessionIoRetryConfig ioRetry = const SessionIoRetryConfig(),
  5. SessionTimingLogger? timingLog,
  6. int maxFullOpenBytes = defaultMaxFullOpenBytes,
  7. bool wholeFileOnly = false,
})

Opens an existing session file.

Malformed lines — a torn crash-write at ANY position (torn last line, or a hole mid-file left by racing writers) — never fail the open: they are quarantined verbatim into a <file>.corrupt sidecar and dropped, and the main file is rewritten from the surviving records so every later open/append sees whole JSONL. The number of quarantined lines is reported through quarantinedEntries.

A ranged fs opens through the streamed scan (gh-1073 — no segment is ever materialized as one String); wholeFileOnly forces the classic whole-file read instead. That flag exists for error-recovery fallbacks: when the caller just watched a ranged read fail, retrying over the same capability is unsound — the fallback must load through plain whole-file reads only.

Implementation

static Future<JsonlSessionStorage> open(
  FileSystem fs,
  String filePath, {
  SessionParseExecutor? parseExecutor,
  SessionIoRetryConfig ioRetry = const SessionIoRetryConfig(),
  SessionTimingLogger? timingLog,
  int maxFullOpenBytes = defaultMaxFullOpenBytes,
  bool wholeFileOnly = false,
}) async {
  final sw = Stopwatch()..start();
  final storage = await withSessionFileLock(
    filePath,
    () => _openLocked(
      fs,
      filePath,
      parseExecutor,
      ioRetry,
      timingLog,
      maxFullOpenBytes,
      wholeFileOnly,
    ),
  );
  timingLog?.call(
    'resume_timing open file=${filePath.split('/').last} '
    'mode=full lock_wait_ms=${sw.elapsedMilliseconds - storage._openInnerMs} '
    'total_ms=${sw.elapsedMilliseconds}',
  );
  return storage;
}