text

package
v1.0.10-beta.1 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package text implements a state-based Replicated Growable Array (RGA).

Positions are stable mutation tags, not offsets. Offsets are resolved only for a local edit, which makes duplicate and out-of-order deltas safe.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNilText          = errors.New("text: nil RGA")
	ErrInvalidReplicaID = errors.New("text: invalid replica ID")
	ErrInvalidText      = errors.New("text: invalid UTF-8 text")
	ErrRange            = errors.New("text: range outside visible text")
	ErrInvalidDelta     = errors.New("text: invalid RGA delta")
	// ErrIncompleteState indicates a state snapshot contains an unresolved
	// parent reference. Deltas may be partial for out-of-order delivery, but a
	// recoverable state frame must include the complete parent closure.
	ErrIncompleteState = errors.New("text: incomplete RGA state")
	ErrTagConflict     = errors.New("text: conflicting node for one tag")
	// ErrUnsafeCompaction means a tombstone still anchors local or unresolved
	// descendants, so removing it would change RGA ordering or permit a stale
	// insertion to become visible.
	ErrUnsafeCompaction = errors.New("text: unsafe RGA tombstone compaction")
	// ErrResourceLimit indicates that accepting a delta would exceed the
	// receiver's configured in-memory safety limits.
	ErrResourceLimit = errors.New("text: RGA resource limit exceeded")
)

Functions

This section is empty.

Types

type Delta 

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

Delta is a joinable partial RGA state. Nodes and tombstones are deliberately opaque so a malformed delta cannot be assembled by direct field mutation.

func UnmarshalRGADelta 

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

UnmarshalRGADelta decodes one bounded canonical RGA delta frame.

func UnmarshalRGADeltaWithLimits 

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

func UnmarshalRGARunDelta added in v1.0.6 

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

UnmarshalRGARunDelta decodes a bounded run-v2 delta.

func (Delta) MarshalBinary 

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

MarshalBinary returns the canonical framed RGA delta.

func (Delta) MarshalJSON added in v1.0.5 

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

MarshalJSON returns a diagnostic summary for structured logs. It omits text content, positions, tombstone identities, and clock state.

func (Delta) MarshalRunBinary added in v1.0.6 

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

MarshalRunBinary encodes a delta with compact same-replica parent chains.

func (Delta) Merge 

func (d Delta) Merge(other Delta) (Delta, error)

type Options added in v1.0.6 

type Options struct {
	MaxNodes        int
	MaxTombstones   int
	MaxPendingNodes int
	MaxPendingBytes int
}

Options bounds retained RGA metadata. Values must be positive. The defaults match the maximum element count of one default framed payload while keeping unresolved dependency state substantially smaller than a full document. Applications handling untrusted peers should choose limits appropriate to a replication group instead of relying on process-wide memory availability.

func DefaultOptions added in v1.0.6 

func DefaultOptions() Options

DefaultOptions returns conservative per-RGA retention limits.

type Position 

type Position = crdt.Tag

Position is a stable, opaque identifier for one Unicode scalar value. It remains valid after inserts before it and after it has been deleted.

type RGA 

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

RGA is a collaborative text CRDT. A tombstone retained for a deleted position wins even if it arrives before the corresponding insertion.

func New 

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

func NewFromClock 

func NewFromClock(state clock.State) (*RGA, error)

func NewFromClockWithOptions added in v1.0.6 

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

NewFromClockWithOptions restores an RGA clock with explicit retention limits. Clock state must be persisted atomically with a complete snapshot before reusing its replica ID.

func NewFromSnapshot 

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

func NewWithOptions added in v1.0.6 

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

NewWithOptions constructs an RGA with explicit retention limits.

func (*RGA) ApplyDelta 

func (r *RGA) ApplyDelta(delta Delta) error

func (*RGA) ClockState 

func (r *RGA) ClockState() clock.State

func (*RGA) CompactTombstones added in v1.0.6 

func (r *RGA) CompactTombstones(tags []Position) (int, error)

CompactTombstones physically removes exactly the requested tombstoned leaf nodes. It is deliberately stricter than OR-Set compaction: an RGA deletion remains a structural anchor while any integrated or pending child refers to it. Call this only after an authenticated, exact-acknowledgement epoch has durably checkpointed a post-compaction snapshot and retired old deltas.

The operation is all-or-nothing. Unknown tags are ignored; invalid tags, unresolved dependencies, non-leaf nodes, or tombstones received before their insertion return ErrUnsafeCompaction without changing the RGA.

func (*RGA) Delete 

func (r *RGA) Delete(offset, count int) (Delta, error)

Delete marks count visible runes starting at offset as removed. The delta carries only tombstones; replicas that have not received the inserts yet retain those tombstones until the matching nodes arrive.

func (*RGA) Insert 

func (r *RGA) Insert(offset int, value string) (Delta, error)

Insert inserts valid UTF-8 text before visible rune offset. It creates one node per Unicode scalar, so offset/count are rune based rather than byte based and can never split UTF-8.

func (*RGA) MarshalBinary 

func (r *RGA) MarshalBinary() ([]byte, error)

MarshalBinary returns the canonical framed RGA state.

func (*RGA) MarshalBinaryWithClockState 

func (r *RGA) MarshalBinaryWithClockState() ([]byte, clock.State, error)

func (*RGA) MarshalJSON added in v1.0.5 

func (r *RGA) MarshalJSON() ([]byte, error)

MarshalJSON returns a diagnostic summary for structured logs. It omits text content, positions, tombstone identities, and clock state.

func (*RGA) MarshalRunBinary added in v1.0.6 

func (r *RGA) MarshalRunBinary() ([]byte, error)

MarshalRunBinary encodes complete RGA state using the separately negotiated run-v2 frame. It retains v1 scalar Positions and is therefore safe to merge with v1 deltas after decoding.

func (*RGA) Merge 

func (r *RGA) Merge(other *RGA) error

func (*RGA) MissingParents added in v1.0.6 

func (r *RGA) MissingParents() []Position

MissingParents returns stable IDs that must arrive before pending nodes can integrate. The returned slice is sorted and safe for callers to retain.

func (*RGA) PendingCount added in v1.0.6 

func (r *RGA) PendingCount() int

PendingCount reports the number of accepted nodes still waiting for a missing parent. It is useful for replication diagnostics and backpressure.

func (*RGA) Positions 

func (r *RGA) Positions() []Position

Positions returns a copy of visible stable IDs in display order.

func (*RGA) Snapshot 

func (r *RGA) Snapshot(frontier map[string]crdt.Tag) (snapshot.Snapshot, error)

func (*RGA) SnapshotCurrentState 

func (r *RGA) SnapshotCurrentState() (snapshot.Snapshot, error)

func (*RGA) SnapshotRunCurrentState added in v1.0.6 

func (r *RGA) SnapshotRunCurrentState() (snapshot.Snapshot, error)

SnapshotRunCurrentState returns an HLC-backed, validated run-v2 snapshot.

func (*RGA) State 

func (r *RGA) State() crdt.StateSnapshot

func (*RGA) String 

func (r *RGA) String() string

func (*RGA) TombstoneTags added in v1.0.6 

func (r *RGA) TombstoneTags() []Position

TombstoneTags returns every retained deletion tag in canonical order. It is an acknowledgement input, not proof that a tag is safe to collect.

func (*RGA) UnmarshalBinary 

func (r *RGA) UnmarshalBinary(data []byte) error

func (*RGA) UnmarshalBinaryWithLimits 

func (r *RGA) UnmarshalBinaryWithLimits(data []byte, limits frame.DecoderLimits) error

func (*RGA) UnmarshalRunBinary added in v1.0.6 

func (r *RGA) UnmarshalRunBinary(data []byte) error

UnmarshalRunBinary installs one complete run-v2 RGA state frame.

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.