postgres

package
v0.0.0-...-2ce9d76 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package postgres provides PostgreSQL persistence for control-plane state.

Index

Constants

View Source 
const (
	// MaxCommandPageSize bounds one command-history database response.
	MaxCommandPageSize uint32 = 1_000
	// MaxCommandCursorBytes bounds opaque command-history pagination state.
	MaxCommandCursorBytes = 1_024
	// MaxCommandRetentionBatch bounds one terminal-command cleanup transaction.
	MaxCommandRetentionBatch uint32 = 1_000
)
View Source 
const (
	// MaxAuditBatch bounds verification and retention database work.
	MaxAuditBatch uint32 = 1_000
)

Variables

View Source 
var (
	// ErrInvalidAuditRequest reports an unscoped or unbounded audit operation.
	ErrInvalidAuditRequest = errors.New("postgres: invalid audit request")
	// ErrAuditAnchorNotFound reports a tenant without initialized audit state.
	ErrAuditAnchorNotFound = errors.New("postgres: audit anchor not found")
	// ErrInvalidAuditState reports malformed persisted audit metadata.
	ErrInvalidAuditState = errors.New("postgres: invalid audit state")
)
View Source 
var (
	// ErrInvalidCommandRequest reports an unbounded command lookup scope.
	ErrInvalidCommandRequest = errors.New("postgres: invalid command request")
	// ErrInvalidCommandState reports a malformed persisted command result.
	ErrInvalidCommandState = errors.New("postgres: invalid command state")
	// ErrInvalidCommandRetentionRequest reports an unsafe cleanup scope.
	ErrInvalidCommandRetentionRequest = errors.New("postgres: invalid command retention request")
	// ErrInvalidCommandRetentionState reports an impossible deletion count.
	ErrInvalidCommandRetentionState = errors.New("postgres: invalid command retention state")
)
View Source 
var (
	// ErrNilQueryer reports a missing PostgreSQL read boundary.
	ErrNilQueryer = errors.New("postgres: queryer is nil")
	// ErrInvalidDesiredLookup reports an unscoped or unsupported target.
	ErrInvalidDesiredLookup = errors.New("postgres: invalid desired-state lookup")
	// ErrDesiredStateNotFound reports a target without durable desired state.
	ErrDesiredStateNotFound = errors.New("postgres: desired state not found")
)
View Source 
var (
	// ErrNilBeginner reports a missing PostgreSQL transaction source.
	ErrNilBeginner = errors.New("postgres: transaction beginner is nil")
	// ErrIdempotencyConflict reports reuse of a key for another command.
	ErrIdempotencyConflict = errors.New("postgres: idempotency key conflicts with stored command")
	// ErrCompletionConflict reports an attempt to replace a terminal result.
	ErrCompletionConflict = errors.New("postgres: terminal command result conflicts with stored result")
	// ErrCommandNotFound reports completion of an unknown tenant-scoped key.
	ErrCommandNotFound = errors.New("postgres: command not found")
	// ErrAuditSequenceExhausted reports an audit chain beyond bigint capacity.
	ErrAuditSequenceExhausted = errors.New("postgres: audit sequence exhausted")
	// ErrAuditHashInvalid reports malformed persisted audit-chain state.
	ErrAuditHashInvalid = errors.New("postgres: invalid audit hash")
	// ErrDesiredStateConflict reports a concurrent desired-state replacement.
	ErrDesiredStateConflict = errors.New("postgres: desired state update conflict")
)
View Source 
var ErrInvalidMigrationDatabase = errors.New("postgres: migration database is nil")

ErrInvalidMigrationDatabase reports a missing migration connection pool.

View Source 
var ErrInvalidRuntimePool = errors.New("postgres: invalid runtime pool")

ErrInvalidRuntimePool reports a missing or uninitialized PostgreSQL pool.

View Source 
var ErrResultNotTerminal = errors.New("postgres: command result is not terminal")

ErrResultNotTerminal rejects accepted results at the completion boundary.

Functions

func MigrationSource 

func MigrationSource() (migrations.Source, error)

MigrationSource returns the immutable embedded control-plane schema history.

func NewMigrationRunner 

func NewMigrationRunner(database *sql.DB) (*migrations.Runner, error)

NewMigrationRunner builds the bounded migrations runner for the embedded control-plane schema. The caller retains ownership of database.

Types

type AuditPage 

type AuditPage struct {
	Entries      []history.Entry
	NextSequence uint64
}

AuditPage is one verified bounded tenant audit-history page.

type AuditStore 

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

AuditStore verifies and retains tenant audit history transactionally.

func NewAuditStore 

func NewAuditStore(beginner gopostgres.Beginner) (*AuditStore, error)

NewAuditStore creates a transaction-backed audit operations repository.

func (*AuditStore) AuditSensitiveAccess 

func (s *AuditStore) AuditSensitiveAccess(
	ctx context.Context,
	access controlplane.SensitiveAccess,
) error

AuditSensitiveAccess durably records one authorized privileged record read.

func (*AuditStore) ListTenant 

func (s *AuditStore) ListTenant(
	ctx context.Context,
	tenant string,
	after uint64,
	limit uint32,
) (AuditPage, error)

ListTenant returns one verified page after the supplied sequence cursor.

func (*AuditStore) RetainBefore 

func (s *AuditStore) RetainBefore(
	ctx context.Context,
	tenant string,
	cutoff time.Time,
	batchSize uint32,
) (RetentionResult, error)

RetainBefore deletes one contiguous old prefix and advances its anchor.

func (*AuditStore) VerifyTenant 

func (s *AuditStore) VerifyTenant(
	ctx context.Context,
	tenant string,
	pageSize uint32,
) (VerificationReport, error)

VerifyTenant streams and verifies one tenant chain in a repeatable snapshot.

type CommandPage 

type CommandPage struct {
	Records    []CommandRecord
	NextCursor string
}

CommandPage is one bounded newest-first tenant command-history page.

type CommandRecord 

type CommandRecord struct {
	Command controlplane.Command
	Result  controlplane.CommandResult
}

CommandRecord joins one immutable command envelope to its durable outcome.

type CommandRetentionResult 

type CommandRetentionResult struct {
	Deleted uint32
}

CommandRetentionResult reports one bounded terminal-command cleanup batch.

type CommandStore 

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

CommandStore reads tenant-scoped durable command outcomes.

func NewCommandStore 

func NewCommandStore(beginner gopostgres.Beginner) (*CommandStore, error)

NewCommandStore creates a transaction-backed command result reader.

func (*CommandStore) Get 

func (s *CommandStore) Get(
	ctx context.Context,
	tenant string,
	key string,
) (controlplane.CommandResult, error)

Get returns one durable result by tenant and idempotency key.

func (*CommandStore) ListTenant 

func (s *CommandStore) ListTenant(
	ctx context.Context,
	tenant string,
	cursor string,
	limit uint32,
) (CommandPage, error)

ListTenant returns one newest-first tenant command-history page.

func (*CommandStore) RetainCommandsBefore 

func (s *CommandStore) RetainCommandsBefore(
	ctx context.Context,
	tenant string,
	cutoff time.Time,
	batchSize uint32,
) (CommandRetentionResult, error)

RetainCommandsBefore deletes old terminal commands that no retained audit event or current desired state references.

type DesiredStore 

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

DesiredStore reads tenant-scoped operational state for worker convergence.

func NewDesiredStore 

func NewDesiredStore(queryer rowQueryer) (*DesiredStore, error)

NewDesiredStore creates a desired-state read repository.

func (*DesiredStore) Get 

func (s *DesiredStore) Get(
	ctx context.Context,
	tenant string,
	target controlplane.Target,
) (control.DesiredRecord, error)

Get returns the latest durable desired state for one target.

type Journal 

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

Journal persists command outcomes and their audit records in one transaction.

func NewJournal 

func NewJournal(beginner gopostgres.Beginner) (*Journal, error)

NewJournal creates a journal backed by postgres transaction semantics.

func (*Journal) Accept 

func (j *Journal) Accept(
	ctx context.Context,
	command controlplane.Command,
) (controlplane.CommandResult, bool, error)

Accept atomically records a command and its initial audit event.

func (*Journal) Complete 

func (j *Journal) Complete(
	ctx context.Context,
	result controlplane.CommandResult,
) error

Complete atomically records a terminal command result and audit event.

func (*Journal) MarkAcknowledged 

func (j *Journal) MarkAcknowledged(ctx context.Context, result controlplane.CommandResult) error

MarkAcknowledged atomically persists a successful data-plane acknowledgement before the terminal result is written.

func (*Journal) MarkDispatched 

func (j *Journal) MarkDispatched(ctx context.Context, result controlplane.CommandResult) error

MarkDispatched atomically persists the pre-dispatch recovery boundary and its audit event.

type PoolReadiness 

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

PoolReadiness adapts postgres bounded health checks to the API contract.

func (*PoolReadiness) Ready 

func (readiness *PoolReadiness) Ready(ctx context.Context) error

Ready performs a bounded PostgreSQL ping through postgres.

type RetentionResult 

type RetentionResult struct {
	Deleted         uint32
	AnchorSequence  uint64
	AnchorHash      history.Hash
	RetainedThrough time.Time
}

RetentionResult describes one bounded retained-prefix cleanup batch.

type Runtime 

type Runtime struct {
	Journal   *Journal
	Audit     *AuditStore
	Commands  *CommandStore
	Desired   *DesiredStore
	Readiness *PoolReadiness
}

Runtime is the complete PostgreSQL-backed control-plane service bundle. The caller retains ownership of the underlying pool.

func NewRuntime 

func NewRuntime(pool *gopostgres.Pool) (*Runtime, error)

NewRuntime wires all control-plane persistence services to one pool.

type VerificationReport 

type VerificationReport struct {
	Events       uint64
	HeadSequence uint64
	HeadHash     history.Hash
}

VerificationReport identifies the verified tenant audit head.

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.