journal

Documentation

Overview

Package journal implements beardrive's append-only operation log.

Every change to a volume is recorded as an Op in a per-device JSONL journal. Journals are append-only and each device only ever writes its own journal, so syncing is conflict-free at the transport level: a sync uploads your journal and downloads everyone else's. The merged view of a volume is a deterministic replay of the union of all ops ordered by (lamport, time, device, seq) — every device converges to the same state.

Index

• Constants
• func Append(path string, ops []Op) error
• func Less(a, b Op) bool
• func Marshal(ops []Op) ([]byte, error)
• func Replay(ops []Op) map[string]FileState
• func Sort(ops []Op)
• type FileState
• type Op
  • func Parse(data []byte) ([]Op, error)
  • func ReadFile(path string) ([]Op, error)

Constants

const (
	KindPut    = "put"
	KindDelete = "delete"
)

Functions

func Append

func Append(path string, ops []Op) error

Append appends ops to a journal file as JSONL.

func Less

func Less(a, b Op) bool

Less defines the total order used to replay ops from many devices.

func Marshal

func Marshal(ops []Op) ([]byte, error)

Marshal encodes ops as JSONL, the journal wire format.

func Replay

func Replay(ops []Op) map[string]FileState

Replay folds a set of ops (from any number of devices) into the resulting volume state. Last writer wins per path under the total order.

func Sort

func Sort(ops []Op)

Types

type FileState

type FileState struct {
	Blob string
	Size int64
	Mode uint32
}

FileState is the resolved state of one path after replay.

type Op

type Op struct {
	Seq        int64     `json:"seq"`     // per-device sequence number, 1-based
	Lamport    int64     `json:"lamport"` // logical clock for cross-device ordering
	Time       time.Time `json:"time"`
	Device     string    `json:"device"`
	DeviceName string    `json:"device_name,omitempty"`
	Author     string    `json:"author,omitempty"`    // OS/git identity (offline fallback)
	User       string    `json:"user,omitempty"`      // signed-in account email
	UserName   string    `json:"user_name,omitempty"` // signed-in account display name
	Kind       string    `json:"kind"`                // "put" or "delete"
	Path       string    `json:"path"`                // slash-separated, relative to volume root
	Blob       string    `json:"blob,omitempty"`      // sha256 hex of content (put only)
	Size       int64     `json:"size,omitempty"`
	Mode       uint32    `json:"mode,omitempty"` // permission bits
	Note       string    `json:"note,omitempty"` // e.g. "conflict copy of <path>"
}

Op is a single journaled file operation.

func Parse

func Parse(data []byte) ([]Op, error)

Parse decodes a JSONL journal.

func ReadFile

func ReadFile(path string) ([]Op, error)

ReadFile reads a journal file; a missing file is an empty journal.