b5terminal

type CancelDiagnostics ¶

type CancelDiagnostics struct {
	ReadyForQueryIdleObserved bool
	ExecuteExited             bool
	CancelSocketClosed        bool
	StatementTimeoutObserved  bool
}

type CancelEmission ¶

type CancelEmission uint8

const (
	CancelNotSentProven CancelEmission = iota
	CancelSendStartedOrIndeterminate
	CancelFullPacketWritten
)

type CancelGuard ¶

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

CancelGuard serializes the independent cancel send path with any attempt to start a new main-connection command. Standard PostgreSQL has no generation- bound cancel fence, so taint is monotonic and permanent.

func NewCancelGuard() *CancelGuard

func (guard *CancelGuard) Disposition(backendAbsenceConfirmed bool) ConnectionDisposition

func (guard *CancelGuard) ObserveCancelSocketClosed()

func (guard *CancelGuard) ObserveEmission(emission CancelEmission)

func (guard *CancelGuard) ObserveExecuteExit()

func (guard *CancelGuard) ObserveReadyForQueryIdle()

func (guard *CancelGuard) ObserveStatementTimeout()

func (guard *CancelGuard) RecordMainSend(command MainCommand) error

func (guard *CancelGuard) Snapshot() CancelSnapshot

type CancelSnapshot ¶

type CancelSnapshot struct {
	Emission    CancelEmission
	Tainted     bool
	Diagnostics CancelDiagnostics
	Sent        map[MainCommand]uint64
}

type CommitStage ¶

type CommitStage uint8

const (
	CommitStageBeforeSend CommitStage = iota
	CommitStagePartialWrite
	CommitStageFullWriteAwaitingACK
	CommitStageACKObservedAwaitingRFQ
)

type ConnectionDisposition ¶

type ConnectionDisposition = b5.ConnectionDisposition

type ConsistencyReason ¶

type ConsistencyReason uint8

const (
	ReasonNone ConsistencyReason = iota
	ReasonUnknownSchema
	ReasonInvalidWriteAccounting
	ReasonInsufficientCorrelation
	ReasonUntypedReply
	ReasonServerStatusInsufficient
	ReasonWrongOperation
	ReasonStaleOrFutureGeneration
	ReasonDuplicateTerminalReply
	ReasonPositiveAndRejection
	ReasonDuplicateOrChangingRFQ
	ReasonReplyStatusContradiction
	ReasonExplicitLocalWriteContradiction
	ReasonInvalidStrongCorrelation
)

type ConsistencyResult ¶

type ConsistencyResult struct {
	Verdict ConsistencyVerdict
	Reason  ConsistencyReason
}

func CheckEvidence(e Evidence) ConsistencyResult

type ConsistencyVerdict ¶

type ConsistencyVerdict = b5.EvidenceConsistency

type CorrelationProof ¶

type CorrelationProof struct {
	Strength                CorrelationStrength
	CleanCommandBoundary    bool
	UniqueSocketOwner       bool
	DecoderAfterSendPermit  bool
	NoUnreadOrPendingAtSend bool
	MonotonicTranscript     bool
	TranscriptDigest        [32]byte
}

CorrelationProof records the minimum facts needed to call a PostgreSQL reply current. PostgreSQL does not put a request ID in these replies, so a strong claim is valid only from an exclusive decoder at a clean boundary.

type CorrelationStrength ¶

type CorrelationStrength = b5.ReplyCorrelation

type DBOutcome ¶

type DBOutcome = b5.DBOutcome

type Evidence ¶

type Evidence struct {
	Schema                string
	SchemaVersion         uint16
	Operation             TerminalOperation
	TransactionGeneration uint64
	AttemptGeneration     uint64
	OwnerGeneration       uint64
	Write                 WriteEvidence
	Replies               []TerminalReply
	ServerStatuses        []ServerTxStatus
}

Evidence is the immutable input to CheckEvidence and ResolveTerminal.

type FaultEvent ¶

type FaultEvent struct {
	Kind     FaultEventKind
	Command  MainCommand
	At       uint64
	Sequence uint64
}

type FaultEventKind ¶

type FaultEventKind uint8

const (
	FaultEventCancelPacket FaultEventKind = iota
	FaultEventMainCommand
	FaultEventExecuteSuccess
	FaultEventReadyForQueryIdle
	FaultEventCancelSocketClosed
	FaultEventStatementTimeout
)

type FaultProxy ¶

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

FaultProxy is a deterministic, in-memory two-path proxy. Delay controls when the server observes an event; CancelGuard is updated when the client send starts, which models the dangerous interval before a delayed cancel arrives.

func NewFaultProxy(guard *CancelGuard) *FaultProxy

func (proxy *FaultProxy) AdvanceTo(at uint64) []FaultEvent

func (proxy *FaultProxy) Delivered() []FaultEvent

func (proxy *FaultProxy) Pending() []FaultEvent

func (proxy *FaultProxy) ScheduleServerEvent(kind FaultEventKind, delay uint64)

func (proxy *FaultProxy) SendCancel(emission CancelEmission, delay uint64)

func (proxy *FaultProxy) SendMain(command MainCommand, delay uint64) error

type MainCommand ¶

type MainCommand uint8

const (
	CommandRollback MainCommand = iota
	CommandCommit
	CommandReset
	CommandHealthProbe
	CommandStatement
)

type NoCommitEverSent ¶

type NoCommitEverSent struct {
	Schema                     string
	SchemaVersion              uint16
	TransactionGeneration      uint64
	OwnerGeneration            uint64
	HistoryContinuous          bool
	UniqueSocketOwner          bool
	CommitSendPermitEverOpened bool
}

NoCommitEverSent is independent coordinator evidence. Connector evidence may not manufacture it, particularly when that connector is contradictory.

func (proof NoCommitEverSent) ValidFor(e Evidence) bool

type OwnerState ¶

type OwnerState uint8

const (
	OwnerActive OwnerState = iota
	OwnerQuiescing
	OwnerCommitting
	OwnerRollingBack
	OwnerTerminal
)

type PGAdapterOptions ¶

type PGAdapterOptions struct {
	WatchdogTimeout time.Duration
	ReconcileBudget time.Duration
	ResetSQL        string
	HealthSQL       string
}

type PGBackendIdentity ¶

type PGBackendIdentity struct {
	ServerIdentity  string
	Database        string
	PID             uint32
	BackendStart    time.Time
	ConnectionNonce string
}

PGBackendIdentity is the identity passed to independent backend inventory. PID alone is intentionally insufficient because PostgreSQL can reuse it.

type PGPhysicalConnection ¶

type PGPhysicalConnection struct {
	Conn                     net.Conn
	Identity                 PGBackendIdentity
	CleanCommandBoundary     bool
	UniqueSocketOwner        bool
	TransferToPool           func(context.Context, net.Conn, PGBackendIdentity) error
	ConfirmBackendAbsence    func(context.Context, PGBackendIdentity) (bool, error)
	OnLocalConnectionDiscard func(PGBackendIdentity, error)
}

PGPhysicalConnection transfers exclusive ownership of one already authenticated physical connection to the adapter. TransferToPool performs the pool-generation CAS and assumes ownership only when it returns nil. ConfirmBackendAbsence must use an independent connection or inventory.

type PGTerminalAdapter ¶

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

PGTerminalAdapter owns the physical connection from terminal-frame send through exactly one pool transfer or local destruction plus reconciliation.

func NewPGTerminalAdapter(lease PGPhysicalConnection, guard *CancelGuard, options PGAdapterOptions) (*PGTerminalAdapter, error)

func (adapter *PGTerminalAdapter) FinishCommit(ctx context.Context, owner *TerminalOwner, attempt TerminalAttempt) (PGTerminalResult, error)

func (adapter *PGTerminalAdapter) FinishRollback(ctx context.Context, owner *TerminalOwner, attempt TerminalAttempt, proof NoCommitEverSent) (PGTerminalResult, error)

func (adapter *PGTerminalAdapter) ObserveCancelEmission(emission CancelEmission)

func (adapter *PGTerminalAdapter) SendCancelRequest(ctx context.Context, dial func(context.Context) (net.Conn, error), pid, secret uint32) (CancelEmission, error)

type PGTerminalResult ¶

type PGTerminalResult struct {
	Evidence       Evidence
	Resolution     TerminalResolution
	ReleaseChecks  ReleaseChecks
	Backend        PGBackendIdentity
	WatchdogFired  bool
	CancelSnapshot CancelSnapshot
	DestroySignal  error
	LifecycleError error
}

PGTerminalResult contains the S4a total-function result plus the physical lifecycle proof. DestroySignal is ErrPGConnectionDiscarded whenever this adapter has made the connection permanently non-reusable. The businessdb capability boundary converts it to driver.ErrBadConn for physical disposal; neither signal may be used to retry a terminal operation.

type ReleaseChecks ¶

type ReleaseChecks struct {
	DrainComplete     bool
	SessionReset      bool
	HealthCheck       bool
	StatusRecheckIdle bool
	PoolTransferCAS   bool
}

func (checks ReleaseChecks) AllPassed() bool

type ResolutionContext ¶

type ResolutionContext struct {
	NoCommitProof           NoCommitEverSent
	CancelEmission          CancelEmission
	ReleaseChecks           ReleaseChecks
	BackendAbsenceConfirmed bool
}

type ServerTxState ¶

type ServerTxState = b5.ServerTxStatus

type ServerTxStatus ¶

type ServerTxStatus struct {
	State                 ServerTxState
	TransactionGeneration uint64
	AttemptGeneration     uint64
}

ServerTxStatus is one ReadyForQuery observation. Evidence retains all observations so a duplicate RFQ or a status change is contradictory.

type TerminalAttempt ¶

type TerminalAttempt struct {
	TransactionGeneration uint64
	OwnerGeneration       uint64
	AttemptGeneration     uint64
	Operation             TerminalOperation
	TimeoutOwner          bool
}

type TerminalOperation ¶

type TerminalOperation = b5.TerminalOperation

TerminalOperation is the operation selected by the single terminal-owner CAS. An operation value is never inferred from a driver error string.

type TerminalOwner ¶

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

TerminalOwner is a generation-bound single-owner CAS. The immutable snapshots make every race linearize at one atomic compare-and-swap.

func NewTerminalOwner(transactionGeneration, ownerGeneration uint64) *TerminalOwner

func (owner *TerminalOwner) AdvanceCommitStage(attempt TerminalAttempt, stage CommitStage) error

func (owner *TerminalOwner) BeginTimeoutRollback(attempt TerminalAttempt) error

func (owner *TerminalOwner) Complete(attempt TerminalAttempt, result TerminalResolution) error

func (owner *TerminalOwner) NoCommitProof(attempt TerminalAttempt) (NoCommitEverSent, bool)

func (owner *TerminalOwner) ObserveWallDeadline(transactionGeneration, ownerGeneration uint64) TimeoutObservation

func (owner *TerminalOwner) OpenCommitSendPermit(attempt TerminalAttempt) error

func (owner *TerminalOwner) Snapshot() TerminalOwnerSnapshot

func (owner *TerminalOwner) TryCommit(transactionGeneration, ownerGeneration uint64) (TerminalAttempt, bool)

func (owner *TerminalOwner) TryRollback(transactionGeneration, ownerGeneration uint64) (TerminalAttempt, bool)

func (owner *TerminalOwner) ValidateAttempt(attempt TerminalAttempt) error

func (owner *TerminalOwner) Wait(ctx context.Context) (TerminalResolution, error)

type TerminalOwnerSnapshot ¶

type TerminalOwnerSnapshot struct {
	State                      OwnerState
	TransactionGeneration      uint64
	OwnerGeneration            uint64
	AttemptGeneration          uint64
	Operation                  TerminalOperation
	CommitSendPermitEverOpened bool
	CommitStage                CommitStage
	WallDeadlineObserved       bool
}

type TerminalReply ¶

type TerminalReply struct {
	Kind                  TerminalReplyKind
	Operation             TerminalOperation
	TransactionGeneration uint64
	AttemptGeneration     uint64
	Correlation           CorrelationProof
}

TerminalReply is one decoded terminal reply. Multiple entries in Evidence are retained so duplicate ACKs and mutually exclusive positive/rejection replies can be rejected instead of silently choosing one.

type TerminalReplyKind ¶

type TerminalReplyKind uint8

const (
	ReplyKindUnknown TerminalReplyKind = iota
	ReplyNoReply
	ReplyCommitPositiveACK
	ReplyCommitDeferredErrorRejection
	ReplyRollbackPositiveACK
	ReplyRollbackDefinitiveRejection
	ReplyUntyped
)

type TerminalResolution ¶

type TerminalResolution struct {
	Schema        string
	SchemaVersion uint16
	Consistency   ConsistencyResult
	Outcome       DBOutcome
	Disposition   ConnectionDisposition
}

func ResolveTerminal(e Evidence, context ResolutionContext) TerminalResolution

type TimeoutDecision ¶

type TimeoutDecision uint8

const (
	TimeoutLost TimeoutDecision = iota
	TimeoutWonBeforeCommit
	TimeoutFinishCommitOnly
)

type TimeoutObservation ¶

type TimeoutObservation struct {
	Decision TimeoutDecision
	Attempt  TerminalAttempt
	Stage    CommitStage
}

type WriteEvidence ¶

type WriteEvidence struct {
	Phase        WritePhase
	BytesWritten uint64
	FrameBytes   uint64
}

WriteEvidence binds a phase to the connector's byte accounting. FrameBytes is the complete encoded terminal-frame length. BytesWritten is exact for all phases except WriteIndeterminate, where it is only the last known count.

type WritePhase ¶

type WritePhase = b5.WritePhase

WritePhase is connector-observed write progress for one terminal frame.