Store and Job
A store of installed packs in one directory: its signed catalog, its packs and their journal, shared by every language and the command line (research note store-api).
Native builds only
The store is part of the store feature: in every native library, and left out of
the WebAssembly build, where the browser's own cache keeps packs. The signed catalog it installs
from goes live with the first catalog release; see the store.
Store
A store of installed packs in one directory: its signed catalog, its packs and their journal, shared by every language and the command line (research note store-api). Long work runs as a Job on a thread of its own; one store runs its jobs one at a time, and its other calls wait for the job running.
Packs are named as catalog paths (np.places.tgd) or short (np, np.dem), several comma-separated. Results are blobs:
catalog:path,release,download,disk,components,licence,state(available,installedorupdate);status:path,release,bytes,pinned,asked,health(good,length,head,footerorsections),components;- an install or update:
path,release,fetched,reused,kept,changed; - a refresh:
timestamp,files,bytes; a repair:path,health,fetched;remove:path,release; findandlocate: one row per place and pack that covers it:id,name,lat,lon,countries, then the pack'spack,release,download,diskandstate, null for a place no pack in the catalog covers.
create
Sets up a store at root and opens it: the metadata mirrors repo and asset mirrors assets (comma-separated URLs), and trusted_root, the catalog's root metadata, which becomes its trust anchor once it verifies by itself. A store set up before is set up again with these.
Errors. ErrorCode::Refused if the root does not verify or the store cannot be written.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn create(root: &str, repo: &str, assets: &str, trusted_root: &[u8]) -> Result<Self>open
Opens the store at root, finishing or undoing an install a crash cut short.
Errors. ErrorCode::Refused if it is not a store or its journal cannot be read.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn open(root: &str) -> Result<Self>damaged
The packs found damaged when the store was opened, comma-separated; empty when none. repair fetches what they lack.
pub fn damaged(&self) -> Stringcatalog
The verified catalog as stored, one row per pack, with its state against the store.
Errors. ErrorCode::Refused before a refresh, or if the stored catalog no longer verifies.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn catalog(&self) -> Result<Blob>status
Each installed pack and its health, from a full check of every byte when deep.
Errors. ErrorCode::Refused if a pack cannot be read.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn status(&self, deep: bool) -> Result<Blob>pin
Pins the pack (kept when room is made), or unpins it.
Errors. ErrorCode::Refused if it is not installed.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn pin(&self, pack: &str, on: bool) -> Result<()>remove
Removes the packs and the dependencies nothing else needs; returns what was removed.
Errors. ErrorCode::Refused if one is not installed or another pack needs it.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn remove(&self, pack: &str) -> Result<Blob>find
The places named query in engine (one over a world pack the app ships, the installed packs, or both), best first, each with the catalog's packs that cover it: what to install for "Dubai". Runs offline on the stored catalog.
Errors. ErrorCode::InvalidArgument for a limit above LIMIT_MAX; ErrorCode::Refused if the stored catalog no longer verifies.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn find(&self, engine: &Engine, query: &str, limit: u32) -> Result<Blob>locate
The countries within radius_m metres of a point in engine, each with the catalog's packs that cover the point: what to install for where the user stands.
Errors. ErrorCode::InvalidArgument for a point off the globe; ErrorCode::Refused if the stored catalog no longer verifies.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn locate(&self, engine: &Engine, lat: f64, lon: f64, radius_m: u32) -> Result<Blob>engine
An engine over the installed packs, each opened with the components and languages installed.
Errors. ErrorCode::Io or ErrorCode::Corrupt if a pack cannot be opened.
Blocks. While a job of this store runs, and on the disk: call it off a UI thread, or use the language's asynchronous form.
pub fn engine(&self) -> Result<Engine>refresh
Refreshes the catalog for the countries (comma-separated ISO codes) and every country installed. Fails with ErrorCode::Network or ErrorCode::Refused.
pub fn refresh(&self, countries: &str) -> Jobinstall
Installs the packs with options, dependencies first, refreshing the catalog for their countries. Cancelled, it leaves the store as it was; the packs installed before the one cut stay installed.
Errors. ErrorCode::InvalidArgument for an unknown component or language tag, more than 8 languages, or an outline level above 255; the job's own errors are the job's.
pub fn install(&self, packs: &str, options: &InstallOptions) -> Result<Job>install_pass
One pass of an install whose bytes a platform's own download service fetches, for downloads that must go on while the app is suspended. The pass reads each asset's ranges from files under dir, checks every byte as from any host, and its result lists what is still missing, one row per range: pack, urls (the asset on each mirror, one per line), length (the asset's), start and end (the range, end exclusive) and file, where to save those bytes. Fetch every listed range (an HTTP Range request for bytes=start-(end-1)), then run the pass again; a result with no rows means the packs are installed and their files under dir removed. A first install takes three passes.
Errors. ErrorCode::InvalidArgument as for Store::install, or for an empty dir; the job's own errors are the job's.
pub fn install_pass(&self, packs: &str, dir: &str, options: &InstallOptions) -> Result<Job>update
Updates the packs (every installed one when empty) to the catalog's releases, keeping the components and languages installed.
pub fn update(&self, packs: &str) -> Jobrepair
Checks the pack in full and, unless it is whole, fetches what it lacks.
pub fn repair(&self, pack: &str) -> JobJob
A store's long work on a thread of its own: its progress in bytes, a wait for the next change, a cancel, and its result.
Job. Each language builds its own idioms on these methods: a stream of progress, and the awaited result cancelling the job when the caller's task is cancelled.
wait_progress
Waits until the progress moves past seq (from seq), the job ends, or timeout_ms passes; returns the sequence then. Polling with the last one returned sees every change.
Blocks. Until the job moves or ends: call it off a UI thread, or use the language's asynchronous form.
pub fn wait_progress(&self, seq: u64, timeout_ms: u32) -> u64seq
The progress's sequence number: it moves on with every change.
pub fn seq(&self) -> u64done_bytes
Bytes received so far.
pub fn done_bytes(&self) -> u64total_bytes
Bytes expected, from the catalog's sizes: never below the bytes received, and equal to them once the job ends.
pub fn total_bytes(&self) -> u64is_ended
Whether the job has ended (done, failed or cancelled); its result is then ready.
pub fn is_ended(&self) -> boolcancel
Asks the job to stop at its next request or chunk; it then fails with ErrorCode::Cancelled and leaves the store as it was.
pub fn cancel(&self)result
The job's result, waiting for it to end.
Errors. The job's: ErrorCode::Network, ErrorCode::Refused, ErrorCode::Cancelled, or ErrorCode::Io and ErrorCode::Corrupt for an engine's packs.
Blocks. Until the job moves or ends: call it off a UI thread, or use the language's asynchronous form.
pub fn result(&self) -> Result<Blob>