transfer
Downloads, uploads, packs, and safely extracts artifacts.
A URL source is resolved through get wherever one is accepted, so its cache
serves put, pack, and unpack as well.
Results are published atomically: output is staged and renamed into place, so an interrupted operation leaves no partial destination behind.
Types
| Type | Description |
|---|---|
ArchiveError |
Raised when unpacking a raw compressed stream (gzip, Zstandard, XZ) fails. |
ArchiveFormat |
An archive format pack writes. |
UnpackFormat |
An input format unpack reads: an archive, or a raw
compressed stream. |
ArchiveFormat = (:TAR: | :TAR_GZIP: | :TAR_ZSTD: | :ZIP:)
An archive format pack writes.
| Value | Meaning |
|---|---|
:TAR: |
Uncompressed TAR |
:TAR_GZIP: |
gzip-compressed TAR |
:TAR_ZSTD: |
Zstandard-compressed TAR |
:ZIP: |
ZIP |
UnpackFormat = (ArchiveFormat | :GZIP: | :ZSTD: | :XZ:)
An input format unpack reads: an archive, or a raw
compressed stream.
| Value | Meaning |
|---|---|
:GZIP: |
Raw gzip stream |
:ZSTD: |
Raw Zstandard stream |
:XZ: |
Raw XZ stream |
Functions
get source … -> fs.Path
Resolves a local path or downloads an HTTP(S) URL into the application cache.
A cached response is revalidated with whatever validators the server supplied for it. An interrupted download is kept and resumed with a range request on the next call, falling back to a full download when the server ignores the range or the representation has changed.
Parameters
| Name | Type | Description |
|---|---|---|
source |
(Str | url.Url | fs.Path) |
Local path or HTTP(S) URL to resolve. |
:app? |
Str |
Application name selecting the cache directory. |
:digest? |
Str |
Expected digest, as algorithm:hex. |
:cache? |
(Str | fs.Path) |
Explicit cache directory. |
:app
Defaults to the name of the running program. Not valid together with
cache.
:digest
Supported algorithms are BLAKE3, MD5, SHA-1, SHA-256, and SHA-512. An entry already verified against the digest is returned without contacting the server.
:cache
Bypasses app and fs.cache_dir entirely, and is not valid together with
app. Mainly useful for tests that want an isolated, disposable cache
root.
pack source destination … -> nil
Packs a file or directory into TAR, compressed TAR, or ZIP.
Directory contents are relative to the source root.
Parameters
| Name | Type | Description |
|---|---|---|
source |
(Str | url.Url | fs.Path) |
File or directory to pack. |
destination |
(Str | url.Url | fs.Path) |
Archive to write. |
:format? |
ArchiveFormat |
Archive format. |
:prefix? |
(Str | fs.Path) |
Relative path prepended to every archive entry. |
:mode? |
(Int | fs.unix.Mode) |
Permissions for regular
files. Defaults to the source mode, or 0o644 when unavailable. |
:dir_mode? |
(Int | fs.unix.Mode) |
Permissions for
directories. Defaults to the source mode, or 0o755 when unavailable. |
:link_mode? |
(Int | fs.unix.Mode) |
Permissions for
symlinks. Defaults to the source mode, or 0o777 when unavailable. |
:uid? |
Int |
Owner ID. Defaults to the source owner, or 0 when
unavailable. |
:gid? |
Int |
Group ID. Defaults to the source group, or 0 when
unavailable. |
:owner_name? |
Str |
Owner name. Defaults to the source owner's qualified name when it can be looked up. |
:group_name? |
Str |
Group name. Defaults to the source group's qualified name when it can be looked up. |
:mtime? |
time.DateTime |
Modification time. Defaults to the source modification time, or the Unix epoch when unavailable. |
:format
Inferred from the destination name when omitted, which fails if the name carries no recognized extension.
put source destination … -> nil
Copies or uploads source to destination.
Parameters
| Name | Type | Description |
|---|---|---|
source |
(Str | url.Url | fs.Path) |
Local path or HTTP(S) URL to copy from. |
destination |
(Str | url.Url | fs.Path) |
Local path or HTTP(S) URL to write to. |
:headers? |
Dict[Str | Sym, Str] |
Request headers for an HTTP(S) destination. |
source
A URL is resolved through get first.
:headers
Only valid for an HTTP(S) destination.
unpack source destination … -> nil
Safely extracts an archive or decompresses a single file into a new destination.
Extraction validates the whole manifest before writing anything, rejecting
unsafe or conflicting paths. Raw decompression runs the corresponding gzip,
zstd, or xz program.
Parameters
| Name | Type | Description |
|---|---|---|
source |
(Str | url.Url | fs.Path) |
Archive or compressed file to extract. |
destination |
(Str | fs.Path) |
Path to create. |
:format? |
UnpackFormat |
Input format. |
:strip? |
(Int | :ROOT:) |
Leading path components to strip from each entry. |
:app? |
Str |
Application name selecting the cache directory, for a URL source. |
destination
Must not already exist, and may not be a URL.
:format
Inferred from the source name when omitted. A compressed TAR archive is
distinguished from a raw stream by filename: .tar.gz selects
:TAR_GZIP: while .gz selects :GZIP:.
:strip
:ROOT: strips one component, and requires a non-empty archive whose
entries share a single root component. Raw streams require 0.