tarprism

README

tar-prism

Splits an uncompressed tar archive into two parts and puts it back together byte for byte:

• recipe — every byte that is not regular-file content: headers, PAX and GNU meta entries, block padding, the end-of-archive marker, trailing padding. Kept verbatim, in order.
• blobs — the content of each regular file, numbered in archive order.

Together they form a prism directory:

prism/
  recipe.bin        non-content bytes of the archive, verbatim
  recipe.json       splice offsets, sizes, names, and the BLAKE3 digest of the archive
  blobs/00000001    content of the 1st regular file
  blobs/00000002    content of the 2nd regular file
  ...

Composing a prism reproduces the original archive exactly and verifies the result against the recorded BLAKE3 digest.

CLI

tar-prism decompose <input.tar|-> <prism-dir>
tar-prism compose   <prism-dir> <output.tar|->

- reads the archive from stdin or writes it to stdout. decompose refuses a non-empty target directory. compose overwrites an existing output file. If compose fails, the output file may be partial or unverified; trust it only when the command exits with status 0. Only uncompressed archives are supported; decompress .tar.gz and friends first.

Library

import tarprism "github.com/draganm/tar-prism"

err := tarprism.Decompose(reader, "prism")   // tar in, prism directory out
err  = tarprism.Compose("prism", writer)     // prism directory in, identical tar out
idx, err := tarprism.ReadIndex("prism")      // inspect recipe.json

Development

nix develop            # Go and GNU tar from nixpkgs (direnv: `direnv allow`)
go test ./...

The tests round-trip archives written by Go's archive/tar, by GNU tar and bsdtar when available, and hand-built block sequences covering GNU sparse entries, PAX size overrides, bogus hard-link sizes, and truncated input.

License

tar-prism is licensed under the GNU Affero General Public License, version 3 or later; see LICENSE.

Documentation

Overview

Package tarprism splits an uncompressed tar archive into a recipe (every byte that is not regular-file content, kept verbatim) and numbered blobs (the file contents), and reassembles the byte-identical archive from them.

Index

• Constants
• func Compose(dir string, w io.Writer) error
• func Decompose(r io.Reader, dir string) error
• type Entry
• type Index
  • func ReadIndex(dir string) (*Index, error)

Constants

const (
	RecipeFile = "recipe.bin"
	IndexFile  = "recipe.json"
	BlobsDir   = "blobs"
)

Files and directories that make up a prism directory.

const FormatVersion = 1

FormatVersion is the recipe.json version written by Decompose and accepted by Compose.

Functions

func Compose

func Compose(dir string, w io.Writer) error

Compose reads the prism in dir and writes the original archive to w. The output is verified against the BLAKE3 digest recorded at decompose time; on a mismatch the (already written) output must not be trusted.

func Decompose

func Decompose(r io.Reader, dir string) error

Decompose reads an uncompressed tar archive from r and writes a prism into dir: recipe.bin, recipe.json, and blobs/. dir must not exist or must be empty. On error the partially written directory is left in place.

Types

type Entry

type Entry struct {
	// Name is the entry's name in the archive, for human readers only.
	Name string `json:"name"`
	// Offset is the byte position in recipe.bin where the blob is spliced in.
	Offset int64 `json:"offset"`
	// Size is the blob's length in bytes.
	Size int64 `json:"size"`
	// Blob is the blob's path relative to the prism directory, slash-separated.
	Blob string `json:"blob"`
}

Entry describes one regular-file blob.

type Index

type Index struct {
	Version int     `json:"version"`
	BLAKE3  string  `json:"blake3"`
	Entries []Entry `json:"entries"`
}

Index is the content of recipe.json: where each blob is spliced back into the recipe, and the BLAKE3 digest of the original archive.

func ReadIndex

func ReadIndex(dir string) (*Index, error)

ReadIndex parses and validates <dir>/recipe.json.