documenttree

package
v1.0.32-beta.1 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package documenttree implements a bounded, framed 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-v1 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")
	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 StableFrameType 

func StableFrameType() crdt.FrameType

StableFrameType returns the state/delta pair selected by a document-tree-v1 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) 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) InsertMap 

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

func (*Array) InsertSubdocument 

func (a *Array) InsertSubdocument(index int, id string) (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) Subdocuments 

func (d *Document) Subdocuments() []SubdocumentRef

Subdocuments returns the de-duplicated subdocument references reachable from currently visible roots. A reference is metadata only: callers must authenticate and authorize the separately negotiated subdocument manifest before opening a provider for it.

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) 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) SetSubdocument 

func (m *Map) SetSubdocument(key, id string) (Delta, error)

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
	MaxSubdocumentIDBytes 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 every parent/subdocument group.

func DefaultOptions 

func DefaultOptions() Options

DefaultOptions returns conservative per-document retention limits.

type Registry 

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

Registry tracks which visible subdocuments a local consumer has requested to load. Sync, Load, and Unload do not mutate the parent CRDT and do not perform network I/O; a provider uses Loaded to decide which independent manifest/group to fetch or release.

func NewRegistry 

func NewRegistry(options RegistryOptions) (*Registry, error)

func (*Registry) Available 

func (r *Registry) Available() []SubdocumentRef

Available returns sorted visible references, regardless of local load state. The returned slice is caller-owned.

func (*Registry) Load 

func (r *Registry) Load(id string) (SubdocumentRef, bool)

Load records a local request to load one currently visible subdocument. Callers open their own provider after this returns true.

func (*Registry) Loaded 

func (r *Registry) Loaded(id string) bool

Loaded reports whether the reference is locally requested/opened.

func (*Registry) Sync 

func (r *Registry) Sync(document *Document) error

Sync refreshes the registry from one document's visible reference graph. It is atomic: an over-limit document leaves the prior local lifecycle state untouched.

func (*Registry) Unload 

func (r *Registry) Unload(id string) bool

Unload releases the local load request. It does not delete the parent reference and cannot revoke a remote peer's access.

type RegistryOptions 

type RegistryOptions struct {
	MaxSubdocuments int
	MaxIDBytes      int
}

RegistryOptions bounds local, ephemeral subdocument lifecycle metadata. It is intentionally independent of Document.Options because opened content belongs to separately authorized replication groups.

func DefaultRegistryOptions 

func DefaultRegistryOptions() RegistryOptions

type SubdocumentRef 

type SubdocumentRef struct{ ID string }

SubdocumentRef identifies a separate, independently authorized replication group. Its bytes never contain the subdocument state or grant access to it. A provider can use Registry to track local load/unload requests.

type Value 

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

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

func Subdocument 

func Subdocument(id string) Value

type ValueKind 

type ValueKind uint8

ValueKind classifies the payload retained by maps and array positions. 

const (
	ValueBytes ValueKind = iota + 1
	ValueObject
	ValueSubdocument
)

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.