Documentation
¶
Overview ¶
Package shared provides a small, Yjs-style document facade over the bounded document-tree-v2 CRDT. It intentionally keeps authentication, authorization, transport, durable outboxes, and recovery storage with the host application.
Index ¶
- Variables
- func Profile() crdt.ReplicationProfile
- type Array
- func (a *Array) Array(index int) (*Array, bool)
- func (a *Array) Delete(index, count int) error
- func (a *Array) Get(index int) ([]byte, bool)
- func (a *Array) Insert(index int, value []byte) error
- func (a *Array) InsertArray(index int) (*Array, error)
- func (a *Array) InsertJSON(index int, value any) error
- func (a *Array) InsertMap(index int) (*Map, error)
- func (a *Array) InsertString(index int, value string) error
- func (a *Array) JSON(index int, target any) (bool, error)
- func (a *Array) Len() int
- func (a *Array) Map(index int) (*Map, bool)
- func (a *Array) String(index int) (string, bool)
- type Checkpoint
- type Document
- func (d *Document) ApplyUpdate(update []byte) error
- func (d *Document) Array(name string) (*Array, error)
- func (d *Document) Checkpoint() (Checkpoint, error)
- func (d *Document) LookupArray(name string) (*Array, bool)
- func (d *Document) LookupMap(name string) (*Map, bool)
- func (d *Document) Map(name string) (*Map, error)
- func (d *Document) OnUpdate(handler UpdateHandler) (func(), error)
- func (d *Document) Options() Options
- func (d *Document) State() crdt.StateSnapshot
- type Map
- func (m *Map) Array(key string) (*Array, bool)
- func (m *Map) CreateArray(key string) (*Array, error)
- func (m *Map) CreateMap(key string) (*Map, error)
- func (m *Map) Delete(key string) error
- func (m *Map) Get(key string) ([]byte, bool)
- func (m *Map) JSON(key string, target any) (bool, error)
- func (m *Map) Keys() []string
- func (m *Map) Map(key string) (*Map, bool)
- func (m *Map) Set(key string, value []byte) error
- func (m *Map) SetJSON(key string, value any) error
- func (m *Map) SetString(key, value string) error
- func (m *Map) String(key string) (string, bool)
- type Options
- type UpdateHandler
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNilDocument reports an operation on a nil shared document. ErrNilDocument = errors.New("shared: nil document") // ErrNilMap reports an operation on a nil shared map. ErrNilMap = errors.New("shared: nil map") // ErrNilArray reports an operation on a nil shared array. ErrNilArray = errors.New("shared: nil array") // ErrNilUpdateHandler reports a nil local-update subscriber. ErrNilUpdateHandler = errors.New("shared: nil update handler") // ErrValueKind reports an attempt to read an object or subdocument as bytes. ErrValueKind = errors.New("shared: value is not bytes") )
Functions ¶
func Profile ¶
func Profile() crdt.ReplicationProfile
Profile returns the exact stable profile used by every shared document. It is guidance and protocol metadata only: the host still authenticates the resulting manifest and authorizes every received update.
Types ¶
type Array ¶
type Array struct {
// contains filtered or unexported fields
}
Array is a named or nested shared array.
func (*Array) InsertArray ¶
InsertArray creates a nested array at index.
func (*Array) InsertJSON ¶
InsertJSON marshals value as JSON before inserting it at index.
func (*Array) InsertString ¶
InsertString stores a UTF-8 string at index.
type Checkpoint ¶
Checkpoint is one recovery unit for a shared document. State and ClockState are both required; storing only State can reuse HLC tags after a restart.
type Document ¶
type Document struct {
// contains filtered or unexported fields
}
Document owns named Map and Array roots plus local update subscriptions. It is document-tree-v2, not a Yjs wire-compatible document. Its high-level methods intentionally hide delta construction; OnUpdate exposes the already bounded canonical frame at the transport boundary.
func New ¶
New creates a shared document with conservative local defaults. It is useful for a prototype or a process-local document. Networked applications should use NewWithLimits or NewWithOptions so the receive budget is deliberate.
func NewWithLimits ¶
func NewWithLimits(replicaID string, limits frame.DecoderLimits) (*Document, error)
NewWithLimits creates a document with default retained-state limits and one explicit frame budget for both updates it emits and updates it receives.
func NewWithOptions ¶
NewWithOptions creates a document with explicit retention and frame limits. An invalid frame budget is rejected before the document can be used.
func Restore ¶
func Restore(checkpoint Checkpoint, options Options) (*Document, error)
Restore creates a document from a complete checkpoint made by Checkpoint. The checkpoint and its HLC state must have been persisted atomically before reusing the same replica ID.
func (*Document) ApplyUpdate ¶
ApplyUpdate validates and applies an untrusted canonical update frame. The host must authenticate and authorize the peer and cap its transport body before calling this method; a profile, checksum, or successful decode is not authorization. Repeated and reordered accepted updates converge safely.
func (*Document) Array ¶
Array returns the named shared array, creating its root on first local use. Creation emits an update like any other local mutation.
func (*Document) Checkpoint ¶
func (d *Document) Checkpoint() (Checkpoint, error)
Checkpoint returns a complete state frame and HLC state that must be stored atomically before this replica ID is reused after restart.
func (*Document) LookupArray ¶ added in v1.0.33
LookupArray returns the current visible named Array without creating a root or emitting a local update. It returns false for an absent, incomplete, or Map root, and for invalid names.
func (*Document) LookupMap ¶ added in v1.0.33
LookupMap returns the current visible named Map without creating a root or emitting a local update. It returns false for an absent, incomplete, or Array root, and for invalid names.
func (*Document) Map ¶
Map returns the named shared map, creating its root on first local use. Creation emits an update like any other local mutation. A name that already denotes an Array returns documenttree.ErrTypeMismatch.
func (*Document) OnUpdate ¶
func (d *Document) OnUpdate(handler UpdateHandler) (func(), error)
OnUpdate subscribes to locally created update frames. The returned function is safe to call multiple times and from an update callback.
func (*Document) State ¶
func (d *Document) State() crdt.StateSnapshot
State reports structural diagnostics without exposing document values.
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map is a named or nested shared map. All mutating methods emit one local update after the underlying document-tree operation succeeds.
func (*Map) CreateArray ¶
CreateArray creates a nested shared array at key.
type Options ¶
type Options struct {
DocumentOptions documenttree.Options
FrameLimits frame.DecoderLimits
}
Options owns the local retention and frame budgets for one shared document. FrameLimits applies to both locally emitted updates and untrusted received updates. Production peers must negotiate compatible values and reject an oversized transport body before calling ApplyUpdate.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns conservative per-document and frame limits for local development. A production group should use NewWithOptions with limits tied to its authenticated schema, tenant quota, and transport body limit.
type UpdateHandler ¶
type UpdateHandler func(update []byte)
UpdateHandler receives one owned, canonical document-tree delta frame after a local successful mutation. It is called without an internal lock, may unsubscribe itself, and should hand the bytes to an outbox rather than doing blocking network I/O inline.
The handler runs after the local state mutation. A host must durably record its own outbox and checkpoint according to its delivery guarantees.
Source Files