Documentation
¶
Overview ¶
Package b5coordinator implements the feature-off B5 planned transaction coordinator. It deliberately has no MCP, HTTP, feature-flag, credential or raw database dependency. The only executable object it can receive is the narrow, transaction-bound Capability below.
Index ¶
- Constants
- Variables
- func ErrorCode(err error) b5.ErrorCode
- type Analysis
- type Analyzer
- type ApprovalConsumeRequest
- type ApprovalLease
- type ApprovalStore
- type AuditEvent
- type AuditKind
- type AuditResult
- type Auditor
- type BackendIdentity
- type BeginCapability
- type BeginRequest
- type Capability
- type Clock
- type Config
- type Coordinator
- func (coordinator *Coordinator) Begin(ctx context.Context, request BeginRequest, analyzer Analyzer) (Result, error)
- func (coordinator *Coordinator) Commit(ctx context.Context, request FinishRequest) (Result, error)
- func (coordinator *Coordinator) Execute(ctx context.Context, request ExecuteRequest) (Result, error)
- func (coordinator *Coordinator) Expire(ctx context.Context, limit int) (int, error)
- func (coordinator *Coordinator) FinalFence(ctx context.Context, transactionID string) error
- func (coordinator *Coordinator) Recover(ctx context.Context, transactionID string) (Result, error)
- func (coordinator *Coordinator) Rollback(ctx context.Context, request FinishRequest) (Result, error)
- func (coordinator *Coordinator) Shutdown(ctx context.Context) error
- func (coordinator *Coordinator) Status(ctx context.Context, session SessionAuthorization, transactionID string) (Result, error)
- func (coordinator *Coordinator) String() string
- type Decision
- type DirectorySessionGate
- type Engine
- type ExecuteRequest
- type Failure
- type FinishRequest
- type MemoryApproval
- type MemoryApprovalStore
- func (memory *MemoryApprovalStore) Consume(_ context.Context, request ApprovalConsumeRequest) (ApprovalLease, error)
- func (memory *MemoryApprovalStore) Get(id string) (MemoryApproval, bool)
- func (memory *MemoryApprovalStore) MarkActive(_ context.Context, lease ApprovalLease, transactionID string) error
- func (memory *MemoryApprovalStore) MarkBeginFailed(_ context.Context, lease ApprovalLease, transactionID string) error
- func (memory *MemoryApprovalStore) Put(value MemoryApproval)
- type MemoryAuditor
- type MemoryTransactionStore
- func (memory *MemoryTransactionStore) CASProgress(_ context.Context, id string, revision int64, status b5.TransactionStatus, ...) (store.B5Transaction, error)
- func (memory *MemoryTransactionStore) CASState(_ context.Context, id string, revision int64, fromStatus b5.TransactionStatus, ...) (store.B5Transaction, error)
- func (memory *MemoryTransactionStore) Create(_ context.Context, value store.B5Transaction) (store.B5Transaction, error)
- func (memory *MemoryTransactionStore) Get(_ context.Context, id string) (store.B5Transaction, error)
- func (memory *MemoryTransactionStore) ListExpired(_ context.Context, now time.Time, limit int) ([]store.B5Transaction, error)
- type OperationEvidence
- type Plan
- type PlanAnalyzerResolver
- type PlanRequest
- type PlannedStatement
- type ResourceLimits
- type Result
- type SessionAuthorization
- type SessionFailure
- type SessionGate
- type StatementRequest
- type StatementResult
- type StaticSessionGate
- type TerminalResult
- type TransactionStore
- type WALAuditor
Constants ¶
const ( PlanSchemaID = "agentsql.b5.plan.v4" PlanSchemaVersion = uint16(4) BeginAuthSchemaID = "agentsql.b5.begin-auth.v3" RequiredBinderABI = b5dml.BinderABI )
Variables ¶
var ( ErrInvalidPlan = errors.New("b5coordinator: invalid transaction plan") ErrPlanDenied = errors.New("b5coordinator: plan denied") ErrApprovalRequired = errors.New("b5coordinator: approval required") ErrApprovalInvalid = errors.New("b5coordinator: approval invalid") ErrWrongOwner = errors.New("b5coordinator: wrong owner or epoch") ErrBusy = errors.New("b5coordinator: operation already active") ErrWrongOrdinal = errors.New("b5coordinator: operation is not next in plan") ErrRollbackOnly = errors.New("b5coordinator: transaction is rollback-only") ErrTerminal = errors.New("b5coordinator: transaction is terminal") ErrCapabilityUnknown = errors.New("b5coordinator: capability result is uncertain") )
Functions ¶
Types ¶
type Analysis ¶
type Analysis struct {
Facts b5dml.StatementFacts
TreeDigest [32]byte
ManifestDigest [32]byte
ClosureDigest [32]byte
Decision Decision
EstimatedRows int64
EstimatedWork uint64
Artifact any
}
Analysis is immutable candidate-phase evidence. Artifact may contain the binder enrollment used for same-transaction comparison, but it must not be serializable or executable and is never included in a digest.
type ApprovalConsumeRequest ¶
type ApprovalLease ¶
type ApprovalStore ¶
type ApprovalStore interface {
Consume(context.Context, ApprovalConsumeRequest) (ApprovalLease, error)
MarkBeginFailed(context.Context, ApprovalLease, string) error
MarkActive(context.Context, ApprovalLease, string) error
}
type AuditEvent ¶
type AuditResult ¶
type AuditResult struct {
Durability b5.AuditDurability
EventDigest [32]byte
}
type Auditor ¶
type Auditor interface {
Barrier(context.Context, AuditEvent) (AuditResult, error)
}
type BackendIdentity ¶
type BeginCapability ¶
type BeginCapability interface {
BeginNative(context.Context) (b5dml.BeginAttemptEvidence, error)
FixContext(context.Context, time.Time) error
BindAndSeal(context.Context, Plan) ([32]byte, error)
Activate() (Capability, error)
CleanupBegin(context.Context, *b5terminal.TerminalOwner, b5dml.BeginCleanupDecision) (TerminalResult, error)
}
type BeginRequest ¶
type BeginRequest struct {
Session SessionAuthorization
TransactionID, RequestID, ApprovalID string
Plan PlanRequest
}
type Capability ¶
type Capability interface {
Execute(context.Context, PlannedStatement) (StatementResult, error)
Cancel(context.Context) (b5terminal.CancelEmission, error)
FinishCommit(context.Context, *b5terminal.TerminalOwner, b5terminal.TerminalAttempt) (TerminalResult, error)
FinishRollback(context.Context, *b5terminal.TerminalOwner, b5terminal.TerminalAttempt, b5terminal.NoCommitEverSent) (TerminalResult, error)
Discard(context.Context) (b5.ConnectionDisposition, error)
}
Capability is transaction-bound and accepts only a statement already sealed into the plan. It intentionally has no method taking arbitrary SQL.
type Config ¶
type Config struct {
Transactions TransactionStore
Approvals ApprovalStore
Sessions SessionGate
Engine Engine
Audit Auditor
Clock Clock
}
type Coordinator ¶
type Coordinator struct {
// contains filtered or unexported fields
}
func New ¶
func New(config Config) (*Coordinator, error)
func (*Coordinator) Begin ¶
func (coordinator *Coordinator) Begin(ctx context.Context, request BeginRequest, analyzer Analyzer) (Result, error)
func (*Coordinator) Commit ¶
func (coordinator *Coordinator) Commit(ctx context.Context, request FinishRequest) (Result, error)
func (*Coordinator) Execute ¶
func (coordinator *Coordinator) Execute(ctx context.Context, request ExecuteRequest) (Result, error)
func (*Coordinator) Expire ¶
Expire performs the durable deadline scan used by an owner watchdog. It never touches a row owned by another epoch because only locally-held live capabilities can be terminated; other rows remain for the owner-crash reaper/reconciliation path.
func (*Coordinator) FinalFence ¶
func (coordinator *Coordinator) FinalFence(ctx context.Context, transactionID string) error
FinalFence durably marks that all post-terminal control-plane work for a transaction completed. It is deliberately callable only after the business connection has reached a terminal disposition.
func (*Coordinator) Rollback ¶
func (coordinator *Coordinator) Rollback(ctx context.Context, request FinishRequest) (Result, error)
func (*Coordinator) Shutdown ¶
func (coordinator *Coordinator) Shutdown(ctx context.Context) error
Shutdown stops admission at the protocol owner, freezes every locally-held capability, and gives each transaction the same typed rollback/cancel-taint lifecycle used by the watchdog. It never reconstructs or touches a foreign owner capability.
func (*Coordinator) Status ¶
func (coordinator *Coordinator) Status(ctx context.Context, session SessionAuthorization, transactionID string) (Result, error)
func (*Coordinator) String ¶
func (coordinator *Coordinator) String() string
type DirectorySessionGate ¶
DirectorySessionGate preserves b5session's proof/owner/sticky-route rules. It performs Lookup, never Touch: invalid, stale and wrong-instance requests therefore cannot extend a victim transaction or acquire cleanup authority.
func (DirectorySessionGate) Validate ¶
func (gate DirectorySessionGate) Validate(ctx context.Context, authorization SessionAuthorization) error
type Engine ¶
type Engine interface {
Pin(context.Context, Plan, *b5dml.BeginMachine) (BeginCapability, BackendIdentity, error)
}
type ExecuteRequest ¶
type ExecuteRequest struct {
Session SessionAuthorization
TransactionID, RequestID, OperationID string
Ordinal int
}
type FinishRequest ¶
type FinishRequest struct {
Session SessionAuthorization
TransactionID, RequestID string
}
type MemoryApproval ¶
type MemoryApprovalStore ¶
type MemoryApprovalStore struct {
// contains filtered or unexported fields
}
func NewMemoryApprovalStore ¶
func NewMemoryApprovalStore() *MemoryApprovalStore
func (*MemoryApprovalStore) Consume ¶
func (memory *MemoryApprovalStore) Consume(_ context.Context, request ApprovalConsumeRequest) (ApprovalLease, error)
func (*MemoryApprovalStore) Get ¶
func (memory *MemoryApprovalStore) Get(id string) (MemoryApproval, bool)
func (*MemoryApprovalStore) MarkActive ¶
func (memory *MemoryApprovalStore) MarkActive(_ context.Context, lease ApprovalLease, transactionID string) error
func (*MemoryApprovalStore) MarkBeginFailed ¶
func (memory *MemoryApprovalStore) MarkBeginFailed(_ context.Context, lease ApprovalLease, transactionID string) error
func (*MemoryApprovalStore) Put ¶
func (memory *MemoryApprovalStore) Put(value MemoryApproval)
type MemoryAuditor ¶
type MemoryAuditor struct {
Events []AuditEvent
Fail func(AuditEvent) error
Durability func(AuditEvent) b5.AuditDurability
// contains filtered or unexported fields
}
func (*MemoryAuditor) Barrier ¶
func (audit *MemoryAuditor) Barrier(_ context.Context, event AuditEvent) (AuditResult, error)
type MemoryTransactionStore ¶
type MemoryTransactionStore struct {
// contains filtered or unexported fields
}
MemoryTransactionStore is a deterministic implementation of the exact durable-store contract. It is intended for coordinator model/fault tests; production construction uses store.B5TransactionRepository.
func NewMemoryTransactionStore ¶
func NewMemoryTransactionStore() *MemoryTransactionStore
func (*MemoryTransactionStore) CASProgress ¶
func (memory *MemoryTransactionStore) CASProgress(_ context.Context, id string, revision int64, status b5.TransactionStatus, phase b5.TransactionPhase, update store.B5TransactionProgress) (store.B5Transaction, error)
func (*MemoryTransactionStore) CASState ¶
func (memory *MemoryTransactionStore) CASState(_ context.Context, id string, revision int64, fromStatus b5.TransactionStatus, fromPhase b5.TransactionPhase, toStatus b5.TransactionStatus, toPhase b5.TransactionPhase) (store.B5Transaction, error)
func (*MemoryTransactionStore) Create ¶
func (memory *MemoryTransactionStore) Create(_ context.Context, value store.B5Transaction) (store.B5Transaction, error)
func (*MemoryTransactionStore) Get ¶
func (memory *MemoryTransactionStore) Get(_ context.Context, id string) (store.B5Transaction, error)
func (*MemoryTransactionStore) ListExpired ¶
func (memory *MemoryTransactionStore) ListExpired(_ context.Context, now time.Time, limit int) ([]store.B5Transaction, error)
type OperationEvidence ¶
type Plan ¶
type Plan struct {
SchemaID, TenantID, PrincipalID, AgentID, DatasourceID string
SchemaVersion uint16
KeyRevision, DatasourceRevision, PolicyRevision uint64
Dialect string
ServerMajor int
Isolation, BinderABI, ClosurePolicy string
Limits ResourceLimits
Statements []PlannedStatement
Digest [32]byte
RequiresApproval bool
}
type PlanAnalyzerResolver ¶
type PlanAnalyzerResolver interface {
AnalyzerFor(context.Context, PlanRequest) (Analyzer, error)
}
PlanAnalyzerResolver selects an analyzer from server-owned datasource and principal state. It is evaluated before any statement analysis and prevents a multi-datasource production runtime from trusting client dialect metadata.
type PlanRequest ¶
type PlanRequest struct {
TenantID, PrincipalID, AgentID, DatasourceID string
KeyRevision, DatasourceRevision, PolicyRevision uint64
Dialect string
ServerMajor int
Isolation, BinderABI, ClosurePolicy string
Statements []StatementRequest
Limits ResourceLimits
}
type PlannedStatement ¶
type PlannedStatement struct {
Ordinal int
OperationID string
SQL string
RawSQLDigest [32]byte
ReasonDigest [32]byte
TreeDigest [32]byte
ManifestDigest [32]byte
ClosureDigest [32]byte
Action b5.DMLAction
Writes []b5dml.WriteTarget
References []b5dml.Reference
Decision Decision
EstimatedRows int64
EstimatedWork uint64
// contains filtered or unexported fields
}
func (PlannedStatement) Artifact ¶
func (statement PlannedStatement) Artifact() any
type ResourceLimits ¶
type ResourceLimits struct {
MaxStatements int
MaxSQLBytes int
MaxPlanBytes int
MaxAffectedRows int64
MaxEstimatedWork uint64
IdleTimeout time.Duration
WallTimeout time.Duration
StatementTimeout time.Duration
OperationWatchdog time.Duration
QuiesceGrace time.Duration
}
func DefaultResourceLimits ¶
func DefaultResourceLimits() ResourceLimits
type Result ¶
type Result struct {
TransactionID string `json:"transaction_id"`
Status b5.TransactionStatus `json:"status"`
Phase b5.TransactionPhase `json:"phase"`
Code b5.ErrorCode `json:"error_code,omitempty"`
Effect b5.TxEffect `json:"tx_effect"`
DBOutcome b5.DBOutcome `json:"db_outcome,omitempty"`
AuditDurability b5.AuditDurability `json:"audit_durability,omitempty"`
ConnectionDisposition b5.ConnectionDisposition `json:"connection_disposition,omitempty"`
NextOrdinal int `json:"next_ordinal"`
AffectedRows int64 `json:"affected_rows"`
Evidence []OperationEvidence `json:"evidence,omitempty"`
}
type SessionAuthorization ¶
type SessionFailure ¶
func (*SessionFailure) Error ¶
func (failure *SessionFailure) Error() string
type SessionGate ¶
type SessionGate interface {
Validate(context.Context, SessionAuthorization) error
}
type StatementRequest ¶
type StatementResult ¶
type StaticSessionGate ¶
func (StaticSessionGate) Validate ¶
func (gate StaticSessionGate) Validate(_ context.Context, session SessionAuthorization) error
type TerminalResult ¶
type TerminalResult struct {
Resolution b5terminal.TerminalResolution
EvidenceDigest [32]byte
DispositionProofDigest [32]byte
CancelEmission b5terminal.CancelEmission
}
type TransactionStore ¶
type TransactionStore interface {
store.B5TransactionStore
}
type WALAuditor ¶
WALAuditor adapts the S7b primary/WAL/receipt service to coordinator barriers. Pre-effect tx_begin is primary-only and fails closed. Post-effect facts use Service so a primary outage is represented by an immutable WAL append receipt and the returned durability axis.
func NewWALAuditor ¶
func NewWALAuditor(service *b5wal.Service) (*WALAuditor, error)
func (*WALAuditor) Barrier ¶
func (audit *WALAuditor) Barrier(ctx context.Context, event AuditEvent) (AuditResult, error)