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.
Structs§
- Envelope
Config - Configuration for encoding an envelope.
- Zstd
Config - Configuration for zstd compression.
Enums§
- Envelope
Error - Error type for envelope operations.
- Envelope
Format - Encoded format of an envelope payload.
Constants§
- MAGIC_
NUMBERS - Magic number identifying the start of an envelope.
Functions§
- read_
envelope - Read a HUGR envelope from a reader.
- write_
envelope - Write a HUGR package into an envelope, using the specified configuration.