documenttree

package
v1.0.36-beta.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 3, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package documenttree implements a bounded, framed, fully nested document-tree CRDT.

A document tree combines LWW maps and RGA arrays through single-owner child objects. It intentionally does not reuse the wire formats of lww.Map, list.RGA, or Yjs: a manifest selects this complete protocol as one unit.

Index

Constants

View Source 
const SemanticsVersion uint64 = crdt.SemanticsVersionDocumentTree

SemanticsVersion is the immutable document-tree-v2 protocol contract.

Variables

View Source 
var (
	ErrNilDocument     = errors.New("documenttree: nil document")
	ErrInvalidReplica  = errors.New("documenttree: invalid replica ID")
	ErrInvalidRoot     = errors.New("documenttree: invalid root name")
	ErrInvalidKey      = errors.New("documenttree: invalid map key")
	ErrInvalidValue    = errors.New("documenttree: invalid value")
	ErrInvalidJSON     = errors.New("documenttree: invalid JSON scalar")
	ErrInvalidDelta    = errors.New("documenttree: invalid document-tree delta")
	ErrInvalidState    = errors.New("documenttree: invalid document-tree state")
	ErrIncompleteState = errors.New("documenttree: incomplete document-tree state")
	ErrTypeMismatch    = errors.New("documenttree: object type mismatch")
	ErrUnknownObject   = errors.New("documenttree: unknown object")
	ErrRange           = errors.New("documenttree: array range outside visible projection")
	ErrTagConflict     = errors.New("documenttree: conflicting use of a mutation tag")
	ErrResourceLimit   = errors.New("documenttree: resource limit exceeded")
)

Functions

func MigrateV1Delta added in v1.0.33 

func MigrateV1Delta(data []byte, options Options, limits frame.DecoderLimits) ([]byte, error)

MigrateV1Delta converts one bounded v1 delta into a v2 delta. It is safe only for a controlled cutover where every participant has stopped sending v1 frames; hosts must deliver the resulting v2 frame to a v2 replication group with the same authenticated schema and compatible limits.

func MigrateV1State added in v1.0.33 

func MigrateV1State(data []byte, options Options, limits frame.DecoderLimits) ([]byte, error)

MigrateV1State converts one complete v1 state frame into a complete v2 frame without changing its object graph or HLC tags. It is an offline, one-time migration tool, not a replication decoder. A v1 frame containing its former lazy-reference value is rejected: the referenced content was not in the old frame, so treating it as a fully nested value would lose data.

func StableFrameType 

func StableFrameType() crdt.FrameType

StableFrameType returns the state/delta pair selected by a document-tree-v2 replication manifest. The protocol owns its HLC because roots, map writes, and array positions all use HLC tags.

Types

type Array 

type Array struct {
	// contains filtered or unexported fields
}

Array is a lightweight handle to one RGA array object.

func (*Array) Array 

func (a *Array) Array(index int) (*Array, bool)

func (*Array) Delete 

func (a *Array) Delete(index, count int) (Delta, error)

func (*Array) Get 

func (a *Array) Get(index int) (Value, bool)

func (*Array) GetJSON added in v1.0.36 

func (a *Array) GetJSON(index int) (any, bool, error)

GetJSON returns a decoded JSON scalar at one visible array position.

func (*Array) ID 

func (a *Array) ID() ObjectID

func (*Array) Insert 

func (a *Array) Insert(index int, value []byte) (Delta, error)

func (*Array) InsertArray 

func (a *Array) InsertArray(index int) (*Array, Delta, error)

func (*Array) InsertJSON added in v1.0.36 

func (a *Array) InsertJSON(index int, value any) (Delta, error)

InsertJSON inserts one canonical JSON scalar. Nested JSON containers must be modelled with InsertMap or InsertArray so their independent edits converge.

func (*Array) InsertMap 

func (a *Array) InsertMap(index int) (*Map, Delta, error)

func (*Array) Len 

func (a *Array) Len() int

func (*Array) Map 

func (a *Array) Map(index int) (*Map, bool)

type Delta 

type Delta struct {
	// contains filtered or unexported fields
}

Delta is an opaque, joinable partial document-tree state. Local mutation or UnmarshalDelta are the only ways to construct a meaningful Delta. A local delta may retain its already-validated canonical outbox frame so a facade can hand it off without serializing the same mutation twice.

func UnmarshalDelta 

func UnmarshalDelta(data []byte) (Delta, error)

UnmarshalDelta decodes one bounded canonical delta.

func UnmarshalDeltaWithLimits 

func UnmarshalDeltaWithLimits(data []byte, limits frame.DecoderLimits) (Delta, error)

UnmarshalDeltaWithLimits decodes a delta with the default retained-value policy. ApplyDelta always rechecks it against the receiver's local limits.

func UnmarshalDeltaWithOptions 

func UnmarshalDeltaWithOptions(data []byte, options Options, limits frame.DecoderLimits) (Delta, error)

UnmarshalDeltaWithOptions validates one delta before it can enter a receiver-owned pending queue.

func (Delta) MarshalBinary 

func (d Delta) MarshalBinary() ([]byte, error)

MarshalBinary returns a canonical bounded document-tree delta frame.

func (Delta) MarshalBinaryWithLimits 

func (d Delta) MarshalBinaryWithLimits(limits frame.DecoderLimits) ([]byte, error)

MarshalBinaryWithLimits enforces the exact output frame budget selected by the local group before returning a delta for an outbox.

func (Delta) MarshalJSON 

func (d Delta) MarshalJSON() ([]byte, error)

MarshalJSON returns a payload-free diagnostic summary for a delta.

type Document 

type Document struct {
	// contains filtered or unexported fields
}

Document is a bounded collection of LWW maps and RGA arrays. The document lock protects every object so a mutation that creates a child is atomic with its parent reference; handles never carry independent mutable state.

func New 

func New(replicaID string) (*Document, error)

New constructs an empty document with the default retention policy.

func NewFromClockWithOptions 

func NewFromClockWithOptions(state clock.State, options Options) (*Document, error)

NewFromClockWithOptions restores an empty document using a persisted HLC.

func NewFromClockWithOptionsAndOutputLimits added in v1.0.31 

func NewFromClockWithOptionsAndOutputLimits(state clock.State, options Options, outputLimits frame.DecoderLimits) (*Document, error)

NewFromClockWithOptionsAndOutputLimits restores a document with explicit retained-state and local outbox budgets. The output budget is checked before every local mutation is committed, so an encoding failure cannot create a local-only update.

func NewFromSnapshot 

func NewFromSnapshot(saved snapshot.Snapshot) (*Document, error)

NewFromSnapshot restores a complete snapshot using default local limits.

func NewFromSnapshotWithOptions 

func NewFromSnapshotWithOptions(saved snapshot.Snapshot, options Options, limits frame.DecoderLimits) (*Document, error)

NewFromSnapshotWithOptions restores under caller-selected retention and decoder limits; a snapshot cannot widen either local budget.

func NewWithOptions 

func NewWithOptions(replicaID string, options Options) (*Document, error)

NewWithOptions constructs an empty document with explicit local limits.

func NewWithOptionsAndOutputLimits added in v1.0.31 

func NewWithOptionsAndOutputLimits(replicaID string, options Options, outputLimits frame.DecoderLimits) (*Document, error)

NewWithOptionsAndOutputLimits constructs a document that rejects a local mutation before it changes state when its canonical delta cannot fit the selected outbox frame budget. Remote decoding remains independently bounded by the limits passed to UnmarshalDeltaWithOptions.

func (*Document) ApplyDelta 

func (d *Document) ApplyDelta(delta Delta) error

ApplyDelta joins a decoded delta atomically. It retains bounded unresolved records for parent-before-child reordering but never serializes them as a complete state.

func (*Document) Array 

func (d *Document) Array(id ObjectID) (*Array, bool)

Array returns a handle only for an integrated array object.

func (*Document) ClockState 

func (d *Document) ClockState() clock.State

ClockState returns the state that must be atomically persisted with a complete document snapshot before this replica ID is used after restart.

func (*Document) CreateRootArray 

func (d *Document) CreateRootArray(name string) (*Array, Delta, error)

CreateRootArray creates one named array root, or returns the current array root without a delta when it already exists.

func (*Document) CreateRootMap 

func (d *Document) CreateRootMap(name string) (*Map, Delta, error)

CreateRootMap creates one named map root, or returns the current map root without a delta when it already exists. Concurrent roots of the same name resolve by their creation tag; a schema should not reuse a root name for a different Kind.

func (*Document) Map 

func (d *Document) Map(id ObjectID) (*Map, bool)

Map returns a handle only for an integrated map object.

func (*Document) MarshalBinary 

func (d *Document) MarshalBinary() ([]byte, error)

MarshalBinary returns a canonical complete document-tree state. A state with missing parent/object records is intentionally not serializable.

func (*Document) MarshalBinaryWithClockState 

func (d *Document) MarshalBinaryWithClockState() ([]byte, clock.State, error)

MarshalBinaryWithClockState returns state and the HLC state to persist in one transaction before a replica ID can be reused.

func (*Document) MarshalBinaryWithClockStateAndLimits 

func (d *Document) MarshalBinaryWithClockStateAndLimits(limits frame.DecoderLimits) ([]byte, clock.State, error)

func (*Document) MarshalBinaryWithLimits 

func (d *Document) MarshalBinaryWithLimits(limits frame.DecoderLimits) ([]byte, error)

func (*Document) MarshalDeltaWithLimits added in v1.0.31 

func (d *Document) MarshalDeltaWithLimits(delta Delta, limits frame.DecoderLimits) ([]byte, error)

MarshalDeltaWithLimits encodes delta using this document's retained-value policy and an explicit transport budget. Documents created with an output budget have already checked the same encoding before accepting local delta, so this is the safe outbox handoff for those mutations.

func (*Document) MarshalJSON 

func (d *Document) MarshalJSON() ([]byte, error)

MarshalJSON returns a payload-free diagnostic summary.

func (*Document) MarshalLocalDelta added in v1.0.31 

func (d *Document) MarshalLocalDelta(delta Delta) ([]byte, error)

MarshalLocalDelta returns the already-validated frame for a delta returned by a local mutation on d when d has an output budget. It otherwise encodes with that budget. Callers must use it only with a delta from this document; untrusted deltas must go through UnmarshalDeltaWithOptions instead.

func (*Document) Merge 

func (d *Document) Merge(other *Document) error

Merge joins another complete or incomplete document state without exposing mutable internals. Both documents retain their independent HLC identities.

func (*Document) RootArray 

func (d *Document) RootArray(name string) (*Array, bool)

RootArray returns the current visible array root.

func (*Document) RootMap 

func (d *Document) RootMap(name string) (*Map, bool)

RootMap returns the current visible map root. It is false while a root declaration is waiting for its object record, or when the root is an array.

func (*Document) SnapshotCurrentState 

func (d *Document) SnapshotCurrentState() (snapshot.Snapshot, error)

SnapshotCurrentState creates a validated HLC-backed recovery snapshot.

func (*Document) SnapshotCurrentStateWithLimits 

func (d *Document) SnapshotCurrentStateWithLimits(limits frame.DecoderLimits) (snapshot.Snapshot, error)

func (*Document) State 

func (d *Document) State() crdt.StateSnapshot

State returns a diagnostic summary. It excludes user values and object IDs.

func (*Document) UnmarshalBinary 

func (d *Document) UnmarshalBinary(data []byte) error

UnmarshalBinary atomically replaces a document with one complete canonical state frame. It never accepts pending state into a recovery boundary.

func (*Document) UnmarshalBinaryWithLimits 

func (d *Document) UnmarshalBinaryWithLimits(data []byte, limits frame.DecoderLimits) error

type Kind 

type Kind uint8

Kind is the fixed CRDT interpretation of one object. 

const (
	KindMap Kind = iota + 1
	KindArray
)

type Map 

type Map struct {
	// contains filtered or unexported fields
}

Map is a lightweight handle to one integrated map object.

func (*Map) Array 

func (m *Map) Array(key string) (*Array, bool)

func (*Map) CreateArray 

func (m *Map) CreateArray(key string) (*Array, Delta, error)

func (*Map) CreateMap 

func (m *Map) CreateMap(key string) (*Map, Delta, error)

func (*Map) Delete 

func (m *Map) Delete(key string) (Delta, error)

func (*Map) Get 

func (m *Map) Get(key string) (Value, bool)

func (*Map) GetJSON added in v1.0.36 

func (m *Map) GetJSON(key string) (any, bool, error)

GetJSON returns a decoded JSON scalar written through SetJSON. It rejects a raw byte value that is not a canonical JSON scalar rather than guessing how an application intended to interpret it.

func (*Map) ID 

func (m *Map) ID() ObjectID

func (*Map) Keys 

func (m *Map) Keys() []string

func (*Map) Map 

func (m *Map) Map(key string) (*Map, bool)

func (*Map) Set 

func (m *Map) Set(key string, value []byte) (Delta, error)

func (*Map) SetJSON added in v1.0.36 

func (m *Map) SetJSON(key string, value any) (Delta, error)

SetJSON stores one JSON scalar as a canonical byte value. Objects and arrays are deliberately rejected: create a Map or Array child instead so concurrent descendants retain their own CRDT identities rather than becoming one last-writer-wins JSON blob.

type ObjectID 

type ObjectID = crdt.Tag

ObjectID is the immutable identity of a created child object or array position. The zero ID is reserved as the RGA array root anchor.

type ObjectRef 

type ObjectRef struct {
	ID   ObjectID
	Kind Kind
}

ObjectRef names a child object. It is returned as a Value and is immutable: an object can have exactly one parent creation record and cannot be moved or inserted a second time.

type Options 

type Options struct {
	MaxRoots             int
	MaxObjects           int
	MaxMapEntries        int
	MaxArrayNodes        int
	MaxArrayTombstones   int
	MaxPendingOperations int
	MaxPendingBytes      int
	MaxDepth             int
	MaxKeyBytes          int
	MaxValueBytes        int
}

Options bounds retained and incomplete document state. Limits apply to one document-tree group; hosts must still reject oversized transport bodies before allocating them and authorize the one complete replication group.

func DefaultOptions 

func DefaultOptions() Options

DefaultOptions returns conservative per-document retention limits.

type Value 

type Value struct {
	Kind   ValueKind
	Bytes  []byte
	Object ObjectRef
}

Value is an owned projection value. Bytes is copied on both input and output; applications must treat its content as schema-selected opaque data.

func Bytes 

func Bytes(value []byte) Value

type ValueKind 

type ValueKind uint8

ValueKind classifies the payload retained by maps and array positions. 

const (
	ValueBytes ValueKind = iota + 1
	ValueObject
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.