planread

package
v0.2.13 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 18 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` and `kubectl ptah approve` read 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.

Load refuses a document that carries a field this build does not declare, the way the manager and the runner do. An approval is a decision about the whole document, so it reads through Load. LoadForDisplay is for showing a plan: it makes the same checks, names such a field instead of refusing, and returns a DisplayPlan, which an approval cannot be built from.

The Go API carries no compatibility promise before v1, like the API it reads. Pin the module version. The API compatibility page says what LoadForDisplay promises about the documents it reads.

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,
	// another document format, or, for Load, a field this build does not
	// declare.
	ErrUnsupported = errors.New("unsupported plan format")
	// ErrUnreadFields is a document with fields this build does not declare.
	// Load refuses it and LoadForDisplay reads it. An error that matches this
	// one also matches ErrUnsupported.
	ErrUnreadFields = errors.New("the document carries fields this build does not read")
	// 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 DisplayPlan added in v0.2.10

type DisplayPlan struct {
	Namespace string
	Schema    string
	Selection Selection

	PlanName      string
	Fingerprint   string
	ContentDigest string
	Dialect       string
	// Destructive is what the plan object records.
	Destructive bool
	// PrivilegeChanges and UnrecordedPrivilegeChanges are Plan's.
	PrivilegeChanges           []string
	UnrecordedPrivilegeChanges []string

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

	CreatedAt   metav1.Time
	CompletedAt *metav1.Time

	// UnreadFields names the fields of the document this build does not declare,
	// sorted, with a statement's as statements[].NAME. It holds names and never
	// a value: a value could be what strict decoding keeps away from an Apply,
	// such as the name of a credential's environment variable in a statement's
	// inputs.
	UnreadFields []string
}

DisplayPlan is what LoadForDisplay shows a person of a stored plan.

It is a type of its own so that the compiler holds what that read promises: nothing that takes a Plan takes this. It carries no UID, which an approval binds, no manifest, and no document, whose bytes hold the values of the fields this build did not read. It has no SQL method either, since its statements alone can run differently from the plan they came from.

func LoadForDisplay added in v0.2.10

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

LoadForDisplay is Load for showing a plan to a person, and for nothing else.

A stored plan outlives an upgrade, so a reader can meet a document from a Ptah newer than itself, with a field added at the same plan contract and format version. This read makes every check Load makes on the stored objects and on the fields it declares, and answers with the plan and its unknown fields named in UnreadFields.

Do not offer an approval from it, or decide anything else on it. A person who reads this plan has not read those fields, and a field Ptah added can change what the statements do when they run. Load is the read that decides.

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.

A document with a field this build does not declare is refused with ErrUnreadFields, which also matches ErrUnsupported. Anything that decides on a plan, an approval first of all, reads through this function.

func (Plan) Display added in v0.2.10

func (p Plan) Display() DisplayPlan

Display is a plan read whole, as a display read would show it.

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 the statement's classification as the operator reads it:
	// Ptah's, raised where the operator reads the SQL as destructive.
	Severity string
	// StoredSeverity is Ptah's classification as the document carries it. It
	// differs from Severity on a statement the operator raised.
	StoredSeverity 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