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
Rangeof 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 -
valueas 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 aswhat, are thesizebytes whose SHA-256 issha256. 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
urimay be fetched:https:, or plainhttp:to this machine only. -
isSha256Hex(
String text) → bool -
Whether
textis a SHA-256 digest written as 64 lowercase hex digits. -
normalPath(
String path) → String -
pathwith/between parts and no trailing/(a drive root such asC:/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 -
pathwith/between parts and its.and..parts resolved:C:/app/./lib/../assetsisC:/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 -
pathas an absolute path, from the folderbase(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
totalwhen known. - RedirectCheck = bool Function(Uri uri)
-
Whether a fetch may follow a redirect to
target: a caller's own rule (HttpFetcher.get'sallowRedirect), asked after the https rule and before anything is sent totarget.
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.