Expand description
Envelope format for HUGR packages.
The format is designed to be extensible and backwards-compatible. It consists of a header declaring the format used to encode the HUGR, followed by the encoded HUGR itself.
Use read_envelope and write_envelope for reading and writing
envelopes from/to readers and writers, or call Package::load and
Package::store directly.
§Payload formats
The envelope may encode the HUGR in different formats, listed in
EnvelopeFormat. The payload may also be compressed with zstd.
Some formats can be represented as ASCII, as indicated by the
EnvelopeFormat::ascii_printable method. When this is the case, the
whole envelope can be stored in a string.
§Envelope header
The binary header format is 10 bytes, with the following fields:
| Field | Size (bytes) | Description |
|---|---|---|
| Magic | 8 | MAGIC_NUMBERS constant identifying the envelope format. |
| Format | 1 | EnvelopeFormat describing the payload format. |
| Flags | 1 | Additional configuration flags. |
Flags:
- Bit 0: Whether the payload is compressed with zstd.
- Bits 1-5: Reserved for future use.
- Bit 7,6: Constant “01” to make some headers ascii-printable.
Modules§
- serde_
with - Derivation to serialize and deserialize Hugrs and Packages as envelopes in a serde compatible way.
Structs§
- Envelope
Config - Configuration for encoding an envelope.
- Extension
Version Mismatch - Error raised when the reported used version of an extension does not match the registered version in the extension registry.
- With
Generator - Wrap an error with a generator string.
- Zstd
Config - Configuration for zstd compression.
Enums§
- Envelope
Error - Error type for envelope operations.
- Envelope
Format - Encoded format of an envelope payload.
- Extension
Breaking Error - Error raised when checking for breaking changes in used extensions.
- Package
Encoding Error - Error raised while loading a package.
Constants§
- GENERATOR_
KEY - Key used to store the name of the generator that produced the envelope.
- MAGIC_
NUMBERS - Magic number identifying the start of an envelope.
- USED_
EXTENSIONS_ KEY - Key used to store the list of used extensions in the metadata of a HUGR.
Functions§
- read_
envelope - Read a HUGR envelope from a reader.
- write_
envelope - Write a HUGR package into an envelope, using the specified configuration.