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 ¶
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 ¶
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
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 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.
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".
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. |