commitlog

package
v0.6.1 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const (
	CommandFrameVersion uint16 = 1

	CommandWALNonCriticalFlagStart uint64 = 1 << 32
)
View Source 
const (
	Version = 1

	OpSetRID    = byte(0)
	OpSetInline = byte(1)
	OpDelete    = byte(2)
	// OpSetInlineZero stores an inline zero-filled value without carrying the
	// value bytes. Readers normalize it back to OpSetInline.
	OpSetInlineZero = byte(3)
)
View Source 
const MaxCommandJournalLane = 1023

Variables

View Source 
var (
	ErrCorrupt                           = errors.New("commitlog: corrupt record")
	ErrRecordTooLarge                    = errors.New("commitlog: record too large")
	ErrMixedBatchSeq                     = errors.New("commitlog: mixed batch sequence")
	ErrCommandWALTerminalTail            = errors.New("commitlog: command wal terminal incomplete tail")
	ErrCommandWALLegacyPayload           = errors.New("commitlog: legacy raw payload in command wal")
	ErrCommandWALUnsupportedVersion      = errors.New("commitlog: command wal unsupported version")
	ErrCommandWALUnsupportedKind         = errors.New("commitlog: command wal unsupported kind")
	ErrCommandWALUnsupportedCriticalFlag = errors.New("commitlog: command wal unsupported critical flag")
	ErrCommandWALDuplicateLSN            = errors.New("commitlog: command wal duplicate lsn")
	ErrCommandWALStaleSegment            = errors.New("commitlog: command wal stale segment")
	ErrCommandWALSegmentSeqExhausted     = errors.New("commitlog: command wal segment sequence exhausted")
	ErrJournalOwnerExists                = errors.New("commitlog: journal owner already exists")
)

Functions

func CommandSegmentName added in v0.6.0 

func CommandSegmentName(lane int, seq uint64) string

func EncodeCatalogCreateCollectionPayload added in v0.6.0 

func EncodeCatalogCreateCollectionPayload(collection string, metadata []byte) ([]byte, error)

func EncodeCollectionDeleteBatchByIDPayload added in v0.6.0 

func EncodeCollectionDeleteBatchByIDPayload(collection string, ids [][]byte) ([]byte, error)

func EncodeCollectionInsertBatchByIDPayload added in v0.6.0 

func EncodeCollectionInsertBatchByIDPayload(collection string, docs []CollectionDocument) ([]byte, error)

func EncodeCollectionRebuildVectorIndexPayload added in v0.6.0 

func EncodeCollectionRebuildVectorIndexPayload(collection, indexName string) ([]byte, error)

func EncodeCollectionUpdateBatchByIDPayload added in v0.6.0 

func EncodeCollectionUpdateBatchByIDPayload(collection string, docs []CollectionDocument) ([]byte, error)

func EncodeCommandFrame added in v0.6.0 

func EncodeCommandFrame(env CommandEnvelope) ([]byte, error)

func EncodeRawKVBatchPayload added in v0.6.0 

func EncodeRawKVBatchPayload(ops []RawKVOperation) ([]byte, error)

func EncodeRawKVBatchPayloadPlanned added in v0.6.1 

func EncodeRawKVBatchPayloadPlanned(plan RawKVBatchPayloadPlan, scan RawKVBatchOperationScanner) ([]byte, error)

EncodeRawKVBatchPayloadPlanned encodes a caller-planned RawKVBatch scan. It is for callers that already validated the scan with PlanRawKVBatchPayloadScan and need the exact planned format, including revision-bearing payloads.

func EncodeRawKVBatchPayloadScan added in v0.6.0 

func EncodeRawKVBatchPayloadScan(scan func(func(RawKVOperation) error) error) ([]byte, error)

EncodeRawKVBatchPayloadScan encodes a RawKVBatch payload by scanning the caller's operation source once. It avoids materializing a []RawKVOperation when the caller already owns a replayable batch representation.

func EncodeRawKVBatchPayloadScanWithHint added in v0.6.0 

func EncodeRawKVBatchPayloadScanWithHint(scan func(func(RawKVOperation) error) error, opHint, byteHint int) ([]byte, error)

EncodeRawKVBatchPayloadScanWithHint is EncodeRawKVBatchPayloadScan with best-effort capacity hints. opHint is an approximate operation count and byteHint is an approximate total key+value byte count.

func EncodeRawKVSingleOperationPayload added in v0.6.0 

func EncodeRawKVSingleOperationPayload(op RawKVOperation) ([]byte, error)

EncodeRawKVSingleOperationPayload encodes the common one-op RawKVBatch command without forcing callers to materialize a single-entry operation slice.

func IsCommandSegmentName added in v0.6.0 

func IsCommandSegmentName(name string) bool

IsCommandSegmentName reports whether name matches the command WAL segment naming grammar used by CommandSegmentName.

func ScanRawKVBatchPayload added in v0.6.0 

func ScanRawKVBatchPayload(payload []byte, visit func(op RawKVOp, key, value []byte) error) error

ScanRawKVBatchPayload validates payload and visits each op with slices that reference payload. For RawKVOpSetRID, value is exactly the 8-byte little-endian RID payload. Use DecodeRawKVBatchPayload when callers need owned copies or typed RID fields.

func ScanRawKVBatchPayloadWithRevision added in v0.6.1 

func ScanRawKVBatchPayloadWithRevision(payload []byte, visit func(op RawKVOp, key, value []byte, revision uint64) error) error

ScanRawKVBatchPayloadWithRevision is ScanRawKVBatchPayload plus the optional per-entry revision carried by revision-aware RawKV payloads. Legacy and compact-zero payloads report revision zero for every operation.

Types

type CatalogCreateCollectionPayload added in v0.6.0 

type CatalogCreateCollectionPayload struct {
	Collection string
	Metadata   []byte
}

func DecodeCatalogCreateCollectionPayload added in v0.6.0 

func DecodeCatalogCreateCollectionPayload(payload []byte) (CatalogCreateCollectionPayload, error)

type CollectionDeleteBatchByIDPayload added in v0.6.0 

type CollectionDeleteBatchByIDPayload struct {
	Collection string
	IDs        [][]byte
}

func DecodeCollectionDeleteBatchByIDPayload added in v0.6.0 

func DecodeCollectionDeleteBatchByIDPayload(payload []byte) (CollectionDeleteBatchByIDPayload, error)

type CollectionDocument added in v0.6.0 

type CollectionDocument struct {
	ID       []byte
	Document []byte
}

type CollectionInsertBatchByIDPayload added in v0.6.0 

type CollectionInsertBatchByIDPayload struct {
	Collection string
	Documents  []CollectionDocument
}

func DecodeCollectionInsertBatchByIDPayload added in v0.6.0 

func DecodeCollectionInsertBatchByIDPayload(payload []byte) (CollectionInsertBatchByIDPayload, error)

type CollectionRebuildVectorIndexPayload added in v0.6.0 

type CollectionRebuildVectorIndexPayload struct {
	Collection string
	IndexName  string
}

func DecodeCollectionRebuildVectorIndexPayload added in v0.6.0 

func DecodeCollectionRebuildVectorIndexPayload(payload []byte) (CollectionRebuildVectorIndexPayload, error)

type CollectionUpdateBatchByIDPayload added in v0.6.0 

type CollectionUpdateBatchByIDPayload struct {
	Collection string
	Documents  []CollectionDocument
}

func DecodeCollectionUpdateBatchByIDPayload added in v0.6.0 

func DecodeCollectionUpdateBatchByIDPayload(payload []byte) (CollectionUpdateBatchByIDPayload, error)

type CommandEnvelope added in v0.6.0 

type CommandEnvelope struct {
	Version          uint16
	LSN              uint64
	Kind             CommandKind
	Scope            CommandScope
	FeatureFlags     uint64
	CatalogEpoch     uint64
	SchemaEpoch      uint64
	BaseAppliedLSN   uint64
	PayloadFormat    PayloadFormat
	Payload          []byte
	ExternalRefs     []ExternalRef
	Preconditions    []CommandExtension
	ResultAssertions []CommandExtension
}

func DecodeCommandFrame added in v0.6.0 

func DecodeCommandFrame(frame []byte) (CommandEnvelope, error)

func ScanCommandFrameSegments added in v0.6.0 

func ScanCommandFrameSegments(paths []string, opts Options) ([]CommandEnvelope, error)

func ScanCommandFrames added in v0.6.0 

func ScanCommandFrames(path string, opts Options) ([]CommandEnvelope, error)

type CommandExtension added in v0.6.0 

type CommandExtension struct {
	Type    uint16
	Payload []byte
}

type CommandJournal added in v0.6.0 

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

func OpenCommandJournal added in v0.6.0 

func OpenCommandJournal(walDir string, opts CommandJournalOptions) (*CommandJournal, error)

func (*CommandJournal) ActiveBytes added in v0.6.0 

func (j *CommandJournal) ActiveBytes() int64

func (*CommandJournal) ActiveSegmentSnapshot added in v0.6.0 

func (j *CommandJournal) ActiveSegmentSnapshot() (path string, bytes int64)

ActiveSegmentSnapshot reports the active segment path and accepted bytes under one journal lock acquisition.

func (*CommandJournal) AppendCommand added in v0.6.0 

func (j *CommandJournal) AppendCommand(env CommandEnvelope) (uint64, error)

AppendCommand validates a complete command frame, assigns the next journal LSN, and appends it through this lane's single writer while holding the journal mutex. This intentionally optimizes for deterministic frame order and tail-only rollback, not parallel appends within one lane.

func (*CommandJournal) AppendCommandPayloadTrusted added in v0.6.0 

func (j *CommandJournal) AppendCommandPayloadTrusted(kind CommandKind, scope CommandScope, format PayloadFormat, baseAppliedLSN uint64, payload []byte) (uint64, error)

AppendCommandPayloadTrusted appends a caller-validated canonical command payload. It validates only command identity and frame size; callers must use this only for payloads built by the matching commitlog encoder.

func (*CommandJournal) AppendRawKVBatchPayloadCommand added in v0.6.0 

func (j *CommandJournal) AppendRawKVBatchPayloadCommand(baseAppliedLSN uint64, payload []byte) (uint64, error)

func (*CommandJournal) AppendRawKVBatchPayloadCommandTrusted added in v0.6.0 

func (j *CommandJournal) AppendRawKVBatchPayloadCommandTrusted(baseAppliedLSN uint64, payload []byte) (uint64, error)

AppendRawKVBatchPayloadCommandTrusted appends a caller-validated canonical RawKVBatch payload.

func (*CommandJournal) AppendRawKVBatchPayloadCommandTrustedAndFlush added in v0.6.0 

func (j *CommandJournal) AppendRawKVBatchPayloadCommandTrustedAndFlush(baseAppliedLSN uint64, payload []byte, sync bool) (uint64, error)

AppendRawKVBatchPayloadCommandTrustedAndFlush appends a caller-validated RawKVBatch payload and flushes/syncs the writer while holding the journal lock. If the append succeeds but the flush fails, the allocated LSN is returned with the flush error so callers can preserve the commit-ambiguous command-WAL failure contract.

func (*CommandJournal) AppendRawKVBatchPayloadScanCommandTrusted added in v0.6.0 

func (j *CommandJournal) AppendRawKVBatchPayloadScanCommandTrusted(baseAppliedLSN uint64, plan RawKVBatchPayloadPlan, scan RawKVBatchOperationScanner) (uint64, error)

AppendRawKVBatchPayloadScanCommandTrusted appends a caller-validated replayable RawKVBatch operation source without materializing the canonical payload slice.

func (*CommandJournal) AppendRawKVBatchPayloadScanCommandTrustedAndFlush added in v0.6.0 

func (j *CommandJournal) AppendRawKVBatchPayloadScanCommandTrustedAndFlush(baseAppliedLSN uint64, plan RawKVBatchPayloadPlan, scan RawKVBatchOperationScanner, sync bool) (uint64, error)

AppendRawKVBatchPayloadScanCommandTrustedAndFlush appends a caller-validated replayable RawKVBatch operation source and flushes/syncs the writer while holding the journal lock.

func (*CommandJournal) AppendRawKVPointCommandTrusted added in v0.6.0 

func (j *CommandJournal) AppendRawKVPointCommandTrusted(baseAppliedLSN uint64, op RawKVOp, key, value []byte) (uint64, error)

AppendRawKVPointCommandTrusted appends a caller-validated public raw KV point Set/Delete command. It preserves the same LSN reservation and rollback semantics as AppendRawKVSingleCommand while avoiding redundant operation validation in the public cached hot path.

func (*CommandJournal) AppendRawKVPointCommandTrustedAndFlush added in v0.6.0 

func (j *CommandJournal) AppendRawKVPointCommandTrustedAndFlush(baseAppliedLSN uint64, op RawKVOp, key, value []byte, sync bool) (uint64, error)

AppendRawKVPointCommandTrustedAndFlush appends a caller-validated public raw KV point command and flushes/syncs the writer while holding the journal lock. When sync is true, any segment rotated before the append is also synced before the new frame is written, preserving durable command-WAL prefix ordering for sync point writes.

func (*CommandJournal) AppendRawKVPointCommandTrustedWithRevisionAndFlush added in v0.6.1 

func (j *CommandJournal) AppendRawKVPointCommandTrustedWithRevisionAndFlush(baseAppliedLSN uint64, op RawKVOp, key, value []byte, revision uint64, sync bool) (uint64, error)

AppendRawKVPointCommandTrustedWithRevisionAndFlush appends a caller-validated public raw KV point command with native entry revision metadata and flushes/syncs the writer while holding the journal lock.

func (*CommandJournal) AppendRawKVSingleCommand added in v0.6.0 

func (j *CommandJournal) AppendRawKVSingleCommand(baseAppliedLSN uint64, op RawKVOperation) (uint64, error)

func (*CommandJournal) AppendRawKVSingleCommandAndFlush added in v0.6.0 

func (j *CommandJournal) AppendRawKVSingleCommandAndFlush(baseAppliedLSN uint64, op RawKVOperation, sync bool) (uint64, error)

AppendRawKVSingleCommandAndFlush appends a one-operation RawKVBatch command and flushes/syncs the writer while holding the journal lock. When sync is true, any segment rotated before the append is also synced before the new frame is written, preserving durable command-WAL prefix ordering for sync point writes.

func (*CommandJournal) Close added in v0.6.0 

func (j *CommandJournal) Close() error

func (*CommandJournal) Flush added in v0.6.0 

func (j *CommandJournal) Flush() error

func (*CommandJournal) NextLSN added in v0.6.0 

func (j *CommandJournal) NextLSN() uint64

func (*CommandJournal) Path added in v0.6.0 

func (j *CommandJournal) Path() string

func (*CommandJournal) RotateActiveSegment added in v0.6.0 

func (j *CommandJournal) RotateActiveSegment(syncCurrent bool) error

RotateActiveSegment rotates the command WAL to the next segment. It is safe to call at checkpoint boundaries; appends are serialized by the journal mutex.

func (*CommandJournal) Sync added in v0.6.0 

func (j *CommandJournal) Sync() error

func (*CommandJournal) WriterBufferStats added in v0.6.0 

func (j *CommandJournal) WriterBufferStats() WriterBufferStats

type CommandJournalOptions added in v0.6.0 

type CommandJournalOptions struct {
	// Lane selects the command WAL lane and must be in [0, MaxCommandJournalLane].
	// Lanes are encoded in decimal segment names, but command WAL is designed
	// around a small configured lane set rather than unbounded dynamic lanes.
	Lane int
	// SegmentSeq selects the segment sequence to append to. Zero means append to
	// the latest existing segment for Lane, or segment 1 when the lane is empty.
	// Explicitly naming the current latest segment appends to its tail. Callers
	// that want rotation must choose the next sequence explicitly.
	// Explicit sequences behind the current lane tail are rejected because they
	// would place newer LSNs before older segments in segment-ordered replay.
	SegmentSeq uint64
	// MaxSegmentSize caps individual command frame payloads; zero uses the
	// commitlog default.
	MaxSegmentSize int64
	// SegmentTargetBytes is the active command-WAL segment file-size target.
	// When >0, appends that would make a non-empty active segment exceed this
	// target rotate to the next lane segment before reserving an LSN. The target
	// is independent from MaxSegmentSize, which remains a per-frame safety cap.
	SegmentTargetBytes int64
	// BufferSize controls this command journal's buffered writer size. Zero
	// uses the commitlog default.
	BufferSize int
	// DeferredCommandBufferSize caps the writer-owned buffer used to finalize
	// trusted public command frames at flush/sync boundaries.
	DeferredCommandBufferSize int
	// DeferredCommandBufferRetainSize bounds retained command buffer capacity
	// after flush. Zero keeps the writer default.
	DeferredCommandBufferRetainSize int
	// Compress enables commitlog frame compression.
	Compress bool
	// OnSegmentRotated is called after a successful active segment rotation with
	// the closed segment bytes, including writer-buffered command frames flushed
	// by the rotation. The callback runs while the journal mutex is held and must
	// not re-enter the journal.
	OnSegmentRotated func(closedBytes int64)
	// InitialLSN is the highest already-applied/durable command LSN. CommandJournal
	// scans existing frames while holding the owner lock and advances reservation
	// to max(InitialLSN, observed frame LSN)+1.
	InitialLSN uint64
}

type CommandKind added in v0.6.0 

type CommandKind uint16

CommandKind identifies the deterministic command payload schema carried by a command WAL frame. 

const (
	CommandKindRawKVBatch CommandKind = 1

	// Collection command frames carry deterministic user-level collection
	// mutations. They do not encode physical root deltas.
	CommandKindCollectionInsertBatchByID    CommandKind = 100
	CommandKindCollectionDeleteBatchByID    CommandKind = 101
	CommandKindCollectionUpdateBatchByID    CommandKind = 102
	CommandKindCollectionRebuildVectorIndex CommandKind = 103
	CommandKindCatalogCreateCollection      CommandKind = 200
	CommandKindCatalogMutationPlaceholder   CommandKind = CommandKindCatalogCreateCollection
)

type CommandScope added in v0.6.0 

type CommandScope uint16

CommandScope identifies which logical TreeDB surface a command mutates. 

const (
	CommandScopeRawKV CommandScope = iota + 1
	CommandScopeCollection
	CommandScopeCatalog
)

type ExternalRef added in v0.6.0 

type ExternalRef struct {
	Class  ExternalRefClass
	Flags  uint16
	FileID uint64
	Offset uint64
	Length uint64
	Digest [32]byte
	Path   []byte
}

type ExternalRefClass added in v0.6.0 

type ExternalRefClass uint16
const (
	ExternalRefValueLog ExternalRefClass = iota + 1
	ExternalRefLeafLog
	ExternalRefPayloadFile
)

type JournalOwner added in v0.6.0 

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

func AcquireJournalOwner added in v0.6.0 

func AcquireJournalOwner(dir string) (*JournalOwner, error)

func AcquireJournalOwnerWithOptions added in v0.6.0 

func AcquireJournalOwnerWithOptions(dir string, opts JournalOwnerOptions) (*JournalOwner, error)

func (*JournalOwner) Close added in v0.6.0 

func (o *JournalOwner) Close() error

type JournalOwnerOptions added in v0.6.0 

type JournalOwnerOptions struct {
	// InitialLSN is the highest durable/applied LSN known by the caller. The
	// first reserved LSN is InitialLSN+1. InitialLSN==MaxUint64 is rejected
	// because there is no next LSN; InitialLSN==MaxUint64-1 is valid and permits
	// reserving the final MaxUint64 LSN exactly once.
	InitialLSN uint64
}

type Options 

type Options struct {
	// MaxSegmentSize bounds the total commitlog segment payload size (bytes).
	// 0 uses the default limit; values < 0 disable the cap.
	MaxSegmentSize int64

	// BufferSize controls the buffered writer size. Values <= 0 use the
	// commitlog default.
	BufferSize int

	// DeferredCommandBufferSize caps the internal command-frame buffer used by
	// trusted public command appends. Values <= 0 disable deferred command-frame
	// finalization.
	DeferredCommandBufferSize int

	// DeferredCommandBufferRetainSize bounds command-frame buffer capacity kept
	// after flush. Values <= 0 retain the full allocated capacity.
	DeferredCommandBufferRetainSize int

	// Compress enables best-effort zstd compression for commitlog segments.
	// Segments are only stored compressed when the compressed payload (plus a
	// small header) is smaller than the raw payload, so compression never causes
	// size amplification. Small segments are left uncompressed to avoid adding
	// hot-path CPU overhead for minimal disk savings.
	Compress bool
}

type PayloadFormat added in v0.6.0 

type PayloadFormat uint16

PayloadFormat identifies the canonical payload encoding inside the envelope. 

const (
	PayloadFormatRawKVBatchV1                   PayloadFormat = 1
	PayloadFormatNativeWireDeterministic        PayloadFormat = 2
	PayloadFormatCollectionInsertBatchByIDV1    PayloadFormat = 3
	PayloadFormatCollectionDeleteBatchByIDV1    PayloadFormat = 4
	PayloadFormatCollectionUpdateBatchByIDV1    PayloadFormat = 5
	PayloadFormatCatalogCreateCollectionV1      PayloadFormat = 6
	PayloadFormatCollectionRebuildVectorIndexV1 PayloadFormat = 7
)

type RawKVBatchOperationScanner added in v0.6.0 

type RawKVBatchOperationScanner func(func(RawKVOperation) error) error

RawKVBatchOperationScanner replays RawKV operations in deterministic command order. Implementations must be replayable: planning and writing scan the same operations separately so large command frames do not need to materialize a canonical payload slice.

type RawKVBatchPayloadBuilder added in v0.6.0 

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

RawKVBatchPayloadBuilder incrementally constructs a canonical RawKVBatch payload while returning stable key/value views into the owned payload bytes.

func NewRawKVBatchPayloadBuilder added in v0.6.0 

func NewRawKVBatchPayloadBuilder(opHint, byteHint int) RawKVBatchPayloadBuilder

NewRawKVBatchPayloadBuilder returns a builder initialized with best-effort capacity hints. Invalid or overflowing hints intentionally fall back to the minimum header capacity; callers that need to observe hint errors should use RawKVBatchPayloadBuilder.ResetWithHint directly.

func (*RawKVBatchPayloadBuilder) Append added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) Append(op RawKVOperation) (keyView, valueView []byte, err error)

func (*RawKVBatchPayloadBuilder) AppendDelete added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) AppendDelete(key []byte) (keyView []byte, err error)

AppendDelete appends a validated RawKV Delete operation without materializing a RawKVOperation wrapper. The key must be non-nil.

func (*RawKVBatchPayloadBuilder) AppendDeleteRange added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) AppendDeleteRange(start, end []byte) (startView []byte, err error)

AppendDeleteRange appends a validated RawKV DeleteRange operation. Nil start or end bounds are encoded as unbounded sentinels and returned as nil views.

func (*RawKVBatchPayloadBuilder) AppendSet added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) AppendSet(key, value []byte) (keyView, valueView []byte, err error)

AppendSet appends a validated RawKV Set operation without materializing a RawKVOperation wrapper. The key and value must be non-nil.

func (*RawKVBatchPayloadBuilder) Count added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) Count() int

func (*RawKVBatchPayloadBuilder) EnableEntryRevisions added in v0.6.1 

func (b *RawKVBatchPayloadBuilder) EnableEntryRevisions() error

EnableEntryRevisions switches the builder to RawKVBatch v4 layout before appending operations, reserving an 8-byte revision slot per operation.

func (*RawKVBatchPayloadBuilder) EntryRevisionsEnabled added in v0.6.1 

func (b *RawKVBatchPayloadBuilder) EntryRevisionsEnabled() bool

EntryRevisionsEnabled reports whether the builder is emitting revision-aware RawKVBatch payloads.

func (*RawKVBatchPayloadBuilder) Len added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) Len() int

func (*RawKVBatchPayloadBuilder) Payload added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) Payload() []byte

func (*RawKVBatchPayloadBuilder) ResetWithHint added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) ResetWithHint(opHint, byteHint int) error

ResetWithHint resets the builder and reserves capacity for the supplied approximate operation and key/value byte counts. Hint errors are advisory: invalid or overflowing hints return ErrRecordTooLarge and fall back to the minimum header capacity so callers may intentionally ignore the error when they can tolerate a small reusable buffer.

func (*RawKVBatchPayloadBuilder) RetainedCap added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) RetainedCap() int

RetainedCap returns the backing capacity retained by the canonical payload.

func (*RawKVBatchPayloadBuilder) RetainedCapAfterAppend added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) RetainedCapAfterAppend(needed int) (int, error)

RetainedCapAfterAppend returns the backing capacity that would be retained after appending needed bytes with the same growth rule used by Append.

func (*RawKVBatchPayloadBuilder) RetainedCapAfterAppendDelete added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) RetainedCapAfterAppendDelete(key []byte) (int, error)

RetainedCapAfterAppendDelete returns the payload-builder backing capacity that AppendDelete would retain.

func (*RawKVBatchPayloadBuilder) RetainedCapAfterAppendDeleteRange added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) RetainedCapAfterAppendDeleteRange(start, end []byte) (int, error)

RetainedCapAfterAppendDeleteRange returns the payload-builder backing capacity that AppendDeleteRange would retain.

func (*RawKVBatchPayloadBuilder) RetainedCapAfterAppendSet added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) RetainedCapAfterAppendSet(key, value []byte) (int, error)

RetainedCapAfterAppendSet returns the payload-builder backing capacity that AppendSet would retain. If the append stays compact-zero, the returned capacity includes the compact-zero payload and zero-value view buffers. If the append must expand compact-zero sets first, it includes that materialization.

func (*RawKVBatchPayloadBuilder) RevisionSlotOffsets added in v0.6.1 

func (b *RawKVBatchPayloadBuilder) RevisionSlotOffsets() []uint32

RevisionSlotOffsets returns byte offsets of revision slots in the canonical payload. The returned slice aliases builder-owned storage and is read-only.

func (*RawKVBatchPayloadBuilder) StampEntryRevisions added in v0.6.1 

func (b *RawKVBatchPayloadBuilder) StampEntryRevisions(scan func(func(uint64) error) error) error

StampEntryRevisions writes revision slots in payload order for builders that were initialized with EnableEntryRevisions.

func (*RawKVBatchPayloadBuilder) Truncate added in v0.6.0 

func (b *RawKVBatchPayloadBuilder) Truncate(payloadLen, count int)

type RawKVBatchPayloadPlan added in v0.6.0 

type RawKVBatchPayloadPlan struct {
	Count          int
	PayloadLen     int
	EntryRevisions bool
}

RawKVBatchPayloadPlan is the exact RawKVBatchV1 payload shape for a replayable operation source.

func PlanRawKVBatchPayloadScan added in v0.6.0 

func PlanRawKVBatchPayloadScan(scan RawKVBatchOperationScanner) (RawKVBatchPayloadPlan, error)

PlanRawKVBatchPayloadScan validates a replayable operation source and returns the exact RawKVBatch payload length needed to encode it.

type RawKVOp added in v0.6.0 

type RawKVOp byte

RawKVOp is a deterministic raw key/value mutation inside a RawKVBatch command payload. The command frame LSN is the batch identity; individual ops intentionally do not carry their own sequence numbers. 

const (
	RawKVOpSet RawKVOp = iota + 1
	RawKVOpDelete
	RawKVOpSetRID
	RawKVOpDeleteRange
)

type RawKVOperation added in v0.6.0 

type RawKVOperation struct {
	Op       RawKVOp
	Key      []byte
	Value    []byte
	RID      uint64
	Revision uint64
}

RawKVOperation represents a single operation in a RawKVBatch command frame.

Field constraints by op type:

  • RawKVOpSet: Key and Value are the raw bytes; RID must be zero.
  • RawKVOpDelete: Key is set; Value must be empty; RID must be zero.
  • RawKVOpSetRID: Key is set; Value MUST be empty (the RID is encoded separately as an 8-byte payload); RID must be non-zero.
  • RawKVOpDeleteRange: Key is the start bound and Value is the exclusive end bound. Nil bounds are unbounded and are encoded with a sentinel length; bounded empty/reversed ranges are invalid in command frames.

Revision is optional per-entry metadata. Zero is the legacy/no-revision value. Revision is valid on point Set/Delete/SetRID operations; range deletes do not carry per-item revision metadata.

func DecodeRawKVBatchPayload added in v0.6.0 

func DecodeRawKVBatchPayload(payload []byte) ([]RawKVOperation, error)

type Reader 

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

func NewReader 

func NewReader(path string) (*Reader, error)

func NewReaderWithOptions 

func NewReaderWithOptions(path string, opts Options) (*Reader, error)

func (*Reader) Close 

func (r *Reader) Close() error

func (*Reader) ReadBatch 

func (r *Reader) ReadBatch() ([]Record, error)

ReadBatch reads the next batch segment.

func (*Reader) ReadCommandFrame added in v0.6.0 

func (r *Reader) ReadCommandFrame() (CommandEnvelope, error)

type Record 

type Record struct {
	Op       byte
	Key      []byte
	Value    []byte
	RID      uint64
	Seq      uint64
	Revision uint64
}

type Writer 

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

func NewWriter 

func NewWriter(path string) (*Writer, error)

func NewWriterWithOptions 

func NewWriterWithOptions(path string, opts Options) (*Writer, error)

func (*Writer) ActiveBytes added in v0.6.0 

func (w *Writer) ActiveBytes() int64

func (*Writer) Append 

func (w *Writer) Append(record Record) error

func (*Writer) AppendBatch 

func (w *Writer) AppendBatch(records []Record) error

func (*Writer) AppendCommand added in v0.6.0 

func (w *Writer) AppendCommand(env CommandEnvelope) error

func (*Writer) AppendCommandPayloadDirectTrusted added in v0.6.0 

func (w *Writer) AppendCommandPayloadDirectTrusted(lsn, baseAppliedLSN uint64, kind CommandKind, scope CommandScope, format PayloadFormat, payload []byte) error

AppendCommandPayloadDirectTrusted appends a canonical command payload whose bytes were constructed by the matching payload encoder.

func (*Writer) AppendRawKVBatchPayloadCommandDirect added in v0.6.0 

func (w *Writer) AppendRawKVBatchPayloadCommandDirect(lsn, baseAppliedLSN uint64, payload []byte) error

func (*Writer) AppendRawKVBatchPayloadCommandDirectTrusted added in v0.6.0 

func (w *Writer) AppendRawKVBatchPayloadCommandDirectTrusted(lsn, baseAppliedLSN uint64, payload []byte) error

AppendRawKVBatchPayloadCommandDirectTrusted appends a canonical RawKVBatch payload that the caller has already validated or constructed through the RawKVBatchPayloadBuilder.

func (*Writer) AppendRawKVBatchPayloadScanCommandDirectTrusted added in v0.6.0 

func (w *Writer) AppendRawKVBatchPayloadScanCommandDirectTrusted(lsn, baseAppliedLSN uint64, plan RawKVBatchPayloadPlan, scan RawKVBatchOperationScanner) error

AppendRawKVBatchPayloadScanCommandDirectTrusted appends a RawKVBatch command from a replayable operation scanner without materializing the canonical payload slice first.

func (*Writer) AppendRawKVPointCommandDirectTrusted added in v0.6.0 

func (w *Writer) AppendRawKVPointCommandDirectTrusted(lsn, baseAppliedLSN uint64, op RawKVOp, key, value []byte) error

AppendRawKVPointCommandDirectTrusted appends a public point Set/Delete command whose key/value have already passed the public cached preflight.

func (*Writer) AppendRawKVSingleCommandDirect added in v0.6.0 

func (w *Writer) AppendRawKVSingleCommandDirect(lsn, baseAppliedLSN uint64, op RawKVOperation) error

func (*Writer) AppendZeroInlineBatchFunc added in v0.6.0 

func (w *Writer) AppendZeroInlineBatchFunc(count int, seq uint64, valueLen int, keyAt func(int) []byte) error

func (*Writer) BufferStats added in v0.6.0 

func (w *Writer) BufferStats() WriterBufferStats

func (*Writer) Close 

func (w *Writer) Close() error

func (*Writer) Flush 

func (w *Writer) Flush() error

func (*Writer) RotateTo 

func (w *Writer) RotateTo(path string) error

RotateTo flushes and closes the current file, then opens (or creates) the provided path and reuses the writer's buffers for future appends.

func (*Writer) RotateToWithSync added in v0.6.0 

func (w *Writer) RotateToWithSync(path string, syncCurrent bool) error

RotateToWithSync flushes and closes the current file, then opens (or creates) the provided path and reuses the writer's buffers for future appends. When syncCurrent is false, the current file is flushed to the OS but not fsynced.

func (*Writer) Size 

func (w *Writer) Size() int64

func (*Writer) Sync 

func (w *Writer) Sync() error

type WriterBufferStats added in v0.6.0 

type WriterBufferStats struct {
	BufferedWriterSize          int
	BufferedWriterBufferedBytes int
	ScratchCapacity             int
	CommandBufferLength         int
	CommandBufferCapacity       int
	CommandBufferLimit          int
	CommandBufferRetainLimit    int
	CommandBufferTrimCount      uint64
	CommandBufferDroppedBytes   uint64
	PendingBatchLength          int
	PendingBatchCapacity        int
}

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.