document

package
v0.8.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: 24 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)
	DefaultMaxJournalBytes     = int64(4 << 30)
	MinimumJournalBytes        = int64(96 + 64 + 24)
	MaximumInsertBytes         = int64((1 << 30) - 24)
	DefaultChangeHistory       = 256
	MaximumChangeHistory       = 4_096
	DefaultMaxAnchorBatch      = 65_536
	MaximumAnchorBatch         = 1_048_576
	DefaultMaxSnapshotLeases   = 1_024
	MaximumSnapshotLeases      = 1_048_576
	DefaultMaxSubscriptions    = 128
	MaximumSubscriptions       = 4_096
	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 CompactionProgress added in v0.5.6 

type CompactionProgress struct {
	OperationID         uint64
	CompletedBytes      int64
	TotalBytes          int64
	PiecesBefore        int64
	PiecesAfter         int64
	JournalCheckpointed bool
	Committed           bool
}

CompactionProgress correlates compaction events. TotalBytes is the exact unique live undo payload selected by the attempt. CompletedBytes is monotonic and never exceeds it.

type CompactionResult added in v0.4.0 

type CompactionResult struct {
	OperationID         uint64
	Metadata            Metadata
	Pieces              store.CompactResult
	UndoBytesBefore     int64
	UndoBytesAfter      int64
	JournalCheckpointed bool
	Committed           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
	// EventCompactionStarted begins structural and undo-store reclamation.
	EventCompactionStarted
	// EventCompactionProgress reports monotonically increasing live undo bytes
	// copied into the candidate replacement store.
	EventCompactionProgress
	// EventCompacted reports a successfully committed compaction attempt.
	EventCompacted
	// EventCompactionFailed reports a compaction error. Compaction.Committed
	// distinguishes a discarded candidate from committed cleanup failure.
	EventCompactionFailed
	// EventVirtualizationStarted begins one Fragment publication or refresh.
	EventVirtualizationStarted
	// EventVirtualizationProgress reports a provider watermark advance.
	EventVirtualizationProgress
	// EventVirtualizationCompleted reports an atomically published generation.
	EventVirtualizationCompleted
	// EventVirtualizationFailed reports a rejected or canceled publication.
	EventVirtualizationFailed
)

type EventStats added in v0.5.6 

type EventStats struct {
	Sequence             uint64
	HistoryEntries       int
	MaximumHistory       int
	Subscriptions        int
	MaximumSubscriptions int
	DiscardedDeliveries  uint64
	HistoryGapEvents     uint64
	SequenceExhausted    bool
	Closed               bool
}

EventStats is an atomic view of retained history, live subscriptions, and subscriber-specific delivery loss. It remains available after Session close.

type LifecycleStats added in v0.5.4 

type LifecycleStats struct {
	ActiveSnapshotLeases       int
	PeakSnapshotLeases         int
	MaxSnapshotLeases          int
	WaitingSaves               int
	SaveActive                 bool
	AutomaticCheckpointPending bool
	Closing                    bool
	Closed                     bool
}

LifecycleStats is an atomic view of host-owned leases, serialized saves, and shutdown. Closing means shutdown was requested but resource retirement has not completed; Closed means the shared close barrier has completed.

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
	// AutoCheckpointJournalBytes enables background save checkpoints when the
	// recovery journal reaches this physical size. Zero disables automatic
	// checkpoints; the hard MaxJournalBytes limit still applies.
	AutoCheckpointJournalBytes int64
}

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 RecoveryStats added in v0.5.3 

type RecoveryStats struct {
	JournalBytes              int64
	MaxJournalBytes           int64
	AutoCheckpointBytes       int64
	NextAutoCheckpointBytes   int64
	AutomaticCheckpoints      uint64
	AutomaticCheckpointQueued bool
}

RecoveryStats is an atomic view of recovery-journal growth and automatic checkpoint scheduling. JournalBytes is zero while no journal is open.

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) CloseContext added in v0.5.4 

func (s *Session) CloseContext(ctx context.Context) error

CloseContext starts the one shared shutdown and waits for its resource barrier. If ctx expires, cleanup continues independently; a later Close or CloseContext observes the same final result.

func (*Session) CommitAtLeast 

func (s *Session) CommitAtLeast(expectedRevision uint64) (Metadata, 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) CommitAtLeastContext added in v0.5.4 

func (s *Session) CommitAtLeastContext(ctx context.Context, expectedRevision uint64) (result Metadata, resultErr error)

CommitAtLeastContext is CommitAtLeast with bounded waiting and streaming cancellation. Close rejects queued saves and cancels Session-owned automatic checkpoints; an already active host save is governed by its caller's ctx.

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) EventStats added in v0.5.6 

func (s *Session) EventStats() EventStats

EventStats returns event-history, subscription-budget, and delivery-loss statistics. It remains available after Close.

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) LifecycleStats added in v0.5.4 

func (s *Session) LifecycleStats() LifecycleStats

LifecycleStats returns bounded host-resource and shutdown state without touching the filesystem. It remains available after Close.

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) RecoveryStats added in v0.5.3 

func (s *Session) RecoveryStats() RecoveryStats

RecoveryStats returns recovery-journal growth and checkpoint scheduling state without touching the filesystem. It remains available after Close.

func (*Session) Redo 

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

func (*Session) RedoContext added in v0.5.4 

func (s *Session) RedoContext(ctx context.Context) (ApplyResult, error)

RedoContext reapplies the newest forward transaction. Cancellation before publication leaves the current revision and history stacks unchanged.

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) RefreshSearchIndex added in v0.6.0 

func (s *Session) RefreshSearchIndex(ctx context.Context, previous *documentsearch.Index) (*documentsearch.Index, error)

RefreshSearchIndex derives the current revision from an Index created by this Session and the exact retained ChangeMap chain. The previous Index remains independently queryable.

func (*Session) RefreshVirtualPager added in v0.5.7 

func (s *Session) RefreshVirtualPager(ctx context.Context, previous *virtual.Pager, provider virtual.FragmentProvider) (*virtual.Pager, error)

RefreshVirtualPager builds the current revision with the previous Pager's exact resource policy and lineage, then optionally asks provider to publish a Fragment generation. The previous Pager remains independently usable.

func (*Session) Save 

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

func (*Session) SaveContext added in v0.5.4 

func (s *Session) SaveContext(ctx context.Context) (Metadata, error)

SaveContext persists the newest revision. Cancellation while waiting for the save serializer or streaming the temporary file leaves the base unchanged. Once atomic replacement commits, the committed result takes precedence over later cancellation.

func (*Session) SearchIndex added in v0.6.0 

func (s *Session) SearchIndex(ctx context.Context, options documentsearch.IndexOptions) (*documentsearch.Index, error)

SearchIndex opens or builds a persistent format-neutral candidate index for the current immutable revision. The returned Index owns its Snapshot lease and must be closed by the caller.

func (*Session) Snapshot 

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

Snapshot returns an immutable lease for the current revision. The caller must Close it; all host-facing Snapshot consumers share MaxSnapshotLeases.

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) UndoContext added in v0.5.4 

func (s *Session) UndoContext(ctx context.Context) (ApplyResult, error)

UndoContext applies the newest inverse transaction. Cancellation before publication leaves the current revision and history stacks unchanged.

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
	AutoCheckpointJournalBytes int64
}

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
	Compaction     CompactionProgress
	Virtualization virtual.Progress
	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
	MaxJournalBytes    int64
	EventHistory       int
	ChangeHistory      int
	MaxAnchorBatch     int
	// MaxSnapshotLeases bounds host-owned Snapshot, coordinate Index, and
	// virtual Pager leases across all current and retired source generations.
	MaxSnapshotLeases int
	// MaxSubscriptions bounds concurrent Session event subscriptions.
	MaxSubscriptions 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 composition builds immutable, format-neutral virtual documents from ordered ranges of immutable UTF-8 byte sources.
 Package composition builds immutable, format-neutral virtual documents from ordered ranges of immutable UTF-8 byte sources.
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 interval provides revision-bound persistent interval sets.
 Package interval provides revision-bound persistent interval sets.
Package save contains streaming, crash-safe document persistence.
 Package save contains streaming, crash-safe document persistence.
Package search provides format-neutral, revision-bound search over immutable UTF-8 byte sources.
 Package search provides format-neutral, revision-bound search over immutable UTF-8 byte sources.
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.