Struct Pack 

pub struct Pack { /* private fields */ }

Implementations

impl Pack

pub fn visit_identities( &self, visit: &mut dyn FnMut(Identity<'_>) -> Result<(), Error>, ) -> Result<(), Error>

Verifies the whole pack, as Pack::verify does, and then calls visit with every render layer of the profile, in the profile’s order, then with every plane, zone, stairwell, definition and anchor, then with the address of every chunk, and then with every object uid: table by table in that order, each table in primary-key order. Every identity listed is therefore one a valid pack holds. One stored document is held at a time.

Errors

Returns the first problem verification finds, an error if SQLite fails or a row is invalid, or the error visit returns.

impl Pack

pub fn profile(&self) -> Result<String, Error>

The stored profile as canonical JSON, checked as a full verification checks it; see Pack::layer_height.

Errors

Returns an error if SQLite fails or the stored profile is invalid.

pub fn plane(&self, id: &str) -> Result<Option<Plane>, Error>

A plane, read from its row and stored document.

Errors

Returns an error if SQLite fails or the stored plane is invalid.

pub fn visit_planes( &self, page: Page<&str>, visit: &mut dyn FnMut(Plane) -> Result<(), Error>, ) -> Result<(), Error>

Calls visit with the planes of page, in ID order. One stored document is held at a time.

Errors

Returns an error if SQLite fails, a stored plane is invalid, or visit fails.

pub fn zone(&self, plane: &str, id: &str) -> Result<Option<Zone>, Error>

A zone of a plane. Whether the plane and parent exist is checked by Pack::verify.

Errors

Returns an error if SQLite fails or the stored zone is invalid.

pub fn visit_zones( &self, plane: &str, page: Page<&str>, visit: &mut dyn FnMut(Zone) -> Result<(), Error>, ) -> Result<(), Error>

Calls visit with the zones of a plane in page, in ID order.

Errors

Returns an error if SQLite fails, a stored zone is invalid, or visit fails.

pub fn anchor(&self, plane: &str, id: &str) -> Result<Option<Anchor>, Error>

An anchor of a plane. Whether the plane exists is checked by Pack::verify.

Errors

Returns an error if SQLite fails or the stored anchor is invalid.

pub fn visit_anchors( &self, plane: &str, page: Page<&str>, visit: &mut dyn FnMut(Anchor) -> Result<(), Error>, ) -> Result<(), Error>

Calls visit with the anchors of a plane in page, in ID order.

Errors

Returns an error if SQLite fails, a stored anchor is invalid, or visit fails.

pub fn visit_stairwells( &self, plane: &str, page: Page<&str>, visit: &mut dyn FnMut(Stairwell) -> Result<(), Error>, ) -> Result<(), Error>

Calls visit with the stairwells of a plane in page, in ID order, read from their stored documents as Pack::stairwell reads one. One stored document is held at a time.

Errors

Returns an error if SQLite fails, a stored stairwell is invalid, or visit fails.

pub fn visit_stairwells_within( &self, plane: &str, page: Page<&str>, maximum_steps: u64, visit: &mut dyn FnMut(Stairwell) -> Result<(), Error>, ) -> Result<(), Error>

Pack::visit_stairwells, with a budget of maximum_steps steps for each stairwell; see Pack::stairwell_within.

Errors

Returns an error if SQLite fails, a stored stairwell is invalid or lists more steps than the budget, or visit fails.

pub fn definition( &self, kind: &str, id: &str, ) -> Result<Option<Definition>, Error>

A definition, by type and ID.

Errors

Returns an error if SQLite fails or the stored definition is invalid.

pub fn visit_definitions( &self, kind: Option<&str>, page: Page<(&str, &str)>, visit: &mut dyn FnMut(Definition) -> Result<(), Error>, ) -> Result<(), Error>

Calls visit with the definitions of page, by type and then ID: those of type kind, or every definition when kind is None. A page’s key is a definition’s type and ID. One stored document is held at a time.

Errors

Returns an error if SQLite fails, a stored definition is invalid, or visit fails.

pub fn visit_layers( &self, plane: &str, page: Page<i32>, visit: &mut dyn FnMut(i32) -> Result<(), Error>, ) -> Result<(), Error>

Calls visit with the layers of a plane that have chunks, in page, in order.

Errors

Returns an error if SQLite fails, a stored layer is not a 32-bit integer, or visit fails.

pub fn visit_chunk_keys( &self, plane: &str, layer: i32, page: Page<(i64, i64)>, visit: &mut dyn FnMut(i64, i64) -> Result<(), Error>, ) -> Result<(), Error>

Calls visit with the chunk coordinates (cx, cy) of the chunks of a plane’s layer in page, by cx and then cy. Each keeps every tile of its chunk within the source format’s integer range.

Errors

Returns an error if SQLite fails, a stored position is out of range, or visit fails.

impl Pack

pub fn open(path: &Path) -> Result<Self, Error>

Opens a pack with VerifyLimits::default; see Pack::open_with.

Errors

Returns an error if the file is not a pack of this format or is longer than the default pack size limit.

pub fn open_with(path: &Path, limits: &VerifyLimits) -> Result<Self, Error>

Opens a pack and checks its size, identity and schema. A file longer than limits.maximum_pack_bytes is rejected before SQLite opens it, and Pack::file_digest reads at most that many bytes.

Errors

Returns an error if the file is not a pack of this format or is longer than the limit.

pub fn open_bytes( bytes: &[u8], digest: Option<[u8; 32]>, limits: &VerifyLimits, ) -> Result<Self, Error>

Opens a pack from its bytes, as Pack::open_from does.

Errors

Returns an error if the bytes are not a pack of this format or are more than the pack size limit.

pub fn open_from( read: impl Read, length: u64, digest: Option<[u8; 32]>, limits: &VerifyLimits, ) -> Result<Self, Error>

Opens a pack image of exactly length bytes, which read yields, and checks its size, identity and schema as Pack::open_with checks a file’s. An image longer than limits.maximum_pack_bytes is rejected before any of it is read. SQLite reads a read-only copy in memory, which stays the pack’s bytes until it is dropped. The copy is hashed as it is filled, so opening an image costs one SHA-256 of it.

digest, when given, is the SHA-256 the image must have. Like a file name that is a digest, verification compares it with the image’s digest; opening does not compare them.

Errors

Returns an error if read fails, ends early or yields more than length bytes, the image is longer than the limit or than memory can hold, or it is not a pack of this format.

pub fn meta(&self, key: &str) -> Result<Option<String>, Error>

A meta value.

Errors

Returns an error if SQLite fails.

pub fn string(&self, id: u32) -> Result<Option<String>, Error>

An interned string.

Errors

Returns an error if SQLite fails or the stored value is not text of at most 1 MiB.

pub fn chunk( &self, plane: &str, layer: i32, cx: i64, cy: i64, ) -> Result<Option<ChunkData>, Error>

Decodes one chunk into its full model; see decode_chunk.

Errors

Returns an error if SQLite fails or the stored record is invalid.

pub fn chunk_within( &self, plane: &str, layer: i32, cx: i64, cy: i64, maximum_entries: u64, ) -> Result<Option<ChunkData>, Error>

Pack::chunk, with a budget of maximum_entries entries: its objects, inventories included, and their fields. A record of at most 16 MiB can hold about a million small objects, or as many fields, so a caller that builds a value for each, such as a browser, can bound them. Under a budget the record is first decoded keeping one object at a time, and the read fails with ErrorCode::DecodeBudget once it counts more, before any chunk is built.

Errors

Returns an error if SQLite fails, the stored record is invalid, or it holds more entries than the budget.

pub fn layer_height(&self) -> Result<Option<u32>, Error>

The profile’s layer_height: height units per layer, or None when the profile does not stack layers. The stored profile is checked as a full verification checks it.

Errors

Returns an error if SQLite fails or the stored profile is invalid.

pub fn stairwell( &self, plane: &str, id: &str, ) -> Result<Option<Stairwell>, Error>

One stairwell of a plane, read from its stored document. Like Pack::chunk, it checks the shape and bounds of what it loads; whether the plane and the steps’ prototypes exist is checked by Pack::verify.

Errors

Returns an error if SQLite fails, or the stored stairwell does not have the source format’s shape or disagrees with its row.

pub fn stairwell_within( &self, plane: &str, id: &str, maximum_steps: u64, ) -> Result<Option<Stairwell>, Error>

Pack::stairwell, with a budget of maximum_steps steps. A stored document can list about a quarter of a million, so a caller that builds a value for each, such as a browser, can bound them; the read fails with ErrorCode::DecodeBudget before it builds any step.

Errors

Returns an error if SQLite fails, the stored stairwell is invalid or disagrees with its row, or it lists more steps than the budget.

pub fn stairwell_step( &self, plane: &str, layer: i32, x: i64, y: i64, ) -> Result<Option<StairwellTile>, Error>

The stairwell step on a tile of a plane, if any. It checks the shape and bounds of what it loads; whether the stairwell and prototype exist is checked by Pack::verify.

Errors

Returns an error if SQLite fails or the stored step is invalid.

pub fn object_location(&self, uid: &str) -> Result<Option<UidLocation>, Error>

Where the object with uid is, from its object_uids row. Like Pack::chunk, it checks the shape and bounds of what it loads; whether the row agrees with the chunk records is checked by Pack::verify, or for this one object by Pack::object.

Errors

Returns an error if SQLite fails or the stored row is invalid.

pub fn object( &self, uid: &str, ) -> Result<Option<(UidLocation, ObjectRecord)>, Error>

The object with uid and where it is. It decodes the object’s chunk, as Pack::chunk does, and fails unless the object at the row’s index has uid.

Errors

Returns an error if SQLite fails, the stored row or chunk is invalid, or they disagree.

pub fn object_within( &self, uid: &str, maximum_entries: u64, ) -> Result<Option<(UidLocation, ObjectRecord)>, Error>

Pack::object, decoding the object’s chunk with a budget of maximum_entries objects and fields; see Pack::chunk_within.

Errors

Returns an error if SQLite fails, the stored row or chunk is invalid, they disagree, or the chunk holds more entries than the budget.

pub fn summary(&self) -> Result<Summary, Error>

Row counts.

Errors

Returns an error if SQLite fails.

pub fn file_digest(&self) -> Result<[u8; 32], Error>

The SHA-256 of the pack file, read from its path when called, or of the image a pack was opened from.

For a file, this hashes whatever file is at the pack’s path now, not necessarily the file SQLite opened: the digest binds to the path. Packs are content-addressed files opened from directories the caller controls; a directory that others can write to is not supported. It reads at most the pack size limit the pack was opened with, and fails for a longer file. An image’s digest was taken as SQLite’s read-only copy was filled, so it binds to the bytes the reads see.

Errors

Returns an error if the file cannot be read or is longer than the limit.

pub fn verify(&self) -> Result<Summary, Error>

Checks the whole pack with the default decoded-byte budget and the pack size limit the pack was opened with; see Pack::verify_with.

Errors

Returns the first problem found.

pub fn verify_with(&self, limits: &VerifyLimits) -> Result<Summary, Error>

Checks the whole pack: SQLite integrity, the file name digest when the name is one, string, plane, zone, anchor and definition rows, every stored document, every chunk record, and every string, layer, ground count and portal target a record references.

Decoding every chunk is linear in the pack’s decoded size, which compression can make far larger than the file, so it stops and fails once limits.maximum_decoded_bytes would be passed. The integrity check and the hash are linear in the file’s size, so the pages are checked against the pack size limit before either runs, and the hash reads at most that many bytes. The limit is the lower of limits.maximum_pack_bytes and the one the pack was opened with, so verifying never reads more than opening allowed. The file name check hashes the file at the pack’s path, so it binds to the path; see Pack::file_digest. An image’s digest is compared before the integrity check instead, so that SQLite’s checks do not run on an image that is not the one the caller expects.

Errors

Returns the first problem found, including an exceeded limit.