pointer

Documentation

Overview

Package pointer encodes and decodes the FXVCS pointer stored in Git in place of a large asset.

Format version 1 is a short, deterministic, line-oriented UTF-8 text:

version https://fxvcs.dev/pointer/v1
domain domain_maps_01
encoding whole/1
manifest sha256:<64 hex>
oid sha256:<64 hex>
size 1048576

Rules:

• the first line is always the version line;
• the remaining keys appear exactly once each, in ascending byte order;
• key and value are separated by one space, lines end with "\n", the file ends with "\n", there is no CRLF, BOM, comment, or trailing whitespace;
• Decode is strict: any deviation is ErrMalformed, so encode(decode(p)) == p for every accepted p and pointer bytes are stable identity input for the asset index;
• a pointer never exceeds MaxSize bytes, which lets clean/smudge sniff cheaply.

`-text` in .gitattributes is required so Git never rewrites the "\n" bytes.

Index

• Constants
• Variables
• func Sniff(data []byte) bool
• type Pointer
  • func Decode(data []byte) (Pointer, error)
  • func (p Pointer) Encode() ([]byte, error)
  • func (p Pointer) MustEncode() []byte
  • func (p Pointer) Validate() error

Constants

const (
	// FormatVersion is the pointer format this package writes.
	FormatVersion = 1
	// VersionLine is the exact first line of a v1 pointer (without newline).
	VersionLine = "version https://fxvcs.dev/pointer/v1"
	// Prefix is what every supported pointer starts with; used for sniffing.
	Prefix = "version https://fxvcs.dev/pointer/"
	// MaxSize bounds a pointer so filters can read a prefix and decide.
	MaxSize = 1024
)

const (
	EncodingWhole = "whole/1" // single object == whole file, manifest has one chunk
)

Encoding identifiers.

Variables

var (
	ErrNotPointer         = errors.New("pointer: not an fxvcs pointer")
	ErrMalformed          = errors.New("pointer: malformed")
	ErrUnsupportedVersion = errors.New("pointer: unsupported pointer format version")
	ErrInvalidField       = errors.New("pointer: invalid field")
)

Errors.

Functions

func Sniff

func Sniff(data []byte) bool

Sniff reports whether data (or a prefix of it, at least len(Prefix) bytes) looks like a pointer of any version. It does not validate.

Types

type Pointer

type Pointer struct {
	StorageDomainID string // domain_...
	Encoding        string // e.g. "whole/1", "cdc-fastcdc/1"
	ManifestDigest  string // sha256:... of the canonical object manifest
	OID             string // sha256:... of the whole uncompressed file
	Size            int64  // uncompressed size in bytes
}

Pointer is the decoded form.

func Decode

func Decode(data []byte) (Pointer, error)

Decode strictly parses pointer bytes.

func (Pointer) Encode

func (p Pointer) Encode() ([]byte, error)

Encode returns the exact pointer bytes. It fails on invalid fields so a malformed pointer can never be written into Git.

func (Pointer) MustEncode

func (p Pointer) MustEncode() []byte

MustEncode panics on invalid fields; for tests and fixtures only.

func (Pointer) Validate

func (p Pointer) Validate() error

Validate checks every field against the v1 grammar.