raftentry

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: 8 Imported by: 0

Documentation

Overview

Package raftentry defines the R3a v1 deterministic command-entry contract.

R3a v1 does not introduce a second semantic command encoding. CommandEntryV1 bytes are the existing native-wire deterministic entry bytes. This package adds the Raft-apply contract around those bytes: digest domain separation, target/scope identity, command classification, idempotency requirements, and deterministic result vocabulary.

Fixture stability is checked with: 

GOWORK=off go test ./TreeDB/internal/raftentry ./TreeDB/internal/nativewire ./TreeDB/docs

Index

Constants

View Source 
const (
	EntryVersionV1 = uint64(1)

	// ScopeRuleSingleGroupV1 is a schema-versioned single-group rule. It is
	// covered by CommandDigestV1 even though it is not re-encoded inside the
	// native-wire deterministic entry bytes.
	ScopeRuleSingleGroupV1 ScopeRuleV1 = "single-group-v1"

	DatabaseScopeDefaultV1 = "database/default"
	CatalogScopeDefaultV1  = "catalog/default"

	NoIdempotencyTokenV1 = "NoIdempotencyV1"

	MaxIdempotencyKeyBytesV1 = 1024
	MaxResultRecordBytesV1   = 64 << 10
	MaxProgressRecordsV1     = 1 << 20
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ApplyEntryID 

type ApplyEntryID struct {
	Term  uint64
	Index uint64
}

type ApplyResultV1 

type ApplyResultV1 struct {
	Status                 ApplyStatusV1
	CommandDigest          CommandDigestV1
	DeterministicErrorCode DeterministicErrorCodeV1
	AffectedCount          int64
	MatchedCount           int64
	ResultDigest           CommandDigestV1
}

type ApplyStatusV1 

type ApplyStatusV1 string
const (
	ApplyStatusApplied                   ApplyStatusV1 = "applied"
	ApplyStatusAlreadyApplied            ApplyStatusV1 = "already-applied"
	ApplyStatusDeterministicGuardFailure ApplyStatusV1 = "deterministic-guard-failure"
	ApplyStatusRejectedUnsupported       ApplyStatusV1 = "rejected-unsupported"
	ApplyStatusRejectedMalformed         ApplyStatusV1 = "rejected-malformed"
	ApplyStatusRejectedConflict          ApplyStatusV1 = "rejected-conflict"
	ApplyStatusRecoveryRequired          ApplyStatusV1 = "recovery-required"
)

type CommandDigestV1 

type CommandDigestV1 [32]byte

func CommandDigestV1ForBytes 

func CommandDigestV1ForBytes(src []byte, opts DecodeOptions) CommandDigestV1

func ValidateCommandDigestInputV1 

func ValidateCommandDigestInputV1(src []byte, opts DecodeOptions) (CommandDigestV1, error)

func (CommandDigestV1) Hex 

func (d CommandDigestV1) Hex() string

type CommandEntryV1 

type CommandEntryV1 struct {
	Bytes          []byte
	Decoded        nativewire.DeterministicEntry
	Digest         CommandDigestV1
	Target         TargetIdentityV1
	IdempotencyKey []byte
	Idempotency    IdempotencyModeV1
	Row            CommandRowV1
}

func DecodeCommandEntryV1 

func DecodeCommandEntryV1(src []byte, opts DecodeOptions) (CommandEntryV1, error)

type CommandRowV1 

type CommandRowV1 struct {
	Known                   bool
	CommandID               nativewire.CommandID
	NativeWireCommand       string
	CommandName             string
	Decision                DecisionV1
	DuplicateMode           DuplicateModeV1
	ResultReplayMode        ResultReplayModeV1
	CommandWALStatus        string
	CommandWALKind          string
	DeterministicEntryBytes string
	Reason                  string
}

func AllCommandRowsV1 

func AllCommandRowsV1() []CommandRowV1

func ClassifyNativeWireCommandV1 

func ClassifyNativeWireCommandV1(id nativewire.CommandID) CommandRowV1

type DecisionV1 

type DecisionV1 string
const (
	DecisionAccepted DecisionV1 = "accepted"
	DecisionRejected DecisionV1 = "rejected"
)

type DecodeOptions 

type DecodeOptions struct {
	Limits          nativewire.Limits
	ScopeRule       ScopeRuleV1
	DatabaseScope   string
	CatalogScope    string
	ApplyEntryID    ApplyEntryID
	RequestMetadata RequestMetadataV1
	ExpectedTarget  *TargetIdentityV1
}

type DeterministicErrorCodeV1 

type DeterministicErrorCodeV1 string
const (
	ErrorNoneV1                 DeterministicErrorCodeV1 = ""
	ErrorUnsupportedCommandV1   DeterministicErrorCodeV1 = "unsupported-command"
	ErrorMalformedEntryV1       DeterministicErrorCodeV1 = "malformed-entry"
	ErrorUnsupportedVersionV1   DeterministicErrorCodeV1 = "unsupported-version"
	ErrorUnsupportedFeatureV1   DeterministicErrorCodeV1 = "unsupported-feature"
	ErrorMissingGuardV1         DeterministicErrorCodeV1 = "missing-guard"
	ErrorTargetMismatchV1       DeterministicErrorCodeV1 = "target-mismatch"
	ErrorRejectedConflictV1     DeterministicErrorCodeV1 = "rejected-conflict"
	ErrorReadOnlyV1             DeterministicErrorCodeV1 = "read-only"
	ErrorUnsafeDurabilityModeV1 DeterministicErrorCodeV1 = "unsafe-durability-mode"
	ErrorResourceExhaustedV1    DeterministicErrorCodeV1 = "resource-exhausted"
	ErrorNoIdempotencyV1        DeterministicErrorCodeV1 = "no-idempotency"
	ErrorResultReplayRequiredV1 DeterministicErrorCodeV1 = "result-replay-required"
	ErrorUnknownRequiredFieldV1 DeterministicErrorCodeV1 = "unknown-required-field"
	ErrorUnsupportedScopeRuleV1 DeterministicErrorCodeV1 = "unsupported-scope-rule"
)

func ErrorCodeOf 

func ErrorCodeOf(err error) (DeterministicErrorCodeV1, bool)

type DuplicateModeV1 

type DuplicateModeV1 string
const (
	DuplicateReplayRequiredV1      DuplicateModeV1 = "replay-required"
	DuplicateFailClosedAllowedV1   DuplicateModeV1 = "duplicate-fail-closed-allowed"
	DuplicateRejectedUnsupportedV1 DuplicateModeV1 = "rejected"
)

type IdempotencyModeV1 

type IdempotencyModeV1 string
const (
	IdempotencyRequiredV1 IdempotencyModeV1 = "required-idempotency-key-v1"
	NoIdempotencyV1       IdempotencyModeV1 = "no-idempotency-v1"
)

type RequestMetadataV1 

type RequestMetadataV1 struct {
	RequestID         uint64
	AckPolicy         nativewire.AckPolicy
	DeadlineUnixNanos int64
	TraceContext      []byte
	Compression       string
	OmitResultIDs     bool
	OmitResponseMeta  bool

	// ClusterRoute* fields are request-only metadata for cluster submitters.
	// They are intentionally excluded from deterministic command entry bytes,
	// but submit admission may still treat them as binding local-route guards.
	ClusterRouteKnown         bool
	ClusterRouteDatabase      string
	ClusterRouteCatalog       string
	ClusterRouteCollection    string
	ClusterRouteShape         string
	ClusterRouteGroupID       string
	ClusterRouteMembers       []string
	ClusterRouteLeaderHint    string
	ClusterRoutePlacementMode string
	ClusterRouteTokenKnown    bool
	ClusterRouteToken         uint64
	ClusterRoutePartitionID   string
}

type ResultReplayModeV1 

type ResultReplayModeV1 string
const (
	ResultReplayPersistedPayloadOrDigestV1 ResultReplayModeV1 = "persisted-result-payload-or-digest"
	ResultReplayFailClosedV1               ResultReplayModeV1 = "fail-closed-until-result-store"
	ResultReplayNoneRejectedV1             ResultReplayModeV1 = "none-rejected"
)

type ScopeRuleV1 

type ScopeRuleV1 string

type TargetIdentityV1 

type TargetIdentityV1 struct {
	ScopeRule              ScopeRuleV1
	DatabaseScope          string
	CatalogScope           string
	CommandID              nativewire.CommandID
	CommandVersion         uint64
	CollectionRef          []byte
	CollectionMeta         []byte
	ExpectedCatalogVersion []byte
}

func (TargetIdentityV1) Clone 

func (t TargetIdentityV1) Clone() TargetIdentityV1

func (TargetIdentityV1) Equal 

func (t TargetIdentityV1) Equal(u TargetIdentityV1) bool

type ValidationError 

type ValidationError struct {
	Code DeterministicErrorCodeV1
	Err  error
}

func (*ValidationError) Error 

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap 

func (e *ValidationError) Unwrap() error

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.