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. |
PackOptions |
Options for pack that override what the filesystem reports
for each entry. |
UnpackFormat |
An input format unpack reads: an archive, or a raw
compressed stream. |
ArchiveFormat
An archive format pack writes.
| Type | Description |
|---|---|
:TAR: |
Uncompressed TAR |
:TAR_GZIP: |
gzip-compressed TAR |
:TAR_ZSTD: |
Zstandard-compressed TAR |
:ZIP: |
ZIP |
PackOptions
Options for pack that override what the filesystem reports
for each entry.
| Item | Type | Description |
|---|---|---|
?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. |
UnpackFormat
An input format unpack reads: an archive, or a raw
compressed stream.
| Type | Description |
|---|---|
ArchiveFormat |
Any ArchiveFormat |
: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 ...options … -> 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. |
...options |
PackOptions |
Overrides for the metadata of each entry. |
: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? |
BaseDict[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.
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.