archive

func (*Provider) CompensateExtract ¶

func (p *Provider) CompensateExtract(activation *op.ActivationRecord, stack *op.RecoveryStack) error

CompensateExtract undoes a Provider.Extract by unwinding its recovery stack.

Extract returns a op.RecoveryStack holding one self-describing file.Receipt per created file or directory. Unwinding it compensates each in reverse order — removing created files and directories and restoring any prior content archived to op.RecoverySite — so the filesystem returns to its pre-extraction state.

Parameters:

• `activation`: the per-dispatch record; supplies the *op.RuntimeEnvironment passed to op.RecoveryStack.Unwind.
• `stack`: the recovery stack Provider.Extract returned as its compensator; a nil stack returns nil.

Returns:

• `error`: the joined errors from the per-entry compensations, or nil when all succeed.

func (*Provider) CompensateExtractStream ¶

func (p *Provider) CompensateExtractStream(activation *op.ActivationRecord, stack *op.RecoveryStack) error

CompensateExtractStream undoes a Provider.ExtractStream by unwinding its recovery stack.

Identical to Provider.CompensateExtract — the stream and disk paths share the receipt machinery — and paired by name so the compensator index routes stream extractions here.

Parameters:

• `activation`: the per-dispatch record; supplies the *op.RuntimeEnvironment passed to Unwind.
• `stack`: the *op.RecoveryStack returned by Provider.ExtractStream; a nil stack is a no-op.

Returns:

• `error`: non-nil when unwinding any recorded compensation fails.

func (*Provider) Extract ¶

func (p *Provider) Extract(
	activationRecord *op.ActivationRecord,
	source *file.Regular,
	prefixPath string,
) (products []file.Resource, stack *op.RecoveryStack, err error)

Extract extracts an archive from `source` into the directory at `prefixPath`.

The prefix directory must already exist as a directory — Extract does not create it; callers are responsible for arranging the prefix (e.g., via plan.file.mkdir upstream). This mirrors the semantics of the tar(1) -C flag, which fails if the target directory is missing. Extract returns an error when `prefixPath` does not exist or exists but is not a directory. The archive format is detected from the file's leading bytes — its compression or container magic — never from its name: gzip-compressed tar, plain (ustar) tar, and zip extract today, while the bzip2, xz, and zstd magics are recognized but rejected until their decompressors land.

Each entry is materialized through the file provider's unified mutation surface — a directory via file.Provider.Mkdir and a regular file via file.Provider.WriteFile, which streams the body with io.Copy (constant memory) and archives any displaced prior content to op.RecoverySite. Every call yields a self-describing file.Receipt that names file.Provider.CompensateFileMutation as its undo; Extract commits each receipt and pushes it onto a single op.RecoveryStack, so a failure mid-extraction returns the partial stack and the saga boundary unwinds it before any retry. Compensation removes created files and directories and restores displaced content from recovery.

Parameters:

• `activationRecord`: the per-dispatch activation; its `Unit` stamps the producer of every interned file.Resource and the `forwardAction` of every receipt.
• `source`: file.Regular identifying the archive file; the format is read from its content at dispatch time.
• `prefixPath`: the extraction directory path. Must exist as a directory; Extract does not create it.

Returns:

• `[]file.Resource`: one entry per file the extraction created or replaced, in extraction order.
• `*op.RecoveryStack`: a recovery stack carrying one self-describing file.Receipt per created file or directory, in extraction order, so a failed run unwinds it in reverse.
• `error`: any error from format detection, extraction, archive-on-displace, or catalog/receipt construction.

+devlore:claim=sandboxed

func (*Provider) ExtractStream ¶

func (p *Provider) ExtractStream(
	activationRecord *op.ActivationRecord,
	src io.Reader,
	prefixPath string,
) (products []file.Resource, stack *op.RecoveryStack, err error)

ExtractStream extracts an archive arriving as a forward-only byte stream into the existing directory `prefixPath`.

The stream counterpart of Provider.Extract (§10 ruling 5's sanctioned add): the leading bytes are sniffed for the format magic and stitched back onto the stream, the tar family extracts stream-natively, and a zip — whose authoritative central directory sits at the end of the file — spools to a temporary file and takes the same random-access path as a disk zip (one zip reader, one authority). Everything downstream — the entry-kind dispatch, the containment guard, receipts, and compensation — is shared with Extract; the returned stack unwinds via Provider.CompensateExtractStream.

Parameters:

• `activationRecord`: the dispatch activation; its `Unit` stamps every produced entry's producerID and the `forwardAction` of every receipt.
• `src`: the archive bytes, consumed exactly once from the current position.
• `prefixPath`: the existing directory the archive extracts into.

Returns:

• `[]file.Resource`: one entry per file, symlink, or hardlink copy the extraction created or replaced.
• `*op.RecoveryStack`: one self-describing file.Receipt per created entry, in extraction order.
• `error`: any error from sniffing, spooling, extraction, or receipt construction.

+devlore:claim=sandboxed