transfer
Downloads, uploads, packs, and safely extracts artifacts.
get accepts a local path or an HTTP(S) URL. URL responses are cached under
the application cache directory and revalidated with HTTP validators when
available. Pass digest: as algorithm:hex to verify an artifact; a cache
entry already verified against that digest can be reused without a request.
pack supports TAR, gzip-compressed TAR, Zstandard-compressed TAR, and ZIP.
unpack additionally decompresses raw gzip, Zstandard, and XZ streams into a
file. It distinguishes compressed TAR archives from raw streams by filename:
for example, .tar.gz selects TAR while .gz selects a raw stream. Raw
decompression requires the corresponding gzip, zstd, or xz program.
Archive extraction first validates the complete manifest, rejects unsafe or conflicting paths, and writes into a staging directory before publishing the destination. Raw decompression also stages its output before publication.
Types
| Type | Description |
|---|---|
ArchiveError |
Raised when unpacking a raw compressed stream (gzip, Zstandard, XZ) fails. |
Functions
get source :app? :digest? :policy? :cache?
Resolves a local path or downloads an HTTP(S) URL into the application cache.
digest uses algorithm:hex syntax. Supported algorithms are BLAKE3, MD5,
SHA-1, SHA-256, and SHA-512. A previously verified digest-pinned entry is
returned without contacting the server.
cache overrides the cache location with an explicit directory, bypassing
app/fs.cache_dir entirely. Mainly useful for tests that want an
isolated, disposable cache root.
policy is reserved and must be nil.
put source destination :headers?
Copies or uploads source to destination.
URL sources are resolved through get.
headers applies only to HTTP(S) destinations.
pack source destination :format? :prefix? ...metadata
Packs a file or directory into TAR, compressed TAR, or ZIP.
Directory contents are relative to the source root. prefix prepends a safe
relative path to every archive entry.
unpack source destination :format? :strip? :app?
Safely extracts an archive or decompresses a single file into a new destination.
For archives, strip accepts a non-negative component count or :ROOT:.
Raw gzip, Zstandard, and XZ streams require strip: 0 and produce a file.