planread

package
v0.2.9 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package planread reads a stored schema plan back the way the operator reads it, for programs outside this module.

The SQL an operator applies lives in immutable PtahSchemaPlanChunk objects that a plan manifest binds by index, size and digest. Reading them by hand means reproducing that binding, and the binding is not a format: a chunk boundary falls wherever 512 KiB falls, which may be the middle of a SQL string, of a JSON escape, or of a UTF-8 character. Load resolves which plan a reader asked for, hands the reconstruction to the operator's own store, and returns nothing until every check the plan makes about itself has held.

`kubectl ptah plan` reads through this package, so there is one reader. Every read goes through the client the caller passes in, which is how a program reads as the person using it: a reader without the grant on chunks gets the API server's Forbidden, unchanged.

The package carries no compatibility promise before v1, like the API it reads. Pin the module version.

Index

Constants

View Source
const (
	// ChunkBytes is the largest piece of a plan one chunk object holds.
	ChunkBytes = plancontract.ChunkBytes
	// MaxChunks is the most chunks one plan is stored in.
	MaxChunks = plancontract.MaxChunks
	// MaxPlanBytes is the largest complete plan document.
	MaxPlanBytes = plancontract.MaxExecutableBytes
)

Limits a reader can size its own buffers and messages by. They are the operator's, not a copy of them.

Variables

View Source
var (
	// ErrSchemaNotFound is a schema that does not exist.
	ErrSchemaNotFound = errors.New("no such schema")
	// ErrNoPlan is a selection the schema has no plan for, or a plan that is
	// gone. Absence is not an empty plan.
	ErrNoPlan = errors.New("no such plan")
	// ErrUnsupported is a plan this build cannot read: another plan contract
	// or another document format.
	ErrUnsupported = errors.New("unsupported plan format")
	// ErrIntegrity is a stored plan that failed a check: a plan recreated
	// under the name the status holds, a plan of another schema, a storage
	// commit that did not finish, a chunk that is missing, replaced, owned by
	// something else, or does not match its digest.
	ErrIntegrity = errors.New("stored plan failed verification")
)

Errors a caller tells apart with errors.Is. An error that matches none of them is the API's, such as Forbidden on a chunk, and apierrors reads it.

Functions

func SupportedContract added in v0.2.7

func SupportedContract(version int32) bool

SupportedContract reports whether this build reads plans of a contract version: 1, a plan computed from an OCI artifact, and 2, a plan computed from a ConfigMap or a Git commit. A plan that records another one is refused with ErrUnsupported.

Types

type Chunk

type Chunk struct {
	Name   string
	Index  int32
	Size   int32
	Digest string
}

Chunk is one verified piece of a plan's storage.

type Plan

type Plan struct {
	Namespace string
	Schema    string
	SchemaUID types.UID
	Selection Selection

	PlanName      string
	PlanUID       types.UID
	Fingerprint   string
	ContentDigest string
	Dialect       string
	// Destructive is what the plan object records.
	Destructive bool
	// PrivilegeChanges are the kinds of authority the plan object records.
	// They are what the manager decided on: any of them made the plan wait
	// for an approval under apply: Always.
	PrivilegeChanges []string
	// UnrecordedPrivilegeChanges are kinds this build reads in the SQL and
	// the plan object does not record. The manager that published the plan did
	// not hold the plan for them, so they are kept apart from the recorded
	// ones rather than shown as a reason the plan waited. They appear only
	// where the reader and the manager are different builds.
	UnrecordedPrivilegeChanges []string

	Statements  []Statement
	ManagedRows []RowSet
	Chunks      []Chunk

	CreatedAt metav1.Time
	// CompletedAt is when the apply this plan belongs to finished. It is set
	// for an applied plan and empty for a current one, which has not run.
	CompletedAt *metav1.Time

	// Manifest is the plan object the checks held for. Its spec carries every
	// identifier an approval names.
	Manifest operatorv1alpha1.PtahSchemaPlan
	// Document is the bytes the store reconstructed and checked against the
	// plan's content digest: the plan as it was published.
	Document []byte
}

Plan is one verified plan.

func Load

func Load(
	ctx context.Context,
	reader client.Reader,
	namespace, name string,
	selection Selection,
) (Plan, error)

Load resolves the selected plan, reconstructs it and verifies it.

Nothing reaches the caller before every check has held. A plan whose last chunk is corrupt produces an error and an empty Plan, rather than an error after half the SQL has been handed over.

func (Plan) SQL

func (p Plan) SQL() string

SQL renders the statements as they were stored: one per entry, in order, each terminated once. Nothing is re-split on a semicolon, because a statement may carry one inside a string, a comment or a function body.

type RowSet

type RowSet struct {
	Schema  string
	Table   string
	Keys    []string
	Columns []string
}

RowSet is one declared row set a plan read: names and no values.

type Selection

type Selection string

Selection is which stored plan a reader asked for.

They are two different questions and neither answers the other: the current plan is what the operator would run next, and the applied plan is what the last confirmed apply ran. A reader asking for one is never given the other, and neither is "the newest plan object in the namespace".

const (
	// Current is the plan the schema's status names now.
	Current Selection = "current"
	// Applied is the plan the last confirmed apply ran.
	Applied Selection = "applied"
)

type Statement

type Statement struct {
	SQL string
	// Severity is Ptah's classification of the statement.
	Severity string
	// Reason is why Ptah classified it so, when it said.
	Reason string
}

Statement is one statement of a plan, as stored.

Directories

Path Synopsis
Package planreadtest holds stored plans in an in-memory API server, for tests of programs that read plans.
Package planreadtest holds stored plans in an in-memory API server, for tests of programs that read plans.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL