fetch library

Downloads and archives: the "download and add" half of installing a package, shared by just and its plugins.

  • HttpFetcher: HTTPS only (every redirect too, and each one checked by the caller's own RedirectCheck when it passes one), parts of a file (ByteRange), polite retries, limits, every failure a FetchException, and CachedText that still reads offline.
  • DownloadCache and checkPinned: downloads pinned by size and SHA-256, kept per user.
  • GitHubRepo: where a repository's release files are, without the rate-limited GitHub API.
  • ZipArchive reads a zip, refusing anything a tool should never unpack (paths outside the folder, links, ZIP64, bombs); ZipWriter writes one the same way every time. SafePaths holds the path rules both follow.
  • CancelToken stops any of it.

Classes

ByteRange
A part of a file to fetch: an HTTP Range of bytes, so a tool can read a zip's directory, or one file in it, without downloading all of it.
CachedText
Text fetched through an on-disk copy: fresh when the server answered, the cached copy when it said "unchanged" — or, offline, when it could not be reached at all or sent something unreadable.
CancelToken
A request to stop a download or an install, checked between steps.
DownloadCache
A per-user cache shared by every project on this machine: archives stored under their SHA-256, so a version downloaded once installs anywhere without the network. What else a tool keeps in dir is its own; sizeInBytes and clear count it too.
FetchResponse
What a server answered.
GitHubRepo
A GitHub repository, as https://github.com/<owner>/<repo> names it.
HashedFiles
Files named by the SHA-256 of their bytes, in one folder: archives, catalog pieces, anything pinned. Every read checks the bytes again, so a damaged or replaced copy is never used — it is deleted, and reads as missing.
HttpFetcher
Fetches files over HTTPS.
JsonFields
A JSON object read field by field, each read naming its path when it fails. Unknown fields are ignored, so newer files still read.
PackageNames
Rules for package names (pub's) and the names written into generated code.
SafePaths
Checks paths from untrusted archives so they can only ever land inside the folder they are extracted to, on every desktop platform.
Sha256
A running SHA-256 hash: add the data in pieces, then close.
Version
A semantic version (semver 2.0): 1.2.3, 1.2.3-dev.4, 1.2.3+5.
VersionConstraint
Which versions are acceptable, written the way pubspecs write it: any, 1.2.3, ^1.2.3, >=1.0.0 <2.0.0.
ZipArchive
A ZIP archive read fully into memory and checked before any file in it is unpacked.
ZipDirectory
A ZIP archive's directory, read from the end of the file alone: every entry's path, sizes and flags, checked by every rule of ZipArchive.read that needs only the directory. What a tool reads to check an archive on a server — with HTTP ranges — before downloading all of it; readContent then fetches and unpacks one small file.
ZipEntry
One file or folder in a ZipArchive or a ZipDirectory.
ZipLimits
How much an archive may hold before ZipArchive.read refuses it.
ZipWriter
Builds a ZIP archive whose bytes depend only on its files' paths and contents.

Constants

justCoreCliVersion → const String
The version of just_core_cli — kept equal to pubspec.yaml's by a test.

Functions

canonicalJson(Object? value, {bool pretty = true}) → String
value as the ecosystem's tools write every JSON file: keys sorted, two-space indents, LF line endings and a final newline. The same data always gives the same bytes, so files diff cleanly and hash stably.
checkPinned(Uint8List bytes, {required int size, required String sha256, required String what}) → void
Checks that bytes, downloaded as what, are the size bytes whose SHA-256 is sha256. Throws DownloadException when they are not: changed after they were pinned, or broken on the way.
compactJson(Map<String, Object?> map) → Map<String, Object?>
Drops null values and empty lists or maps from map, so files only carry what is set.
isFetchAllowed(Uri uri) → bool
Whether uri may be fetched: https:, or plain http: to this machine only.
isSha256Hex(String text) → bool
Whether text is a SHA-256 digest written as 64 lowercase hex digits.
normalPath(String path) → String
path with / between parts and no trailing / (a drive root such as C:/ keeps its own).
pathRoot(String path) → String
The part of path (with /) no .. climbs above: a drive (C:/), a network share (//server/share/) or /; empty for a relative path.
resolveDots(String path) → String
path with / between parts and its . and .. parts resolved: C:/app/./lib/../assets is C:/app/assets. A drive, a network share or / keeps its own form, and .. never climbs above it.
resolvePath(String base, String path, {required bool windows}) → String
path as an absolute path, from the folder base (absolute) when it is relative: / between parts, its . and .. resolved.

Typedefs

ByteProgress = void Function(int received, int? total)
Reports bytes received so far, out of total when known.
RedirectCheck = bool Function(Uri uri)
Whether a fetch may follow a redirect to target: a caller's own rule (HttpFetcher.get's allowRedirect), asked after the https rule and before anything is sent to target.

Exceptions / Errors

CancelledException
Work stopped because a CancelToken was cancelled.
DownloadException
A download whose bytes are not what was pinned.
FetchException
Something that could not be fetched: the server refused, the network failed, or the download broke a limit.
JsonFormatException
A JSON file that is not valid: wrong JSON shape, a missing field, a value out of range.
UnsafePathException
A path in an archive or a package that is not safe to write.
ZipFormatException
A ZIP archive that is damaged, uses something this reader refuses, or breaks one of its ZipLimits.
ZipNeedsBytes
Thrown by ZipDirectory when the bytes it was given end before what it must read: bytes start to end (end not included) of the archive are needed too. Fetch them and try again.