Module nix_compat::nar::wire

source ·
Expand description

NAR wire format, without I/O details, since those differ between the synchronous and asynchronous implementations.

The wire format is an S-expression format, encoded onto the wire using simple encoding rules.

§Encoding

Lengths are represented as 64-bit unsigned integers in little-endian format. Byte strings, including file contents and syntactic strings part of the grammar, are prefixed by their 64-bit length, and padded to 8-byte (64-bit) alignment with zero bytes. The zero-length string is therefore encoded as eight zero bytes representing its length.

§Grammar

The NAR grammar is as follows:

archive ::= "nix-archive-1" node

node ::= "(" "type" "symlink" "target" string ")"
     ||= "(" "type" "regular" ("executable" "")? "contents" string ")"
     ||= "(" "type" "directory" entry* ")"

entry ::= "entry" "(" "name" string "node" node ")"

We rewrite it to pull together the purely syntactic elements into unified tokens, producing an equivalent grammar that can be parsed and serialized more elegantly:

archive ::= TOK_NAR node
node ::= TOK_SYM string             TOK_PAR
     ||= (TOK_REG | TOK_EXE) string TOK_PAR
     ||= TOK_DIR entry*             TOK_PAR

entry ::= TOK_ENT string TOK_NOD node TOK_PAR

TOK_NAR ::= "nix-archive-1" "(" "type"
TOK_SYM ::= "symlink" "target"
TOK_REG ::= "regular" "contents"
TOK_EXE ::= "regular" "executable" "" "contents"
TOK_DIR ::= "directory"
TOK_ENT ::= "entry" "(" "name"
TOK_NOD ::= "node" "(" "type"
TOK_PAR ::= ")"

§Restrictions

NOTE: These restrictions are not (and cannot be) enforced by this module, but must be enforced by its consumers, super::reader and super::writer.

Directory entry names cannot have the reserved names . and .., nor contain forward slashes. They must appear in strictly ascending lexicographic order within a directory, and can be at most MAX_NAME_LEN bytes in length.

Symlink targets can be at most MAX_TARGET_LEN bytes in length.

Neither is permitted to be empty, or contain null bytes.

Re-exports§

  • pub use tag::Tag;

Modules§

Enums§

  • Entry
    Directory entry or terminator
  • Node
    These are the node tokens, succeeding TOK_NAR or TOK_NOD, and preceding the next variable-length element.
  • PadPar 🔒

Constants§