Virtual Tar PoC

This repository contains a minimal Go proof of concept that serves a stable virtual tar stream at /archive.tar from a fixed manifest snapshot. It precomputes ustar headers and offsets at startup, then serves archive bytes from planned metadata plus direct source streaming.

Running the PoC

• Start cmd/virtual-tar-poc from the repository root (or this worktree root). cmd/virtual-tar-poc/main.go resolves the shipped testdata/manifest.json from the checked-out source tree.
• The shipped testdata/manifest.json proves the local-file path with source_path: "files/alpha.txt", so the primary demo runs without a second upstream server.
• Run go run ./cmd/virtual-tar-poc, then fetch http://127.0.0.1:8080/archive.tar from another shell with curl -fsS http://127.0.0.1:8080/archive.tar -o /tmp/virtual-tar-poc.tar, tar -tvf /tmp/virtual-tar-poc.tar, and tar -xOf /tmp/virtual-tar-poc.tar alpha.txt.
• HEAD /archive.tar does not fetch source bytes. Full GET /archive.tar and data-covering single-range requests do.
• source_url remains available for focused HTTP compatibility tests.

Architecture

• internal/poc/tar.go precomputes ustar headers, entry offsets, and segment layout once at startup.
• internal/poc/handler.go plans the requested archive window and streams each segment directly into the HTTP response.
• internal/poc/file_source.go is the primary proof backend and copies exact byte windows from local files.
• internal/poc/source.go routes each entry to either the local-file backend or the HTTP compatibility backend.

Scope

• Supports HEAD, full GET, and single Range GET
• Returns 416 for invalid or unsatisfied ranges
• Returns 501 for multi-range requests
• Emits regular-file ustar entries only

Not in scope

• PAX headers
• Directory or link entries
• Multi-range response bodies
• Live source mutation handling
• Prebuilt archive files or background cleanup
• Platform-specific zero-copy branches