document

package
v0.5.0 Latest Latest
Warning

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

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

Documentation

Overview

Package document coordinates the piece tree, recovery WAL, transactional history, leased source generations, and atomic persistence.

Index

Constants

View Source 
const (
	// DefaultEventHistory is the number of recent Session events retained for
	// resumable subscriptions when OpenOptions does not specify a limit.
	DefaultEventHistory = 256
	// MaximumEventHistory bounds the memory retained by one Session event hub.
	MaximumEventHistory = 65_536
	// DefaultSubscriptionBuffer is used when SubscribeOptions.Buffer is zero.
	DefaultSubscriptionBuffer = 64
	// MaximumSubscriptionBuffer bounds one subscriber's pending event queue.
	MaximumSubscriptionBuffer = 4_096
)
View Source 
const (
	DefaultMaxBatchOperations  = 256
	DefaultMaxInsertBytes      = int64(1 << 20)
	DefaultUndoBytes           = int64(256 << 20)
	MaximumInsertBytes         = int64((1 << 30) - 24)
	DefaultChangeHistory       = 256
	MaximumChangeHistory       = 4_096
	DefaultMaxAnchorBatch      = 65_536
	MaximumAnchorBatch         = 1_048_576
	DefaultJournalSyncInterval = time.Second
)
View Source 
const (
	// DefaultStaleSessionAge limits automatic scanning to old crash artifacts.
	// A held marker lock always protects a live Session regardless of age.
	DefaultStaleSessionAge = 24 * time.Hour
)

Variables

View Source 
var (
	// ErrChangeHistoryExpired reports that at least one requested revision is
	// older than the earliest retained Session boundary.
	ErrChangeHistoryExpired = errors.New("document: change history expired")
	// ErrRevisionUnavailable reports a future revision or a revision inside an
	// atomic batch, neither of which is an observable Session state.
	ErrRevisionUnavailable = errors.New("document: revision is not an available session boundary")
)
View Source 
var (
	// ErrInvalidSubscription reports an invalid buffer or cursor combination.
	ErrInvalidSubscription = errors.New("document: invalid subscription options")
	// ErrEventSequence reports an AfterSequence newer than the Session stream.
	ErrEventSequence = errors.New("document: event sequence is in the future")
)
View Source 
var (
	ErrInvalidOptions = errors.New("document: invalid open options")
	ErrLimitExceeded  = errors.New("document: configured resource limit exceeded")
)
View Source 
var (
	ErrRevisionConflict    = errors.New("document: revision conflict")
	ErrInvalidUTF8         = errors.New("document: file is not UTF-8")
	ErrInvalidUTF8Boundary = errors.New("document: edit is not aligned to UTF-8 boundaries")
	ErrInvalidContext      = errors.New("document: nil context")
	ErrClosed              = errors.New("document: session closed")
	ErrNothingToUndo       = errors.New("document: nothing to undo")
	ErrNothingToRedo       = errors.New("document: nothing to redo")
	ErrExternalChange      = errors.New("document: file changed on disk")
	ErrRevisionOverflow    = errors.New("document: revision overflow")
	ErrFaulted             = errors.New("document: session is faulted and read-only")
)
View Source 
var ErrSessionInUse = errors.New("document: owned session directory is in use")

Functions

This section is empty.

Types

type ApplyResult 

type ApplyResult struct {
	Revision   uint64
	ByteLength int64
	Dirty      bool
	Changes    coordinate.ChangeMap
}

type ChangeHistoryError added in v0.4.0 

type ChangeHistoryError struct {
	FromRevision    uint64
	ToRevision      uint64
	OldestRevision  uint64
	CurrentRevision uint64
	Err             error
}

ChangeHistoryError reports the requested and retained revision windows while preserving ErrChangeHistoryExpired or ErrRevisionUnavailable via Unwrap.

func (*ChangeHistoryError) Error added in v0.4.0 

func (e *ChangeHistoryError) Error() string

func (*ChangeHistoryError) Unwrap added in v0.4.0 

func (e *ChangeHistoryError) Unwrap() error

type ChangeHistoryStats added in v0.4.0 

type ChangeHistoryStats struct {
	OldestRevision  uint64
	CurrentRevision uint64
	Entries         int
	Limit           int
}

ChangeHistoryStats describes the currently retained, contiguous ChangeMap window. OldestRevision and CurrentRevision are both queryable boundaries.

type ChangeOrigin added in v0.4.0 

type ChangeOrigin uint8

ChangeOrigin identifies the operation that produced an EventChanged map. 

const (
	// ChangeOriginNone is used by events that do not contain a ChangeMap.
	ChangeOriginNone ChangeOrigin = iota
	// ChangeOriginApply identifies a successful non-empty ApplyBatch.
	ChangeOriginApply
	// ChangeOriginUndo identifies a successful Undo transaction.
	ChangeOriginUndo
	// ChangeOriginRedo identifies a successful Redo transaction.
	ChangeOriginRedo
)

type CompactOptions added in v0.4.0 

type CompactOptions struct {
	CheckpointJournal bool
}

CompactOptions selects compaction that may perform persistence. Piece and undo compaction always run; CheckpointJournal additionally saves the current revision so the append-only recovery journal can be rebased safely.

type CompactionResult added in v0.4.0 

type CompactionResult struct {
	Metadata            Metadata
	Pieces              store.CompactResult
	UndoBytesBefore     int64
	UndoBytesAfter      int64
	JournalCheckpointed bool
}

CompactionResult describes structural reclamation without changing the document revision or content.

type DirectoryOwnership added in v0.4.0 

type DirectoryOwnership uint8
const (
	DirectoryOwnershipDefault DirectoryOwnership = iota
	DirectoryShared
	DirectoryOwned
)

type EOLStyle 

type EOLStyle string
const (
	EOLLF    EOLStyle = "lf"
	EOLCRLF  EOLStyle = "crlf"
	EOLMixed EOLStyle = "mixed"
)

type EventKind added in v0.4.0 

type EventKind uint8

EventKind identifies a Session lifecycle or content transition. 

const (
	// EventOpened is the first transition in every successfully opened Session.
	EventOpened EventKind = iota + 1
	// EventRecovered follows EventOpened when journal operations were replayed.
	EventRecovered
	// EventChanged reports one committed ApplyBatch, Undo, or Redo transaction.
	EventChanged
	// EventClosed is the last event and precedes subscription channel closure.
	EventClosed
	// EventSaveStarted begins a persistence attempt that will perform I/O.
	EventSaveStarted
	// EventSaveProgress reports monotonically increasing bytes written for one
	// persistence attempt.
	EventSaveProgress
	// EventSaved reports a committed persistence attempt. Cause may contain a
	// DurabilityError when replacement succeeded but directory sync did not.
	EventSaved
	// EventSaveFailed reports an attempt that did not complete normally.
	// Persistence.Committed distinguishes pre-commit failure from a permanent
	// post-commit Session fault.
	EventSaveFailed
	// EventJournalSyncFailed reports the transition from a healthy recovery WAL
	// to a failed background or close-time Sync.
	EventJournalSyncFailed
	// EventJournalSyncRestored reports the first successful Sync or clean save
	// checkpoint after EventJournalSyncFailed.
	EventJournalSyncRestored
)

type Metadata 

type Metadata struct {
	Path                string
	ResolvedPath        string
	Name                string
	ByteLength          int64
	Revision            uint64
	CommittedRevision   uint64
	Dirty               bool
	Recovered           bool
	HasBOM              bool
	EOL                 EOLStyle
	DurabilityUncertain bool
	// RecoveryDurabilityUncertain reports a failed Sync of the recovery WAL.
	// The logical document remains readable and editable, but the newest edits
	// may not survive sudden power loss until a later Sync or save succeeds.
	RecoveryDurabilityUncertain bool
	PersistenceFaulted          bool
}

type OpenOptions 

type OpenOptions struct {
	RecoveryDir          string
	SessionDir           string
	RecoveryDirOwnership DirectoryOwnership
	SessionDirOwnership  DirectoryOwnership
	Limits               SessionLimits
	JournalSyncInterval  time.Duration
}

type PersistenceProgress added in v0.4.0 

type PersistenceProgress struct {
	OperationID    uint64
	TargetRevision uint64
	CompletedBytes int64
	TotalBytes     int64
	Committed      bool
}

PersistenceProgress correlates save events. CompletedBytes is monotonic for an Operation and never exceeds TotalBytes. TargetRevision is the immutable Snapshot selected when the attempt began.

type ReclaimStats added in v0.4.0 

type ReclaimStats struct {
	Scanned   int
	Reclaimed int
	Skipped   int
}

ReclaimStats reports conservative owned-session directory cleanup.

func ReclaimStaleSessionDirectories added in v0.4.0 

func ReclaimStaleSessionDirectories(root string, before time.Time) (ReclaimStats, error)

ReclaimStaleSessionDirectories removes crash leftovers created by Docengine below root and older than before. Directories with a live marker lock, malformed markers, symlinks, or any unrecognized entry are preserved.

type RecoveryOpenError added in v0.3.0 

type RecoveryOpenError struct {
	JournalPath     string
	QuarantinedPath string
	Reason          string
	Err             error
}

func (*RecoveryOpenError) Error added in v0.3.0 

func (e *RecoveryOpenError) Error() string

func (*RecoveryOpenError) Unwrap added in v0.3.0 

func (e *RecoveryOpenError) Unwrap() error

type ReplaceOperation 

type ReplaceOperation struct {
	Start        int64
	DeleteLength int64
	Insert       string
}

type Session 

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

func Open 

func Open(path string, options OpenOptions) (*Session, error)

func OpenContext added in v0.3.0 

func OpenContext(ctx context.Context, path string, options OpenOptions) (*Session, error)

func (*Session) ApplyBatch 

func (s *Session) ApplyBatch(ctx context.Context, expectedRevision uint64, operations []ReplaceOperation) (ApplyResult, error)

func (*Session) ChangeHistoryStats added in v0.4.0 

func (s *Session) ChangeHistoryStats() ChangeHistoryStats

ChangeHistoryStats returns the retained revision window. It remains available after Close.

func (*Session) ChangesBetween added in v0.4.0 

func (s *Session) ChangesBetween(fromRevision, toRevision uint64) (coordinate.ChangeMap, error)

ChangesBetween composes the retained maps between two observable Session boundaries. Reverse queries return the inverse map. It remains available after Close because it does not access document Sources.

func (*Session) Close 

func (s *Session) Close() error

func (*Session) CommitAtLeast 

func (s *Session) CommitAtLeast(expectedRevision uint64) (result Metadata, resultErr error)

CommitAtLeast atomically persists a snapshot whose revision is at least the requested revision. New edits continue in the current generation while the snapshot is streamed.

func (*Session) Compact added in v0.4.0 

func (s *Session) Compact(ctx context.Context, options CompactOptions) (CompactionResult, error)

Compact coalesces adjacent Piece Tree fragments and rewrites the undo store to contain only live history references. Journal compaction is an explicit persistence checkpoint because rewriting an uncommitted WAL in place cannot preserve both revision identity and crash atomicity.

func (*Session) Config added in v0.4.0 

func (s *Session) Config() SessionConfig

Config returns the immutable, fully resolved resource and directory policy used by this Session. It remains available after Close.

func (*Session) CoordinateIndex added in v0.4.0 

func (s *Session) CoordinateIndex(ctx context.Context, options coordinate.Options) (*coordinate.Index, error)

CoordinateIndex builds a bounded-query UTF-8 coordinate index for one immutable Session revision. The returned Index owns its Snapshot lease and must be closed by the caller.

func (*Session) Fault added in v0.3.0 

func (s *Session) Fault() error

Fault returns the cause that placed this Session into its permanent read-only state. It returns nil for a healthy Session.

func (*Session) Metadata 

func (s *Session) Metadata() Metadata

func (*Session) ReadAt 

func (s *Session) ReadAt(p []byte, off int64) (int, error)

func (*Session) RebuildCoordinateIndex added in v0.4.0 

func (s *Session) RebuildCoordinateIndex(ctx context.Context, previous *coordinate.Index, changes coordinate.ChangeMap) (*coordinate.Index, error)

RebuildCoordinateIndex derives the current revision's index from a previous Session index and the exact ChangeMap chain between them. The new index keeps its own Snapshot lease; the previous index remains independently usable.

func (*Session) Redo 

func (s *Session) Redo() (ApplyResult, error)

func (*Session) RefreshCoordinateIndex added in v0.4.0 

func (s *Session) RefreshCoordinateIndex(ctx context.Context, previous *coordinate.Index) (*coordinate.Index, error)

RefreshCoordinateIndex rebuilds the current index from a previous index made by this Session and the retained ChangeMap chain between revisions.

func (*Session) Save 

func (s *Session) Save() (Metadata, error)

func (*Session) Snapshot 

func (s *Session) Snapshot() (uint64, SnapshotLease, error)

func (*Session) Subscribe added in v0.4.0 

func (s *Session) Subscribe(options SubscribeOptions) (*Subscription, error)

Subscribe creates a nonblocking, ordered Session event stream. Historical replay and live publication are joined atomically with respect to Session transitions.

func (*Session) TransformAnchors added in v0.4.0 

func (s *Session) TransformAnchors(fromRevision, toRevision uint64, anchors []coordinate.Anchor) ([]coordinate.Anchor, error)

TransformAnchors applies the retained map between two revisions to an anchor batch. Input order is preserved and invalid input returns no partial result.

func (*Session) TransformRanges added in v0.4.0 

func (s *Session) TransformRanges(fromRevision, toRevision uint64, values []coordinate.AnchoredRange) ([]coordinate.AnchoredRange, error)

TransformRanges applies the retained map between two revisions to a batch of format-neutral anchored ranges. Input order and endpoint affinities are preserved, and validation is atomic.

func (*Session) Undo 

func (s *Session) Undo() (ApplyResult, error)

func (*Session) VirtualPager added in v0.5.0 

func (s *Session) VirtualPager(ctx context.Context, options virtual.Options) (*virtual.Pager, error)

VirtualPager builds a format-neutral logical Page and Fragment pager for one immutable Session revision. The returned Pager owns its Snapshot lease and must be closed by the caller.

type SessionConfig added in v0.4.0 

type SessionConfig struct {
	RecoveryDir          string
	SessionDir           string
	RecoveryDirOwnership DirectoryOwnership
	SessionDirOwnership  DirectoryOwnership
	Limits               SessionLimits
	JournalSyncInterval  time.Duration
}

SessionConfig is the fully resolved immutable configuration of an open Session. DirectoryOwnershipDefault never appears in a resolved config.

type SessionEvent added in v0.4.0 

type SessionEvent struct {
	Sequence    uint64
	Dropped     uint64
	Kind        EventKind
	Origin      ChangeOrigin
	Metadata    Metadata
	Changes     coordinate.ChangeMap
	Persistence PersistenceProgress
	Cause       error
}

SessionEvent is an immutable state transition. Dropped is specific to one subscription and reports how many preceding events were omitted before this delivery. Consumers that observe a drop must rebuild derived state from the event Metadata and a matching Snapshot instead of applying Changes blindly.

type SessionLimits added in v0.4.0 

type SessionLimits struct {
	MaxBatchOperations int
	MaxInsertBytes     int64
	UndoBytes          int64
	EventHistory       int
	ChangeHistory      int
	MaxAnchorBatch     int
}

type SnapshotLease 

type SnapshotLease interface {
	io.ReaderAt
	Len() int64
	WriteTo(io.Writer) (int64, error)
	Close() error
}

SnapshotLease keeps every source used by a snapshot alive until Close. Callers must release the lease when they finish reading or saving a snapshot.

type SubscribeOptions added in v0.4.0 

type SubscribeOptions struct {
	Buffer        int
	AfterSequence uint64
	FutureOnly    bool
}

SubscribeOptions controls replay and buffering for a Session subscription. AfterSequence resumes after a previously observed event. FutureOnly skips retained history and cannot be combined with AfterSequence.

type Subscription added in v0.4.0 

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

Subscription is a nonblocking Session event stream. Events returns a channel that is closed by Subscription.Close or after the Session close barrier.

func (*Subscription) Close added in v0.4.0 

func (s *Subscription) Close() error

Close detaches the subscription and closes its event channel. It is idempotent and does not close the Session.

func (*Subscription) Events added in v0.4.0 

func (s *Subscription) Events() <-chan SessionEvent

Events returns the ordered delivery channel for this subscription.

Source Files

View all Source files

Directories

Path Synopsis
Package coordinate provides format-neutral UTF-8 coordinate indexes, anchors, and cross-revision change maps.
 Package coordinate provides format-neutral UTF-8 coordinate indexes, anchors, and cross-revision change maps.
Package save contains streaming, crash-safe document persistence.
 Package save contains streaming, crash-safe document persistence.
Package store implements a bounded-memory source store for large documents.
 Package store implements a bounded-memory source store for large documents.
Package virtual provides format-neutral, revision-bound document virtualization.
 Package virtual provides format-neutral, revision-bound document virtualization.

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.