Skip to content

Expose stream, seek, and span archive input modes - #373

Merged
Hawkynt merged 10 commits into
mainfrom
feat/archive-input-modes
Sep 19, 2026
Merged

Hawkynt merged 10 commits into
mainfrom
feat/archive-input-modes

Conversation

@Hawkynt

@Hawkynt Hawkynt commented Sep 15, 2026

Copy link
Copy Markdown
Owner

What changed

  • Added explicit *Streaming, *Seekable, and *Span read/list/extract entry points to IArchiveFormatOperations.
  • Kept the existing Stream methods as the compatibility/native descriptor hooks, so every existing archive and pseudo-archive gains all three source modes without duplicating adapter code.
  • Added a large-file-safe bridge for legacy seek-only readers: forward-only input is spooled to a delete-on-close temporary file rather than buffered into a managed array.
  • Added ownership wrapping so a spool or span-backed compatibility buffer stays alive for the lifetime of a returned entry stream.
  • Added extension methods so default interface members are also ergonomic when descriptors are referenced by their concrete type.
  • Added registry-level NUnit tests using an intentionally seek-only fake descriptor to prove the universal fallbacks rather than one format-specific implementation.

Design decisions

Libarchive was used as architectural reference, not as implementation source. Its archive-read API treats forward reads as the primary callback, exposes seek separately, and supports memory-backed input. CompressionWorkbench now exposes the same three input shapes at the common archive/pseudo-archive boundary while preserving existing descriptor implementations.

The compatibility streaming path does not pretend a legacy random-access parser is genuinely one-pass: it spools only when the caller supplies a non-seekable stream. Formats with true sequential parsers can override ListStreaming, ExtractStreaming, and OpenEntryStreaming. Native random-access parsers can override the *Seekable path, and native span parsers can override ListSpan, ExtractSpan, and OpenEntrySpan to avoid the compatibility copy.

The span API uses explicit *Span names instead of overloads. An initial overload design made existing XML references to IArchiveFormatOperations.List ambiguous throughout the repository; explicit mode names preserve source/documentation compatibility and make the three source capabilities obvious at call sites.

No new dependencies were introduced. No libarchive source code was copied or translated.

Reference material

  • libarchive archive.h read/skip/seek callback contract
  • libarchive project documentation describing callback-driven stream and memory access
  • libarchive BSD license reviewed for provenance; only public API behavior/architecture was consulted

Validation

  • Repository README check: green on current CI run.
  • Ubuntu Release build: green on current CI run.
  • Windows build and the remaining test/interop/package checks are still running on the current head.
  • Earlier CI iterations caught and drove fixes for malformed XML cref syntax and the ambiguous span-overload design.

@Hawkynt
Hawkynt force-pushed the feat/archive-input-modes branch 7 times, most recently from a63779c to adbc8c3 Compare September 19, 2026 03:18
@Hawkynt
Hawkynt force-pushed the feat/archive-input-modes branch from adbc8c3 to 6eacce5 Compare September 19, 2026 03:45
@Hawkynt
Hawkynt merged commit f264703 into main Sep 19, 2026
5 checks passed
@Hawkynt
Hawkynt deleted the feat/archive-input-modes branch September 19, 2026 04:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant