apollovm_serialization library
Binary serialization of a parsed ApolloVM AST.
Parsing dominates the cost of loading code. This library stores an
already-parsed ASTRoot as a compact .avma image — Apollo Virtual
Machine Archive — so an application can parse once, at build time or on
first run, and afterwards load the same code unit by decoding bytes, with no
grammar and no backtracking.
// Once, wherever the source is available:
var vm = ApolloVM();
var codeUnit = SourceCodeUnit('dart', source, id: 'calc.dart');
await vm.loadCodeUnit(codeUnit);
var image = vm.saveCodeUnitAST(codeUnit);
// Afterwards, with no parser involved:
var vm2 = ApolloVM();
await vm2.loadCodeUnitAST(image);
Everything here is Uint8List in and Uint8List out: reading and writing
files is left to the caller, so the library is web-safe and has no dart:io
variant.
Integrity
Every image carries a CRC-32, which is verified on load. It detects corruption — a truncated write, bit rot, a mangled transfer — and nothing more: an attacker who edits an image recomputes the checksum in microseconds.
Only a signature made with a key the attacker does not have makes an image tamper-evident. Signing is optional and pluggable (ASTBinarySigner), with HmacSha256Signer built in. An unsigned image deserves exactly as much trust as the source it came from — loading one and running it is equivalent to running arbitrary code from that source, so do not load an unsigned image from an untrusted origin.
Compatibility
An image records the container revision that wrote it and the oldest revision that can decode it correctly. Sections are length-prefixed, so a reader skips any section it does not recognize, and each section is read from a bounded view, so fields a newer writer appended are ignored rather than misread. A newer ApolloVM's output therefore keeps loading in an older one for as long as the additions are purely additive, and an older image keeps loading in every later ApolloVM. When a change genuinely cannot be understood, the reader fails with ASTBinaryException naming both versions instead of producing a wrong AST.
Classes
- ASTBinaryArchiveReader
- Reads a file written by ASTBinaryArchiveWriter.
- ASTBinaryArchiveWriter
- Bundles several binary AST images into one file.
- ASTBinaryFlags
- Bit flags in the binary AST header.
- ASTBinaryFormat
- Constants describing the ApolloVM binary AST container format.
- ASTBinaryHeader
- The fixed header of a binary AST file.
- ASTBinaryInfo
- What a binary AST image says about itself, without decoding its AST.
- ASTBinaryReader
-
Decodes a binary AST image —
.avma, for Apollo Virtual Machine Archive — back into a parsed ASTRoot. - ASTBinarySectionData
- One section of a binary AST file: an identifier and its payload.
- ASTBinarySigner
- Produces the signature stored in a binary AST file's trailer.
- ASTBinaryVerifier
- Checks the signature in a binary AST file's trailer.
- ASTBinaryWriter
-
Encodes a parsed ASTRoot into a binary AST image —
.avma, for Apollo Virtual Machine Archive. - HmacSha256Signer
- Signs binary AST files with HMAC-SHA256.
- HmacSha256Verifier
- Verifies binary AST files signed with HmacSha256Signer.
Enums
- ASTBinaryError
- Why a binary AST file could not be read.
- ASTBinarySection
- Section identifiers in the binary AST section stream.
Extensions
- ApolloVMBinaryAST on ApolloVM
- Binary AST convenience methods on ApolloVM.
- CodeUnitBinaryAST on CodeUnit
- Binary AST convenience methods on CodeUnit.
Exceptions / Errors
- ASTBinaryException
- A binary AST file could not be read.
- ASTBinaryIntegrityException
- The file is structurally valid but does not verify.
- ASTNotSerializableException
- An AST node cannot be represented in a binary AST file.