Metadata

Filepack packages may contain metadata describing the package in metadata.filemeta. This metadata is stored as deco, which is not human readable or writable.

When authoring a package with filepack create, a metadata template named metadata.yaml may be included, in which case it will be converted to deco and saved to metadata.filemeta.

See the schema of metadata.yaml in Metadata, and an example below.

The media field may optionally contain metadata describing the package media. Packages with media metadata are displayed by the filepack server with the ability to browse and play the audio, image, or video items that they contain.

See Media Formats for supported media item file formats.

The unstable web media type may be used for packages containing web content, with is served from the static/ directory of the package, with the required entry point static/index.html.

# Path to cover art. Must be square.
artwork: cover.png

# Primary person or group who created the content.
creator: John Horace Tobin

# Single-line description of the content.
description: A compilation of supernatural occurrences, entities, and facts.

# Official homepage of the content.
homepage: https://tobin-society.org/spirit-guide

# Two-letter ISO 639-1 code of the content's primary language.
language: en

# Metadata describing the media content of the package.
media: ...

# Metadata describing the package itself, as opposed to its content.
package:
  # Path to a markdown file containing a colophon describing the package.
  colophon: COLOPHON.md
  # Primary person or group who created the package.
  creator: Egon Spengler
  # Single-line description of the package.
  description: >-
    First edition on loan from NYPL Main Branch research stacks. Captured via
    Microtek MS-300A flatbed scanner.
  # Official homepage of the package.
  homepage: https://ghost-busters.net/~egon
  # Time the package was created.
  time: 1984-07-08
  # Title of the package.
  title: Tobin's Spirit Guide - First Edition

# Primary publisher of the content.
publisher: Miskatonic University Press

# Path to a markdown file containing a readme describing the content.
readme: README.md

# Time the content was created.
time: '1929'

# Title of the content.
title: Tobin's Spirit Guide

media: audio

media:
  # Collection of audio items.
  type: audio
  # Metadata describing the audio items.
  items:
    - # Path to the audio file.
      path: foo.flac

media: image

media:
  # Collection of image items.
  type: image
  # Metadata describing the image items.
  items:
    - # Path to the image file.
      path: foo.png

media: video

media:
  # Collection of video items.
  type: video
  # Metadata describing the video items.
  items:
    - # Path to the video file.
      path: foo.mp4
      # Path to a placeholder image. Must have the same resolution as the video
      # file.
      placeholder: foo.png

media: web

media:
  # A web site, with `static/index.html` as its entry point.
  type: web

Commands

filepack

Content-addressed packages - https://github.com/casey/filepack

Usage: filepack [OPTIONS] <COMMAND>

Commands:
  archive      Create archive from JSON manifest
  completions  Print shell completion script
  contains     Check if manifest contains file
  create       Create manifest
  delete       Delete package from a filepack server
  download     Download package or file from a filepack server
  files        List manifest files
  fingerprint  Print package fingerprint
  gc           Delete unreferenced data on a filepack server
  hash         Print file hash
  info         Print info
  key          Print public key
  keygen       Generate key pair
  languages    List language codes
  lints        List lint groups
  man          Print man page
  manifest     Print manifest
  metadata     Print metadata
  reference    Print reference
  serve        Start a filepack server
  sign         Sign manifest
  signatures   List manifest signatures
  size         Print manifest totals
  upload       Upload package or file to a filepack server
  verify       Verify manifest
  help         Print this message or the help of the given subcommand(s)

Options:
      --data-dir <DATA_DIR>
          Store local data, including private keys, in <DATA_DIR>
          
          [env: FILEPACK_DATA_DIR=]

      --mmap
          Memory-map files for hashing

      --parallel
          Memory-map and read files in parallel for hashing

      --quiet
          Suppress output

      --unstable
          Enable unstable features
          
          [env: FILEPACK_UNSTABLE=]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

filepack archive

Create archive from JSON manifest

Usage: filepack archive <INPUT> <OUTPUT>

Arguments:
  <INPUT>
          Read manifest JSON from <INPUT>

  <OUTPUT>
          Write archive to <OUTPUT>

Options:
  -h, --help
          Print help

Reads Manifest as JSON from <INPUT>.

filepack completions

Print shell completion script

Usage: filepack completions <SHELL>

Arguments:
  <SHELL>
          Print completion script for <SHELL>
          
          [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -h, --help
          Print help

filepack contains

Check if manifest contains file

Usage: filepack contains <--file <FILE>|--hash <HASH>> [MANIFEST]

Arguments:
  [MANIFEST]
          Load manifest from <PATH>. May be path to manifest, to directory
          containing manifest named `manifest.filepack`, or omitted, in which
          case manifest named `manifest.filepack` in the current directory is
          loaded.

Options:
      --file <FILE>
          Search manifest for <FILE>.

      --hash <HASH>
          Search manifest for <HASH>.

  -h, --help
          Print help

filepack create

Create manifest

Usage: filepack create [OPTIONS] [ROOT]

Arguments:
  [ROOT]
          Create manifest for files in <ROOT> directory, defaults to current
          directory

Options:
      --allow <LINT>
          Allow <LINT>

      --deny <LINT>
          Deny <LINT>

      --force
          Overwrite manifest and generated assets if they already exist

      --generate
          Generate derived assets

      --ignore <PATH>
          Ignore <PATH>

      --key <KEY>
          Sign with <KEY>
          
          [default: master]

      --manifest <MANIFEST>
          Write manifest to <MANIFEST>, defaults to `<ROOT>/manifest.filepack`

      --sign
          Sign manifest

      --timestamp
          Include current time in signature

  -h, --help
          Print help

filepack delete

Delete package from a filepack server

Usage: filepack delete [OPTIONS] --server <URL> <--all|NUMBER>

Arguments:
  [NUMBER]
          Delete package number <NUMBER>

Options:
      --all
          Delete all packages

      --auth <KEY>
          Authenticate with key <KEY>

      --server <URL>
          Delete from server at <URL>

  -h, --help
          Print help

filepack download

Download package or file from a filepack server

Usage: filepack download --server <URL> <--file <HASH>|--package <FINGERPRINT>> <PATH>

Arguments:
  <PATH>
          Download to <PATH>

Options:
      --file <HASH>
          Download file with <HASH>

      --package <FINGERPRINT>
          Download package with <FINGERPRINT>

      --server <URL>
          Download from server at <URL>

  -h, --help
          Print help

filepack files

List manifest files

Usage: filepack files [OPTIONS] [PATH]

Arguments:
  [PATH]
          Load manifest from <PATH>. May be path to manifest, to directory
          containing manifest named `manifest.filepack`, or omitted, in which
          case manifest named `manifest.filepack` in the current directory is
          loaded.

Options:
      --format <FORMAT>
          [default: json-pretty]
          [possible values: json, json-pretty, tsv]

  -h, --help
          Print help

Prints a map from RelativePath to File as JSON to standard output.

filepack fingerprint

Print package fingerprint

Usage: filepack fingerprint [PATH]

Arguments:
  [PATH]
          Load manifest from <PATH>. May be path to manifest, to directory
          containing manifest named `manifest.filepack`, or omitted, in which
          case manifest named `manifest.filepack` in the current directory is
          loaded.

Options:
  -h, --help
          Print help

filepack gc

Delete unreferenced data on a filepack server

Usage: filepack gc [OPTIONS] --server <URL>

Options:
      --auth <KEY>
          Authenticate with key <KEY>

      --server <URL>
          Delete unreferenced data on server at <URL>

  -h, --help
          Print help

filepack hash

Print file hash

Usage: filepack hash [OPTIONS] [FILE]

Arguments:
  [FILE]
          Hash <FILE>, defaulting to standard input

Options:
      --assert <HASH>
          Assert file hash is <HASH>

  -h, --help
          Print help

filepack info

Print info

Usage: filepack info

Options:
  -h, --help
          Print help

Prints Info as JSON to standard output.

filepack key

Print public key

Usage: filepack key [OPTIONS]

Options:
      --key <KEY>
          Print public key <KEY>
          
          [default: master]

  -h, --help
          Print help

filepack keygen

Generate key pair

Usage: filepack keygen [OPTIONS]

Options:
      --name <NAME>
          Generate key named <NAME>
          
          [default: master]

  -h, --help
          Print help

filepack languages

List language codes

Usage: filepack languages [OPTIONS]

Options:
      --format <FORMAT>
          [default: json-pretty]
          [possible values: json, json-pretty, tsv]

  -h, --help
          Print help

Prints a map from Language to String as JSON to standard output.

filepack lints

List lint groups

Usage: filepack lints

Options:
  -h, --help
          Print help

Prints a map from LintGroup to a sorted set of Lint as JSON to standard output.

filepack man

Print man page

Usage: filepack man

Options:
  -h, --help
          Print help

filepack manifest

Print manifest

Usage: filepack manifest [OPTIONS] [PATH]

Arguments:
  [PATH]
          Load manifest from <PATH>. May be path to manifest, to directory
          containing manifest named `manifest.filepack`, or omitted, in which
          case manifest named `manifest.filepack` in the current directory is
          loaded.

Options:
      --format <FORMAT>
          [default: json-pretty]
          [possible values: json, json-pretty, tsv]

  -h, --help
          Print help

Prints Manifest as JSON to standard output.

filepack metadata

Print metadata

Usage: filepack metadata [OPTIONS] [PATH]

Arguments:
  [PATH]
          Load deco metadata from <PATH>. May be path to metadata, to directory
          containing metadata named `metadata.filemeta`, or omitted, in which
          case metadata named `metadata.filemeta` in the current directory is
          loaded.

Options:
      --format <FORMAT>
          [default: json-pretty]
          [possible values: json, json-pretty, tsv]

  -h, --help
          Print help

Prints Metadata as JSON to standard output.

filepack reference

Print reference

Usage: filepack reference

Options:
  -h, --help
          Print help

filepack serve

Start a filepack server

Usage: filepack serve [OPTIONS]

Options:
      --acme-cache <PATH>
          Store ACME TLS certificates in <PATH>

      --acme-contact <CONTACT>
          Provide ACME contact <CONTACT>, email addresses must include `mailto:`
          prefix

      --acme-directory <DIRECTORY>
          Request ACME TLS certificates from <DIRECTORY>
          
          [env: FILEPACK_ACME_DIRECTORY=]
          [default: https://acme-v02.api.letsencrypt.org/directory]

      --address <ADDRESS>
          Listen on <ADDRESS> for incoming requests
          
          [default: 0.0.0.0]

      --admin-key <KEY>
          Admin public key or key name

      --domain <DOMAIN>
          Use <DOMAIN> as canonical domain: request ACME TLS certificates for
          it, accept authentication tokens scoped to it, and redirect to it

      --http
          Serve HTTP traffic

      --http-port <PORT>
          Listen on <PORT> for incoming HTTP requests [default: 80]

      --https
          Serve HTTPS traffic

      --https-port <PORT>
          Listen on <PORT> for incoming HTTPS requests [default: 443]

      --mount <PACKAGE>
          Mount web package <PACKAGE>. <PACKAGE> may be a fingerprint, revision,
          or number. Mounted packages are served under `/mount` by fingerprint,
          revision, and number, as well directly under `/<NAME>` if `<NAME>` is
          supplied. Mounted packages are unsandboxed and served with the server
          origin, make sure you understand the consequences of this and only
          mount packages you trust

      --ready-address <ADDRESS>
          Write listening port to <ADDRESS>

      --redirect-http-to-https
          Redirect HTTP to HTTPS

      --redirect <DOMAIN>
          Redirect requests for <DOMAIN> to the canonical domain, and request
          ACME TLS certificates for it

      --restrict-writes
          Restrict writes to admin

  -h, --help
          Print help

filepack sign

Sign manifest

Usage: filepack sign [OPTIONS] [PATH]

Arguments:
  [PATH]
          Load manifest from <PATH>. May be path to manifest, to directory
          containing manifest named `manifest.filepack`, or omitted, in which
          case manifest named `manifest.filepack` in the current directory is
          loaded.

Options:
      --key <KEY>
          Sign with <KEY>
          
          [default: master]

      --timestamp
          Include current time in signature

  -h, --help
          Print help

filepack signatures

List manifest signatures

Usage: filepack signatures [OPTIONS] [PATH]

Arguments:
  [PATH]
          Load manifest from <PATH>. May be path to manifest, to directory
          containing manifest named `manifest.filepack`, or omitted, in which
          case manifest named `manifest.filepack` in the current directory is
          loaded.

Options:
      --format <FORMAT>
          [default: json-pretty]
          [possible values: json, json-pretty, tsv]

  -h, --help
          Print help

Prints an array of SignatureEntry as JSON to standard output.

filepack size

Print manifest totals

Usage: filepack size [PATH]

Arguments:
  [PATH]
          Load manifest from <PATH>. May be path to manifest, to directory
          containing manifest named `manifest.filepack`, or omitted, in which
          case manifest named `manifest.filepack` in the current directory is
          loaded.

Options:
  -h, --help
          Print help

Prints Totals as JSON to standard output.

filepack upload

Upload package or file to a filepack server

Usage: filepack upload [OPTIONS] --server <URL> [PATH]

Arguments:
  [PATH]
          Upload <PATH>, defaults to current directory for packages

Options:
      --auth <KEY>
          Authenticate with key <KEY>

      --file
          Upload file instead of package

      --replace <NUMBER>
          Replace package number <NUMBER>

      --server <URL>
          Upload to server at <URL>

      --update <NUMBER>
          Update package number <NUMBER>

  -h, --help
          Print help

filepack verify

Verify manifest

Usage: filepack verify [OPTIONS] [ROOT]

Arguments:
  [ROOT]
          Verify files in <ROOT> directory against manifest, defaults to current
          directory

Options:
      --fingerprint <FINGERPRINT>
          Verify package fingerprint is <FINGERPRINT>

      --ignore <PATH>
          Ignore <PATH>

      --ignore-missing
          Ignore missing files

      --key <KEY>
          Verify that manifest has been signed by <KEY>

      --manifest <MANIFEST>
          Read manifest from <MANIFEST>, defaults to `<ROOT>/manifest.filepack`

      --print
          Print manifest if verification is successful

  -h, --help
          Print help

Prints Manifest as JSON to standard output if --print is passed.

Content Types

Routes that serve package files, such as GET /file/{hash}/{*path}, and the package artwork, thumbnail, and media item routes, use a content type determined by the file’s extension.

The Content-Security-Policy: sandbox header is included with responses where doing so does not break built-in browser preview pages.

Binary and unrecognized file extensions are served sandboxed with Content-Type: application/octet-stream and Content-Disposition: attachment.

Files under /mount/ are served with a content type guessed from their extension, not using the following table, and are not sandboxed.

Deco

Filepack defines a variety of data formats, including manifest.filepack manifests, metadata.filemeta metadata, and tagged hex strings.

These formats use deco, a minimal, schema-driven, canonical, evolvable binary serialization format.

Deco has only one type, the byte string. Since all native types are encoded as byte strings, an encoded deco value may not be decoded without knowing its type.

Deco is mostly canonical. With some exceptions, there is only one way to serialize a given value. Types which are designed to be extended are not guaranteed to have a canonical serialization, since they must accept and ignore data produced by newer versions of filepack.

Byte Strings

The first byte, or head, of an encoded byte string determines how to decode it:

• 00-7f: literal single byte (0–127)
• 80-ef: value - 0x80 bytes follow (0–111 bytes)
• f0-f7: value - 0xef byte little-endian length (1–8 bytes) followed by that many bytes (112–2⁶⁴-1)
• f8-ff: reserved values

The shortest possible encoding must be used.

Examples

A single byte whose value is between 0x00 and 0x7f is encoded as-is. For example, the string 0x67 is encoded as 0x67.

A byte string whose length is between 0 and 111 bytes are encoded as a head byte equal to 0x80 plus the length of the string, followed by the byte string. For example, the empty string is encoded as 0x80, the string 0xff is encoded as 0x81ff, and the string 0xabcd is encoded as 0x82abcd.

Byte strings whose length is greater than 111 bytes, up to 2⁶⁴-1 bytes, are encoded as a head byte equal to 0xef plus the number of bytes needed to encode the length, followed by that many length bytes encoded as a little endian integer with trailing zero bytes removed, followed by that many bytes. For example, the byte string containing 255 0xab bytes is encoded as 0xf001ababab….

The shortest possible encoding for a given byte string must be used. For example, the byte string 0xab must be encoded as 0xab 0x81ab, 0xf001ab, or 0xf10100ab.

Arrays

Arrays are encoded as a byte string whose payload is the concatenation of the encoded array elements.

Examples

An empty array is encoded as 0x80.

An array containing one element, the byte string 0xaa, is encoded as 0x8281aa. The element is encoded as 0x81aa, which is two bytes, so the head byte of the array is 0x82.

An array containing two elements, the byte string 0xabcdef and 0x123456, is encoded as 0x8883abcdef83123456.

Interestingly, an array containing a single element of length one whose value is 0x7f or less has the same encoding as the element. So the array containing one element, the byte string 0x22, is encoded as 0x22.

Maps

Maps are encoded as a byte string whose payload is the concatenation of the encoded keys and values, with each key being immediately followed by its value. Keys must be unique and in ascending order.

Examples

An empty map is encoded as 0x80.

A map containing one entry, the key 0x01 with the value 0xaa, is encoded as 0x830181aa. The key is encoded as 0x01 and the value as 0x81aa, which is three bytes in total, so the head byte of the map is 0x83.

A map containing two entries, the key 0x01 with the value 0xabcdef and the key 0x02 with the value 0x123456, is encoded as 0x8a0183abcdef0283123456.

Non-empty ordered sets

Encoded as an array of at least one element. Elements must be unique.

Sorted sets

Encoded as an array of elements. Elements must be unique and in ascending order.

Structs

Structs are encoded as maps from UnsignedInteger field number to field value. Absent optional fields are omitted.

Structs with #[deco(strict)] attribute reject unknown fields. Structs without the attribute ignore unknown fields.

Non strict struct fields with type Option<T>, where T is an enum, are treated as absent if the encoded value is an unrecognized variant.

Field 0 is reserved for versioning. If field 0 is present, decoding fails with an unsupported version error.

Examples

A struct whose optional fields are all absent is encoded as the empty map, 0x80.

A struct with one field, field 1 with the value 99, is encoded as 0x820163. The field number is encoded as 0x01 and the value as 0x63, which is two bytes in total, so the head byte of the struct is 0x82.

A struct with two fields, field 1 with the value 1 and field 2 with the string foo, is encoded as 0x8701010283666f6f. If field 1 is optional and absent, the same struct is encoded as 0x850283666f6f.

Enums

Enums are encoded as arrays whose first value is the UnsignedInteger enum discriminant. The second element, if present, is a struct containing the enum variant’s fields.

If all of a variant’s fields are optional and absent, the second element is omitted entirely, rather than being encoded as an empty struct.

Unknown enum fields are ignored.

Examples

A variant without fields is encoded as an array containing only its discriminant, so the variant with discriminant 0 is encoded as 0x00 and the variant with discriminant 1 is encoded as 0x01.

A variant with discriminant 1 and one field, field 1 with the value 99, is encoded as 0x8401820163. The discriminant is encoded as 0x01 and the struct containing the fields as 0x820163, which is four bytes in total, so the head byte of the array is 0x84.

A variant with discriminant 0 and two fields, field 1 with the value 1 and field 2 with the value 2, is encoded as 0x86008401010202. If field 1 is optional and absent, the same variant is encoded as 0x8400820202. If field 2 were also optional and absent, the variant would be encoded as 0x00.

Schemas

Application

Application a signed message belongs to.

A wrapper around String.

Archive

Filepack archive.

A struct with 2 fields:

The value is encoded with magic bytes consisting of the deco encoded byte string filepack\0, followed by the deco encoded byte string archive, followed by the encoded value.

Audio

Properties of an audio file.

A struct with 8 fields:

AudioCodec

Audio file codec.

An enum with 3 variants:

AudioFormat

Audio file container format.

An enum with 3 variants:

Boolean

True or false.

Encoded as the byte string 0x00 for false and 0x01 for true.

CheckedUrl

http:// or https:// URL.

A wrapper around String.

ChromaSubsampling

Ratio of image chroma to luma samples.

An enum with 5 variants:

Claims

Claims made by an authorization token.

A struct with 2 fields:

ColorType

How an image’s pixels encode color.

An enum with 4 variants:

ComponentBuf

Path component.

May not be ., .., or empty. May not contain /, \, or control characters. May not begin with an ASCII letter followed by :.

A wrapper around String.

Context

Message type enclosed by an envelope.

An enum with 2 variants:

Dimensions

Image dimensions in pixels.

A struct with 2 fields:

Directory

Directory with hash entries.

A struct with 1 field:

DisplayPrivateKey

Ed25519 private key. The first 32 bytes are the public key, and the second 32 bytes are the secret key.

A wrapper around a byte string of exactly 64 bytes.

Ed25519Signature

Ed25519 signature.

A wrapper around a byte string of exactly 64 bytes.

Entry

Entry in a directory.

A struct with 3 fields:

EntryInfo

Type-specific directory entry information.

An enum with 2 variants:

Directory

Envelope<Claims>

Domain-separating message wrapper that commits to the application and context, so signatures of one kind over a serialized envelope cannot be confused for another.

A struct with 3 fields:

Envelope<Statement>

Domain-separating message wrapper that commits to the application and context, so signatures of one kind over a serialized envelope cannot be confused for another.

A struct with 3 fields:

Fingerprint

BLAKE3 hash of a package’s serialized root directory.

A wrapper around Hash.

Hash

BLAKE3 hash.

A wrapper around a byte string of exactly 32 bytes.

Image

Properties of an image file.

A struct with 8 fields:

ImageFormat

Format of an image file.

An enum with 2 variants:

Item<Audio>

Media file.

A struct with 2 fields:

Item<Image>

Media file.

A struct with 2 fields:

Item<Video>

Media file.

A struct with 2 fields:

Language

ISO 639-1 language code.

A wrapper around String.

See Languages for supported language codes.

Media

Package media content metadata.

An enum with 4 variants:

Audio

Image

Video

Metadata

Metadata describing a package’s content.

A struct with 12 fields:

The value is encoded with magic bytes consisting of the deco encoded byte string filepack\0, followed by the deco encoded byte string metadata, followed by the encoded value.

Mode

How an uploaded package relates to existing packages.

An enum with 3 variants:

Replace

Update

Orientation

Transformation to apply when displaying an image.

A struct with 2 fields:

PackageMetadata

Metadata describing a package itself as opposed to its content.

A struct with 6 fields:

PublicKey

Ed25519 public key.

Must use the canonical encoding and not be a small-order point.

A wrapper around a byte string of exactly 32 bytes.

RelativePath

Relative forward-slash-separated path.

May not be empty or have leading, trailing, or double slashes. Each component must be a valid ComponentBuf.

A wrapper around String.

Revision

BLAKE3 hash of a revision.

A wrapper around Hash.

RevisionObject

Revision of a package.

A struct with 2 fields:

Rotation

Rotation to apply when displaying an image.

An enum with 4 variants:

Signature<Claims>

Ed25519 signature over an enveloped message.

A struct with 3 fields:

Unknown fields are rejected.

Signature<Statement>

Ed25519 signature over an enveloped message.

A struct with 3 fields:

Unknown fields are rejected.

SignedInteger

Signed 64-bit integer.

First zig-zag encoded, then encoded as an UnsignedInteger.

Statement

Statement attesting to a package.

A struct with 2 fields:

String

UTF-8 string.

Encoded as a byte string containing the UTF-8 encoding of the string.

Text

Non-empty single line of text.

May not contain control characters, including tabs and line breaks, or leading or trailing whitespace.

A wrapper around String.

Time

Point in time with varying precision.

An enum with 2 variants:

Year

Day

Totals

Directory totals.

files + directories and file_size + directory_size must be less than 2⁶⁴.

A struct with 4 fields:

Track

Track in a video file.

A struct with 3 fields:

TrackCodec

Codec of a video file track.

An enum with 7 variants:

TrackInfo

Track-type specific information.

An enum with 2 variants:

Audio

Video

UnsignedInteger

Unsigned 64-bit integer.

Encoded as little endian with trailing zero bytes removed, with a minimum length of one byte.

Video

Properties of a video file.

A struct with 5 fields:

VideoFormat

Container format of a video file.

An enum with 2 variants:

JSON

Filepack uses JSON for command input and output. This chapter includes the schemas of all filepack types which have JSON representations, including Manifest, which is read by filepack archive and written by filepack manifest.

Schemas

Audio

Properties of an audio file.

A struct with 8 fields:

AudioCodec

Audio file codec.

A string with 3 possible values:

AudioFormat

Audio file container format.

A string with 3 possible values:

Boolean

True or false.

Bytes

Byte string, encoded as lowercase hexadecimal.

CheckedUrl

http:// or https:// URL.

A wrapper around String.

ChromaSubsampling

Ratio of image chroma to luma samples.

A string with 5 possible values:

ColorType

How an image’s pixels encode color.

A string with 4 possible values:

ComponentBuf

Path component.

May not be ., .., or empty. May not contain /, \, or control characters. May not begin with an ASCII letter followed by :.

A wrapper around String.

Dimensions

Image dimensions in pixels.

A struct with 2 fields:

DirectoryTree

Directory tree of subdirectories and file content.

A wrapper around a map from ComponentBuf to DirectoryTreeEntry.

DirectoryTreeEntry

Entry in a directory tree.

An untagged enum with 2 variants:

File

Hashed file.

A struct with 2 fields:

Unknown fields are rejected.

Hash

BLAKE3 hash.

A tagged hex string with tag hash.

Image

Properties of an image file.

A struct with 8 fields:

ImageFormat

Format of an image file.

A string with 2 possible values:

Info

Local configuration.

A struct with 3 fields:

Item<Audio>

Media file.

A struct with 2 fields:

Item<Image>

Media file.

A struct with 2 fields:

Item<Video>

Media file.

A struct with 2 fields:

KeyName

Name of a key in the keychain.

A wrapper around String.

Language

ISO 639-1 language code.

A wrapper around String.

See Languages for supported language codes.

Lint

Check applied to a package by filepack lint.

A string with 24 possible values:

LintGroup

Named group of lints.

A string with 5 possible values:

Manifest

Package manifest unpacked from a package archive.

A struct with 4 fields:

Unknown fields are rejected.

Media

Package media content metadata.

An enum with 4 variants, distinguished by the type field:

audio

image

video

Metadata

Metadata describing a package’s content.

A struct with 12 fields:

Orientation

Transformation to apply when displaying an image.

A struct with 2 fields:

PackageMetadata

Metadata describing a package itself as opposed to its content.

A struct with 6 fields:

PublicKey

Ed25519 public key.

Must use the canonical encoding and not be a small-order point.

A tagged hex string with tag public.

RelativePath

Relative forward-slash-separated path.

May not be empty or have leading, trailing, or double slashes. Each component must be a valid ComponentBuf.

A wrapper around String.

Rotation

Rotation in degrees, one of 0, 90, 180, or 270.

A wrapper around UnsignedInteger.

Signature<Statement>

Ed25519 signature over an enveloped message.

A tagged hex string with tag signature.

SignatureEntry

Signature details.

A struct with 2 fields:

String

String.

Text

Non-empty single line of text.

May not contain control characters, including tabs and line breaks, or leading or trailing whitespace.

A wrapper around String.

Time

Point in time with varying precision.

May be an integer year, or a calendar day, written as Y-MM-DD.

• Year has no leading zeros and may be negative.
• Month is two digits.
• Day is two digits and must be valid for the month and year.

A wrapper around String.

Totals

Directory totals.

files + directories and file_size + directory_size must be less than 2⁶⁴.

A struct with 4 fields:

Track

Track in a video file.

A struct with 3 fields:

TrackCodec

Codec of a video file track.

A string with 7 possible values:

TrackInfo

Track-type specific information.

An enum with 2 variants, distinguished by the type field:

audio

video

UnsignedInteger

Unsigned 64-bit integer.

Utf8PathBuf

UTF-8 filesystem path.

A wrapper around String.

Video

Properties of a video file.

A struct with 5 fields:

VideoFormat

Container format of a video file.

A string with 2 possible values:

Languages

A Language is an ISO 639-1 language code:

Lints

Groups

Lints

Junk Files

The junk lint fails if the package contains a file with one of the following names: .DS_Store, .filepack, .localized.

Windows Reserved Characters

The windows-reserved-character lint fails if a filename contains one of the following characters: ", *, :, <, >, ?, |.

Windows Reserved Names

The windows-reserved-filename lint fails if a filename , ignoring case, is one of the following names, or one of the following names followed by a period: AUX, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, COM¹, COM², COM³, CON, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, LPT¹, LPT², LPT³, NUL, PRN.

Media Formats

Routes

The filepack server responds to the following API routes:

And the following web routes:

/

GET

Display all packages.

Response Body

An HTML page.

/api/directory/{hash}

POST

Verify uploaded directory with hash.

Parameters

/api/file/{hash}

GET

Serve file with hash.

Parameters

Response Body

The contents of a file.

PUT

Upload file with hash.

Parameters

Request Body

An arbitrary byte string.

/api/gc

POST

Delete files, directories, packages, and revisions not reachable by package number.

Response Body

A deco-encoded struct:

/api/head/{revision}

HEAD

Check whether revision is the head of a package.

Parameters

/api/missing

POST

Report which files the server lacks.

Request Body

A deco-encoded struct of at most 1048576 bytes:

Response Body

A deco-encoded struct:

/api/number/{number}

DELETE

Delete package with number.

Parameters

GET

Return information about package with number.

Parameters

Response Body

A deco-encoded struct:

/api/numbers

GET

List all package numbers.

Response Body

A deco-encoded struct:

/api/package/{fingerprint}

HEAD

Check whether package with fingerprint is present.

Parameters

POST

Verify uploaded package with fingerprint.

Parameters

/api/packages

GET

List all package fingerprints.

Response Body

A deco-encoded struct:

/api/revision/{revision}

POST

Verify uploaded revision and assign it a package number.

Parameters

Request Body

A deco-encoded struct of at most 1048576 bytes:

Response Body

A deco-encoded struct:

/artwork/{fingerprint}

GET

Serve cover art of package with fingerprint.

Parameters

Response Body

The contents of a file.

/artwork/{fingerprint}/thumbnail

GET

Serve thumbnail of cover art of package with fingerprint.

Parameters

Response Body

The contents of a file.

/directory/{hash}

GET

Display entries of directory with hash.

Parameters

Response Body

An HTML page.

/favicon.ico

GET

Serve favicon.

Response Body

A static asset.

/file/{hash}

GET

Serve file with hash.

Parameters

Response Body

The contents of a file.

/file/{hash}/{*path}

GET

Serve file with hash, with content type inferred from path, redirecting to /file/{hash} if the extension of path is not recognized.

Parameters

A parameter beginning with * is a wildcard. Wildcard parameters match the remainder of the path, including any slashes, and must not be empty.

Response Body

The contents of a file.

/files

GET

Display all files on the server.

Response Body

An HTML page.

/install.sh

GET

Serve installation script.

Response Body

A static asset.

/media/audio/{fingerprint}/item/{item}

GET

Serve audio item of package with fingerprint.

Parameters

Response Body

The contents of a file.

/media/image/{fingerprint}/item/{item}

GET

Serve image item of package with fingerprint.

Parameters

Response Body

The contents of a file.

/media/image/{fingerprint}/item/{item}/thumbnail

GET

Serve thumbnail of image item of package with fingerprint.

Parameters

Response Body

The contents of a file.

/media/video/{fingerprint}/item/{item}

GET

Serve video item of package with fingerprint.

Parameters

Response Body

The contents of a file.

/media/video/{fingerprint}/item/{item}/placeholder

GET

Serve placeholder image of video item of package with fingerprint.

Parameters

Response Body

The contents of a file.

/media/video/{fingerprint}/item/{item}/placeholder/thumbnail

GET

Serve thumbnail of placeholder image of video item of package with fingerprint.

Parameters

Response Body

The contents of a file.

/mount/{package}

GET

Redirect to root of mounted package, with trailing slash.

Parameters

Response Body

A redirect.

/mount/{package}/

GET

Serve index.html from static directory of mounted package.

Parameters

Response Body

The contents of a file.

/mount/{package}/{*path}

GET

Serve path from static directory of mounted package.

Parameters

A parameter beginning with * is a wildcard. Wildcard parameters match the remainder of the path, including any slashes, and must not be empty.

Response Body

The contents of a file.

/package/{package}

GET

Display package.

Parameters

Response Body

An HTML page.

/package/{package}/history

GET

Display revision history of package.

Parameters

Response Body

An HTML page.

/package/{package}/item/{item}

GET

Display media item of package.

Parameters

Response Body

An HTML page.

/package/{package}/media

GET

Display media of package.

Parameters

Response Body

An HTML page.

/packages

GET

Display all packages.

Query Parameters

order

sort

Response Body

An HTML page.

/static/{*path}

GET

Serve static asset at path.

Parameters

A parameter beginning with * is a wildcard. Wildcard parameters match the remainder of the path, including any slashes, and must not be empty.

Response Body

A static asset.

Tagged Hex

Tagged hex strings begin with a tag identifying the type, followed by a 1, followed by the deco-encoded payload formatted as lowercase hexidecimal.

For example, the tagged hex string of the BLAKE3 hash of the empty string is:

hash1af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262

Note that the encoded payload does not enclude the outer deco length framing.

The deco encoding of the above hash is:

a0af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262

Where a0 encodes the length of the string. The tagged hex representation does not include this outer framing.

A character in the range g through z after the 1 separator is a format version. All format versions are reserved for future use.

Tags

hash

BLAKE3 hash of a file or directory.

A tagged hex Hash.

Example

Hash of the empty string.

hash1af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262

package

Fingerprint identifying a package by its content.

A tagged hex Fingerprint.

Example

Hash of the empty string.

package1af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262

private

Private key.

A tagged hex DisplayPrivateKey.

Example

All-zero private key.

private13b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da290000000000000000000000000000000000000000000000000000000000000000

public

Public key.

A tagged hex PublicKey.

Example

Public key derived from the all-zero private key.

public13b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29

revision

Hash of a revision object.

A tagged hex Revision.

Example

Hash of the revision with no parents whose package fingerprint is the hash of the empty string.

revision1a895f0cd0338254bc76650e829441165eb127ae1e51b92e87189ed1580195617

signature

Signature over a package.

A tagged hex Signature<Statement>.

Example

Signature over the fingerprint hash of the empty string with timestamp 0, signed by the all-zero private key.

signature101a03b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da2902a401a0af1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262020003c0458b42064a66a78926efd7066f62098750af27dee51d4381da7f55007464a56db26eb0f6e4af961aa91c4c58be51ae250e938f0b405c1f4fa679e0dd4009870d

token

Signed bearer token for server authentication.

A tagged hex Signature<Claims>.

Example

Token with audience filepack.com and timestamp 0, signed by the all-zero private key.

token101a03b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da290290018c66696c657061636b2e636f6d020003c086fe820f47ef0c349617059f30b3adf4a13ffd6a3217782dfeabbe99fc905742dfc12bea0ab7dca5dfc05580041ce942c3417dd1a28d5640a9de8cf9daca640f

Unstable Features

Unstable features may change in backwards incompatible ways at any time. Filepack as a whole is unstable, but unstable features are particularly unstable.

Unstable features are enabled with the --unstable flag or by setting the FILEPACK_UNSTABLE environment variable to 1.

YAML

Filepack uses YAML for hand-authored files, namely metadata.

This chapter includes the schemas of all types with YAML representations.

Schemas

Audio

Audio file media item.

A struct with 1 field:

Unknown fields are rejected.

CheckedUrl

http:// or https:// URL.

A wrapper around String.

Image

Image file media item.

A struct with 1 field:

Unknown fields are rejected.

Language

ISO 639-1 language code.

A wrapper around String.

See Languages for supported language codes.

Media

Package media content.

An enum with 4 variants, distinguished by the type field:

Unknown fields are rejected.

audio

image

video

Metadata

Metadata describing a package’s content, read from metadata.yaml.

A struct with 11 fields:

Unknown fields are rejected.

PackageMetadata

Metadata describing the package itself, as opposed to its content.

A struct with 6 fields:

Unknown fields are rejected.

RelativePath

Relative forward-slash-separated path.

May not be empty or have leading, trailing, or double slashes. Each component must be a valid ComponentBuf.

A wrapper around String.

String

String.

Text

Non-empty single line of text.

May not contain control characters, including tabs and line breaks, or leading or trailing whitespace.

A wrapper around String.

Time

Point in time with varying precision.

May be an integer year, or a calendar day, written as Y-MM-DD.

• Year has no leading zeros and may be negative.
• Month is two digits.
• Day is two digits and must be valid for the month and year.

A wrapper around String.

Video

Video file media item.

A struct with 2 fields:

Unknown fields are rejected.