Documentation
¶
Overview ¶
Package dataplane defines the narrow machine-readable contracts consumed by the controller. It deliberately does not import the full Ptah module.
Index ¶
- Constants
- Variables
- func DialectMatches(engine, dialect string) bool
- func DriftFindingCategories() []string
- func DriftFindingQualifiedCategories() []string
- func DriftReportDigest(report DriftReport) (string, error)
- func IsKnownDriftFindingCategory(category string) bool
- func IsKnownDriftInventoryKind(kind string) bool
- func IsKnownMigrationOutcome(outcome string) bool
- func IsKnownPrivilegeChange(kind string) bool
- func MigrationFilesProblem(stdout []byte) (string, bool)
- func PrivilegeChangeKinds() []string
- func RowFileOutsideRoot(failed string) (string, bool)
- func SchemaSourceProblem(stdout []byte, engine string) (string, bool)
- func SchemaStructuralProblem(stdout []byte, engine, failed string) (string, bool)
- func StatementsSQL(plan PlanFile) string
- func UnseenObjectsDescription(objects []string) string
- func ValidateUnseenObjects(objects []string) error
- func VerifyRefusalDiagnostics(report VerifyReport) string
- type CommandError
- type DriftFinding
- type DriftInventoryEntry
- type DriftReport
- type InspectReport
- type MigrationDirty
- type MigrationDriftCheck
- type MigrationDriftFinding
- type MigrationDriftSummary
- type MigrationLogLoss
- type MigrationLogReport
- type MigrationRecord
- type MigrationRunFailure
- type MigrationRunReport
- type MigrationStatusReport
- type MissingPrivilege
- type PlanEffect
- type PlanEffectObject
- type PlanEffectProperty
- type PlanFile
- type PlanRowSet
- type PlanScope
- type PlanStatement
- type PullRequest
- type PulledFile
- type ResolveReport
- type RunLogReference
- type SchemaApplyFailure
- type SchemaApplyReport
- type SchemaApplyUnit
- type SchemaPlanReport
- type SchemaRefusal
- type SourcePullReport
- type TargetFailureKind
- type VerificationFinding
- type VerifyReport
Constants ¶
const ( PlanFormatVersion = 1 SchemaArtifactType = "application/vnd.stokaro.ptah.schema.v1" MigrationArtifactType = "application/vnd.stokaro.ptah.migrations.v1" // DriftFindingVocabularyVersion identifies the closed category vocabulary // accepted from native drift reports. Extending this vocabulary is a runner // protocol change: an older controller must reject, rather than publish, a // category whose disclosure contract it does not understand. // // Nothing reads this number. The refusal it describes is delivered by the // vocabulary itself, at both ends: a controller decoding a report and a // controller parsing a result frame each ask IsKnownDriftFindingCategory, // and an unknown category is refused there rather than compared here. // // Version 2 is Ptah v0.14.0's: the feature categories, which may carry a // kind, replace the per-object categories of extensions and YDB objects. // Version 3 is Ptah v0.16.0's, which compares more kinds of object and // adds their categories: comments, grants and grant options, index // visibility and renames, materialized views, role memberships, // sequences, triggers, views and validated constraints. // Version 4 is Ptah v0.23.0's: a column whose type narrows and a column // that loses its identity get categories of their own beside // columns_modified. DriftFindingVocabularyVersion = 4 // SupportedDriftContract is the version of the document `ptah schema // drift --format json` prints that this operator reads, and DriftCommand // the command that document names. Ptah gave the report a version in // stokaro/ptah#5173, together with the failure document the command now // prints in its place. A report without one comes from an earlier Ptah and // is refused. SupportedDriftContract = 1 DriftCommand = "schema drift" // MaxDriftFindingKindBytes bounds the kind a qualified category carries. // The longest qualified category is 25 bytes before the kind, so a category // the vocabulary admits is at most 153 bytes. MaxDriftFindingKindBytes = 128 )
const ( PlanEffectKindView = "view" PlanEffectActionCreate = "create" PlanEffectActionReplace = "replace" PlanEffectActionAlter = "alter" PlanEffectActionDrop = "drop" // PlanEffectSecurityInvoker is a PostgreSQL view's security_invoker: // whether the view reads the tables under it with its reader's rights // rather than its owner's. PlanEffectSecurityInvoker = "security_invoker" )
The object kinds, actions and properties of an effect the operator reads.
const ( // SupportedMigrationStatusContract and SupportedMigrationRunContract are the // Ptah machine-contract versions this operator reads. // // A document announcing another version is refused rather than read: the // fields this operator knows may still be present and may already mean // something else, and a history read under the wrong contract is a history // nobody checked. // // Version 2 of both is stokaro/ptah#5173's. A status run that cannot read // the history now prints a failure document in the status contract's // version, which a version 1 reader would take for a database with nothing // applied; a run document carries error as an object with a kind, and a // run that stopped before it selected anything is failed with nothing // planned and no status. SupportedMigrationStatusContract = 2 SupportedMigrationRunContract = 2 // MigrationStatusCommand and MigrationRunCommand are the commands the two // documents name. A status embedded in a run document names none. MigrationStatusCommand = "migrations status" MigrationRunCommand = "migrations up" // Migration states a status document reports per migration. MigrationStateApplied = "applied" MigrationStateModified = "modified" MigrationStateDirty = "dirty" MigrationStatePending = "pending" MigrationStateOutOfOrder = "out-of-order" MigrationStateCheckpointCovered = "checkpoint-covered" )
const ( MigrationOutcomeUpToDate = "up-to-date" MigrationOutcomeApplied = "applied" MigrationOutcomeDryRun = "dry-run" MigrationOutcomeFailed = "failed" MigrationOutcomePartial = "partial" MigrationOutcomeUnknown = "unknown" )
Outcomes a run document reports.
const ( MaxMigrationDescriptionBytes = 255 MaxMigrationChecksumBytes = 128 )
Bounds on what a record names. A description is the rest of a file name, which no file system lets exceed 255 bytes, and a checksum is a digest spelled out; anything longer did not come from a migration file.
const ( MigrationDriftClean = "clean" MigrationDriftDrifted = "drifted" MigrationDriftUnable = "unable" )
The outcomes of the drift check `migrations up --check-drift` reports, as Ptah v0.28.0 spells them.
const ( MigrationLogStarted = "started" MigrationLogApplied = "applied" MigrationLogFailed = "failed" )
States a lost entry of an up run would have recorded in Ptah's migration log: one before a migration runs, and one after it applied or failed. Ptah also writes rolled_back, which only a down run writes.
const ( // PrivilegeGrant is a privilege granted on an object, default privileges // included. PrivilegeGrant = "Grant" // PrivilegeRevoke is a privilege revoked from an object. PrivilegeRevoke = "Revoke" // PrivilegeRoleMembership is a role granted to, or revoked from, another // role or user. PrivilegeRoleMembership = "RoleMembership" // PrivilegeRole is a role, user or group created, altered or dropped -- its // attributes, its settings, its existence -- or assumed for the rest of the // session with SET ROLE or SET SESSION AUTHORIZATION. PrivilegeRole = "Role" // PrivilegeOwnership is an object given to another owner. PrivilegeOwnership = "Ownership" // PrivilegeRowSecurityPolicy is a row-security policy created, altered or // dropped, or row security switched off or unforced on a table. PrivilegeRowSecurityPolicy = "RowSecurityPolicy" // PrivilegeSecurityDefiner is code set to run with its owner's rights // rather than its caller's. A MySQL or MariaDB routine does that unless it // says SQL SECURITY INVOKER, so a routine that names no mode counts. A // change to the rights an existing PostgreSQL view reads with counts too, // and so does a MySQL or MariaDB statement that replaces a view, which sets // the rights it reads with whether or not it names them. PrivilegeSecurityDefiner = "SecurityDefiner" // PrivilegeDefiner is a MySQL DEFINER clause, which names the account a // view, routine, trigger or event runs as. PrivilegeDefiner = "Definer" // PrivilegeFunctionReplacement is CREATE OR REPLACE of a function or a // procedure, which can rewrite code that policies, triggers and other // roles already call. PrivilegeFunctionReplacement = "FunctionReplacement" )
The kinds of authority a plan statement can change. Each names a kind of change and never its object, its grantee or its text: the kinds are copied into the plan and into status, where a role name or a function body does not belong.
Extending this list is an API change: the CRD enumerates the same values, and a stored plan that names a kind the schema does not list stops validating.
const ( // SupportedSchemaPlanContract and SupportedSchemaApplyContract are the // versions of the documents `ptah schema plan --json` and `ptah schema // apply --json` print that this operator reads. // // Ptah raises a version when a field changes meaning or leaves, and when an // outcome gains a value. A document announcing another version is refused // rather than read for the fields this operator recognizes, because those // fields may already mean something else. // // Plan version 3 and apply version 4 are stokaro/ptah#5173's. Each carries // error as an object, the kind of a failure to open the target and Ptah's // message, where the versions before carried the message alone, and names // its command. Every outcome, the plan digest, the units an apply lists and // the refusal mean what they meant in plan version 2 and apply version 3. SupportedSchemaPlanContract = 3 SupportedSchemaApplyContract = 4 // SchemaPlanCommand and SchemaApplyCommand are the commands the two // documents name. A document naming another is refused. SchemaPlanCommand = "schema plan" SchemaApplyCommand = "schema apply" )
const ( SchemaPlanOutcomeChanges = "changes" SchemaPlanOutcomeNoChanges = "no-changes" SchemaPlanOutcomeRefused = "refused" SchemaPlanOutcomeFailed = "failed" )
Outcomes a plan document reports.
const ( SchemaApplyOutcomeApplied = "applied" SchemaApplyOutcomeNoChanges = "no-changes" SchemaApplyOutcomeDryRun = "dry-run" SchemaApplyOutcomeCanceled = "canceled" SchemaApplyOutcomeRefused = "refused" SchemaApplyOutcomeFailed = "failed" SchemaApplyOutcomeUnknown = "unknown" )
Outcomes an apply document reports. Refused and failed say that nothing reached the target; unknown says the statements were sent and the run returned an error.
const ( SchemaRefusalStalePlan = "stale-plan" SchemaRefusalProtectedTable = "protected-table" // SchemaRefusalDeclarationRefused is Ptah v0.23.0's refusal of a desired // schema whose declarations contradict each other, such as a foreign key // that references an unknown table. Ptah v0.22.0 reported the same fault // as a failed plan, with the same error message. SchemaRefusalDeclarationRefused = "declaration-refused" )
Refusal codes this operator acts on. Ptah may add codes without raising the contract version, since every refusal means nothing reached the target, so a code outside this list is read as a refusal of no particular kind rather than refused as a document.
const ( PullSourceGit = "git" PullSourceHTTPS = "https" )
The kinds of source a pull report answers, as its source field names them.
const ( UnseenTables = "tables" UnseenViews = "views" UnseenConstraints = "constraints" UnseenTriggers = "triggers" UnseenRoutines = "routines" )
The kinds of object a missing_privileges entry names, in the order the runner's sentence lists them. Ptah's tables entry covers the list of views as well; its views entry is about their definitions.
const DriftFindingKindPattern = `[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(/[A-Za-z0-9_-][A-Za-z0-9._-]*)+`
DriftFindingKindPattern is the unanchored form of driftFindingKindPattern, which the PtahSchema status patterns for a finding's category and an inventory entry's kind repeat.
const MaxDriftInventoryEntries = 128
MaxDriftInventoryEntries bounds a report's inventory, as status.target.inventory bounds it: each kind once, stem or feature kind, and every kind the vocabulary pairs fits under it.
const MaxMigrationVersionKeyBytes = 255
MaxMigrationVersionKeyBytes bounds a lost entry's version key. The key is the version a migration file's name spells, and no file system lets a name exceed 255 bytes.
const PlanEffectVersion = 1
PlanEffectVersion is the version of Ptah's statement effect record this operator reads (stokaro/ptah's docs/site/src/content/docs/reference/ statement-effects.md). Ptah raises it when a field changes meaning or leaves; a new kind of object, action, property or field keeps it. A record at another version is kept and not read, and its statement is read from its SQL.
Variables ¶
var ErrNativeApplyUnit = errors.New("schema apply lists an operation that is not SQL")
ErrNativeApplyUnit is a listed operation that is not SQL. This operator plans and reviews SQL statements, so it cannot account for one.
Functions ¶
func DialectMatches ¶
DialectMatches reports whether a Ptah report dialect belongs to the explicitly configured database engine.
func DriftFindingCategories ¶
func DriftFindingCategories() []string
DriftFindingCategories returns a copy of the closed machine vocabulary's fixed categories.
It is the list the pinned Ptah can emit. support/ptah-drift-categories.json records that list, and hack/ptahdriftcategories holds the record to the pinned source and this list to the record. An unknown category is refused rather than published or dropped. The status pattern could not store it, and leaving it out would understate the report's count and its highest severity.
Changing the list moves DriftFindingVocabularyVersion, the PtahSchema status pattern and the CRD schema version together. The frame version stays: a controller that predates a category refuses a frame carrying it, which is the refusal a version mismatch would give.
func DriftFindingQualifiedCategories ¶ added in v0.2.6
func DriftFindingQualifiedCategories() []string
DriftFindingQualifiedCategories returns a copy of the categories a report writes either bare or followed by ":<kind>".
func DriftReportDigest ¶
func DriftReportDigest(report DriftReport) (string, error)
DriftReportDigest identifies the exact comparison result emitted by one drift read. It is deliberately not a database-schema fingerprint: only a native plan's from_fingerprint may authorize an Apply. The digest is useful for audit and change detection without inventing a second schema identity.
func IsKnownDriftFindingCategory ¶
IsKnownDriftFindingCategory reports whether category belongs to the closed machine vocabulary: a fixed category, or a qualified one, bare or with a kind of the expected form and length.
func IsKnownDriftInventoryKind ¶ added in v0.2.8
IsKnownDriftInventoryKind reports whether kind is one an inventory counts: the stem of a pair of fixed finding categories, an addition and a removal, or the kind a feature owner's qualified categories carry, such as ptah.run/pgextension/extension-change (stokaro/ptah#5149).
func IsKnownMigrationOutcome ¶
IsKnownMigrationOutcome reports whether outcome is one a run document may carry. The runner's termination summary repeats a run's outcome, and it is held to the same set the document was.
func IsKnownPrivilegeChange ¶
IsKnownPrivilegeChange reports whether kind belongs to the vocabulary.
func MigrationFilesProblem ¶ added in v0.2.10
MigrationFilesProblem reads the failure document `migrations status --json` printed about a migration directory it could not load. Any other failure, including one that names a target failure kind, is not about the files.
func PrivilegeChangeKinds ¶
func PrivilegeChangeKinds() []string
PrivilegeChangeKinds returns a copy of the closed vocabulary, in the order a plan lists its kinds.
func RowFileOutsideRoot ¶ added in v0.2.11
RowFileOutsideRoot reads the sentence a failed `schema drift` or `schema plan` holds when a `data` block names a row file outside the directory Ptah bounds row files by, which is its working directory. It returns the guard's sentence without drift's wrapper, so both commands give the same reason:
managed data file "../x.yaml" for table public.t: "/x.yaml" is outside allowed root "/work" managed data file "/x.yaml" for table public.t: a path starting at a root is outside allowed root "/work"
Every other sentence a validate run explains is copied from that child, which has no connection. This one is copied from the failed command, which had one, and so only the whole of it, in the guard's own form: the declared path, the resolved path and the root are each one quoted string, the resolved path and the root are absolute, and nothing follows the root. Ptah writes it from the declaration and the file system before it opens the file, so none of it is something the database answered, and a database's answer reaches a failed sentence in another form: another prefix, or a line of SQL after it.
func SchemaSourceProblem ¶ added in v0.2.10
SchemaSourceProblem reads what `schema validate` printed about a desired schema it could not load: `<dialect>: source: <reason>`, in the dialect the engine names. The reason is as Ptah printed it, across lines if it spans them: what leaves the runner is the runner's to make, after it has redacted the words.
Only that shape is read here. Validate also reports structural problems, a `schema` or an `index` line, which say why a command failed only where that command stopped on them; SchemaStructuralProblem reads those. A load failure says it of every command: drift and plan load the same file before they compare anything.
func SchemaStructuralProblem ¶ added in v0.2.10
SchemaStructuralProblem reads what `schema validate` printed about the schema's structure when that fault is the one the command that failed stopped on, in the dialect the engine names. failed is the sentence the failed command's own document holds.
Validate prints a line for each index it refuses first, and then a fault of the schema as a whole, such as a foreign key into a table it does not declare, which runs to the end of its output. Since Ptah v0.26.0 drift and plan check every index before they compare anything (stokaro/ptah#5845), and the first one they refuse stops them with validate's line, dialect and all. So an `<dialect>: index <name>: <fault>` line is read when failed is that line and nothing else, and the reason is the line after the dialect. A `<dialect>: schema: <fault>` line is read when failed ends with its words: drift and plan run the validator that wrote it, and wrap its sentence and nothing else around it. The reason is then the fault.
Validate reports a fault of the file whether or not it stopped anything, and the command that failed may have stopped on the database or on another fault validate does not know. Comparing the words is what ties the two.
failed is compared and never returned. Its command had a connection, so it could quote the database. What is returned comes from a run that had none.
func StatementsSQL ¶
StatementsSQL renders a plan's statements as they were stored.
One statement per entry, in the order the plan holds them, each terminated once. Nothing is re-split on a semicolon: a statement may carry one inside a string, a comment or a function body, and splitting there would hand a reader SQL the plan never held.
func UnseenObjectsDescription ¶ added in v0.2.10
UnseenObjectsDescription is the runner's sentence for a permission_denied failure that names what the account cannot see. Like every description it is fixed text: the kinds come from the vocabulary, and no database, object or privilege Ptah named is in it. It is empty for a list ValidateUnseenObjects refuses.
func ValidateUnseenObjects ¶ added in v0.2.10
ValidateUnseenObjects refuses a list UnseenObjects could not have returned: empty, a kind outside the vocabulary, a repeated kind, or one out of order.
func VerifyRefusalDiagnostics ¶ added in v0.2.10
func VerifyRefusalDiagnostics(report VerifyReport) string
VerifyRefusalDiagnostics is what `ptah oci verify` writes to standard error when the policy refuses an artifact: the report's own findings, as one sentence and a line for each, after the report on standard output and before exit status 2. The harness row schema-verify-refused/verify-other-type holds this text to the pinned image.
The runner compares a verification's standard error with this and nothing looser, so a line the report does not hold is not read as a refusal.
Types ¶
type CommandError ¶ added in v0.2.10
type CommandError struct {
// Kind is from the vocabulary above, or a kind a later Ptah added, or
// absent when the failure has none.
Kind string `json:"kind,omitempty"`
// Message is Ptah's sentence for a person. It can quote what the database
// said, so nothing but a protected-table refusal's tables is copied from
// it. SchemaStructuralProblem compares it with words from a run that had no
// database, and copies none of it.
Message string `json:"message"`
// MissingPrivileges is what a MySQL or MariaDB account could not see when
// Ptah reports permission_denied for a read of the target, one entry for
// each kind of object. Ptah v0.23.0 adds it.
MissingPrivileges []MissingPrivilege `json:"missing_privileges,omitempty"`
}
CommandError is the error object a Ptah document carries for a run that failed.
func DecodeDriftFailure ¶ added in v0.2.10
func DecodeDriftFailure(data []byte) (*CommandError, error)
DecodeDriftFailure reads the document `schema drift --format json` prints on standard output when it fails: its contract version, its command and the error, in place of the report.
func DecodeMigrationStatusFailure ¶ added in v0.2.10
func DecodeMigrationStatusFailure(data []byte) (*CommandError, error)
DecodeMigrationStatusFailure reads the document `migrations status --json` prints on standard output when it cannot read the history.
func (*CommandError) TargetFailure ¶ added in v0.2.10
func (e *CommandError) TargetFailure() (TargetFailureKind, bool)
TargetFailure is the kind of the error, when it is one of the vocabulary. A nil error has none.
func (*CommandError) UnseenObjects ¶ added in v0.2.10
func (e *CommandError) UnseenObjects() ([]string, bool)
UnseenObjects is the kinds of object a permission_denied failure says the account cannot see, in vocabulary order and each once. It is false when the failure is not permission_denied, names no kind, or names one outside the vocabulary: a list without that kind would understate what is missing, so the failure then reads as the plain permission_denied.
type DriftFinding ¶
type DriftInventoryEntry ¶ added in v0.2.8
type DriftInventoryEntry struct {
Kind string `json:"kind"`
Desired int32 `json:"desired"`
Observed int32 `json:"observed"`
}
DriftInventoryEntry counts one kind of object on both sides of the comparison the drift report made: how many the desired schema declares and how many the database holds, within the compared scope. Kind joins the inventory to the findings: "tables" is the stem of tables_added and tables_removed, and "ptah.run/pgextension/extension-change" is the kind feature_changes:ptah.run/pgextension/extension-change carries. It names no object.
The counts are int32, as status stores them: a count past that fails to decode, and the report with it.
type DriftReport ¶
type DriftReport struct {
ContractVersion int `json:"contract_version"`
Command string `json:"command"`
Drift bool `json:"drift"`
Failed bool `json:"failed"`
FailureThreshold string `json:"failure_threshold"`
HighestSeverity string `json:"highest_severity"`
Dialect string `json:"dialect,omitempty"`
Sources string `json:"sources,omitempty"`
DatabaseURL string `json:"database_url,omitempty"`
IgnoredTables []string `json:"ignored_tables,omitempty"`
Findings []DriftFinding `json:"findings,omitempty"`
Diff json.RawMessage `json:"diff,omitempty"`
// Inventory is absent from a Ptah that does not count, which the
// operator reads as a report with no inventory rather than an empty one.
Inventory []DriftInventoryEntry `json:"inventory,omitempty"`
// Error is present only on the failure document the command prints in
// place of a report, which DecodeDrift refuses and DecodeDriftFailure
// reads.
Error *CommandError `json:"error,omitempty"`
}
func DecodeDrift ¶
func DecodeDrift(data []byte, exitCode int) (DriftReport, error)
DecodeDrift maps the CLI's configured failure threshold into a domain result. Drift may be reported without failing the command.
type InspectReport ¶
type InspectReport struct {
Reference string `json:"reference"`
PinnedReference string `json:"pinned_reference"`
Digest string `json:"digest"`
MediaType string `json:"media_type"`
Size int64 `json:"size"`
ArtifactType string `json:"artifact_type"`
}
func DecodeInspect ¶
func DecodeInspect(data []byte) (InspectReport, error)
type MigrationDirty ¶
type MigrationDirty struct {
Version int64 `json:"version"`
Applied int `json:"applied"`
Total int `json:"total"`
Error string `json:"error,omitempty"`
}
MigrationDirty is the revision row a failed or interrupted run left behind.
type MigrationDriftCheck ¶ added in v0.2.13
type MigrationDriftCheck struct {
Outcome string `json:"outcome"`
Replayed []int64 `json:"replayed,omitempty"`
Stage string `json:"stage,omitempty"`
Reason string `json:"reason,omitempty"`
Message string `json:"message,omitempty"`
Findings []MigrationDriftFinding `json:"findings,omitempty"`
}
MigrationDriftCheck is the drift_check object of a run document. Ptah writes it when --check-drift was passed and the check ran, before any pending migration: a run whose check did not come back clean applied nothing.
Message, and each finding's message and names, are Ptah's text: a message can carry what the driver said about the shadow database, its host or its user, so the frame keeps a summary of it and nothing else.
func (*MigrationDriftCheck) Summary ¶ added in v0.2.13
func (c *MigrationDriftCheck) Summary() *MigrationDriftSummary
Summary is the frame's account of the check.
type MigrationDriftFinding ¶ added in v0.2.13
type MigrationDriftFinding struct {
Kind string `json:"kind"`
}
MigrationDriftFinding is one difference a drifted check found, or one object an unable check could not compare.
type MigrationDriftSummary ¶ added in v0.2.13
type MigrationDriftSummary struct {
Outcome string `json:"outcome"`
Stage string `json:"stage,omitempty"`
Reason string `json:"reason,omitempty"`
Findings int `json:"findings,omitempty"`
}
MigrationDriftSummary is a drift check in the terms a frame carries: the outcome, the stage and reason codes Ptah gave an unable one, and how many findings there were. It carries no text and no object name.
func (*MigrationDriftSummary) Refused ¶ added in v0.2.13
func (s *MigrationDriftSummary) Refused() bool
Refused reports a check that stopped the run: drifted or unable.
func (MigrationDriftSummary) Validate ¶ added in v0.2.13
func (s MigrationDriftSummary) Validate() error
Validate holds a summary to the shape each outcome has: a clean check names no stage, reason or finding, a drifted one names at least one finding and no stage or reason, and an unable one names a stage and a reason.
type MigrationLogLoss ¶ added in v0.2.12
type MigrationLogLoss struct {
// Operation is the verb the entry belongs to, up for every run this
// operator dispatches.
Operation string `json:"operation"`
// Version and VersionKey name the migration the entry is about. Ptah
// always writes the key, because an empty string is itself an identity.
Version int64 `json:"version"`
VersionKey string `json:"version_key"`
// State is what the entry would have recorded.
State string `json:"state,omitempty"`
// SQLState is empty when the server gave no answer, and ErrorNumber is
// zero on every protocol but MySQL's.
SQLState string `json:"sqlstate,omitempty"`
ErrorNumber int `json:"error_number,omitempty"`
// Message is Ptah's sentence about the refusal, which can quote part of
// the value the database refused. The runner clears it before the report
// reaches a frame, and a frame that carries one is refused, so SQLState
// and ErrorNumber are what say why.
Message string `json:"message,omitempty"`
}
MigrationLogLoss is one entry the migration log should hold and does not.
type MigrationLogReport ¶ added in v0.2.12
type MigrationLogReport struct {
// Written counts the entries the database accepted.
Written int `json:"written"`
// Lost names each entry the database refused, in the order the run tried
// them.
Lost []MigrationLogLoss `json:"lost,omitempty"`
}
MigrationLogReport is what a run's writes to Ptah's migration log came to: the schema_migrations_log rows Ptah writes beside the revision table, one before each migration it runs and one after. A write the database refuses does not stop the migration, so the run is the only witness to a lost entry, and the table cannot say what it was never given. Ptah reports it in the run document since v0.23.0 (stokaro/ptah#5541), and leaves it out when the run keeps no log or stopped before it selected anything.
A lost entry changes nothing about the outcome, which Ptah reads from the revision table and not from the log.
func (*MigrationLogReport) ClearMessages ¶ added in v0.2.12
func (r *MigrationLogReport) ClearMessages()
ClearMessages drops every lost entry's message.
func (*MigrationLogReport) LostCount ¶ added in v0.2.12
func (r *MigrationLogReport) LostCount() int
LostCount is how many entries the log lacks, and zero for a report that is absent.
func (MigrationLogReport) Validate ¶ added in v0.2.12
func (r MigrationLogReport) Validate(planned []int64) error
Validate holds a log report to the up run that wrote it, whose selection is planned. A run writes at most two entries for each migration it selected, and each lost entry names one of them with a state an up run records. The code the database answered with is held to the forms a run's failure is: a value that failed its form could be anything, so nothing here quotes it.
type MigrationRecord ¶
type MigrationRecord struct {
Version int64 `json:"version"`
VersionKey string `json:"version_key,omitempty"`
Description string `json:"description,omitempty"`
Checksum string `json:"checksum,omitempty"`
AppliedChecksum string `json:"applied_checksum,omitempty"`
Checkpoint bool `json:"checkpoint,omitempty"`
TransactionMode string `json:"transaction_mode,omitempty"`
// AppliedAt is when the migration's revision row was written, and
// ExecutionMs how long it ran in whole milliseconds, as the row recorded
// them. Ptah reports both only for a row that exists, and no duration for
// a revision table too old to record one. Neither is part of the history
// fingerprint: a plan's premise is which migrations are applied, not when.
AppliedAt *time.Time `json:"applied_at,omitempty"`
ExecutionMs *int64 `json:"execution_time_ms,omitempty"`
State string `json:"state"`
}
MigrationRecord is one migration of the artifact as the database accounts for it.
func (MigrationRecord) HasRevisionRow ¶ added in v0.2.7
func (m MigrationRecord) HasRevisionRow() bool
HasRevisionRow reports whether the database holds a revision row for the record: an applied migration, a modified one, or the dirty one a failed run left behind.
type MigrationRunFailure ¶ added in v0.2.6
type MigrationRunFailure struct {
Version int64 `json:"version"`
Statement int `json:"statement"`
Statements int `json:"statements"`
// Commit is true when every statement ran and the commit that ends them
// failed, as a deferred constraint does. No statement is to blame then,
// and Statement is 0: that is Ptah's documented contract (docs/
// exit_codes.md, "Where a Run Stopped", introduced in stokaro/ptah#5562).
// Under --tx-mode all the one commit ends every selected migration, and
// Version names the last of them.
Commit bool `json:"commit,omitempty"`
// SQLState is empty when the server gave no answer, and ErrorNumber is
// zero on every protocol but MySQL's.
SQLState string `json:"sqlstate,omitempty"`
ErrorNumber int `json:"error_number,omitempty"`
}
MigrationRunFailure is the statement a run stopped at and the code the database answered with. Ptah writes it when a statement reached the database and failed, and since v0.23.0 also when the statements ran and the commit that ends them failed. Unlike Error's message it carries no text, so it names no row and may reach status and Events (#69, #678).
type MigrationRunReport ¶
type MigrationRunReport struct {
ContractVersion int `json:"contract_version"`
Direction string `json:"direction"`
Outcome string `json:"outcome"`
Planned []int64 `json:"planned,omitempty"`
Applied []int64 `json:"applied,omitempty"`
// Error is why the run failed. Its message can quote a row, so the runner
// reads its kind and drops the object before the report reaches a frame.
Error *CommandError `json:"error,omitempty"`
Failure *MigrationRunFailure `json:"failure,omitempty"`
// MigrationLog is what the run's writes to the migration log came to. A
// run that keeps no log, or a Ptah before v0.23.0, reports none, which
// says nothing either way about the log.
MigrationLog *MigrationLogReport `json:"migration_log,omitempty"`
Status *MigrationStatusReport `json:"status,omitempty"`
// DriftCheck is the check --check-drift ran, as Ptah wrote it. A run
// that was not asked for one, or that stopped before it, carries none.
// The runner reads it into DriftSummary and drops it before the report
// reaches a frame.
DriftCheck *MigrationDriftCheck `json:"drift_check,omitempty"`
// DriftSummary is what a frame keeps of DriftCheck. Ptah writes no such
// field.
DriftSummary *MigrationDriftSummary `json:"driftSummary,omitempty"`
}
MigrationRunReport is Ptah's `migrations up --json` document.
func DecodeMigrationRun ¶
func DecodeMigrationRun(data []byte) (MigrationRunReport, error)
DecodeMigrationRun reads a run document, including the status it carries.
func (MigrationRunReport) StoppedBeforeSelecting ¶ added in v0.2.10
func (r MigrationRunReport) StoppedBeforeSelecting() bool
StoppedBeforeSelecting reports a run that failed before Ptah selected any migration: it read no history, planned and applied nothing, and sent no migration statement. A target that could not be opened ends a run this way.
type MigrationStatusReport ¶
type MigrationStatusReport struct {
ContractVersion int `json:"contract_version"`
CurrentVersion int64 `json:"current_version"`
CheckpointVersion int64 `json:"checkpoint_version,omitempty"`
TotalMigrations int `json:"total_migrations"`
HasPendingChanges bool `json:"has_pending_changes"`
// PendingMigrations is the selection Ptah itself made: the versions its
// next run would execute, in the order it would execute them. It is not
// the same question the per-migration states answer, and after a
// checkpoint bootstrap the two disagree on purpose -- a version the
// checkpoint replaced is reported pending once the bootstrap is no longer
// what the database is doing, and Ptah's own floor still skips it.
//
// Carried without omitempty, because this report is decoded from Ptah and
// encoded again into the runner's result frame, and an empty selection is
// the answer that matters: it says the next run would execute nothing.
// Dropped from the frame, it reaches the controller as an absent field,
// which [MigrationStatusReport.Pending] reads as a build that reports no
// selection at all and answers by recounting the states. Ptah declares the
// field the same way for the same reason.
PendingMigrations []int64 `json:"pending_migrations"`
Migrations []MigrationRecord `json:"migrations,omitempty"`
DirtyRevision *MigrationDirty `json:"dirty_revision,omitempty"`
}
MigrationStatusReport is Ptah's `migrations status --json` document.
func DecodeMigrationStatus ¶
func DecodeMigrationStatus(data []byte) (MigrationStatusReport, error)
DecodeMigrationStatus reads a status document and refuses everything it cannot fully account for.
The failure document `migrations status` prints when it cannot read the history is refused here, before anything reads it as a status: it carries the status contract version and none of the status fields, so it would otherwise read as a database with nothing applied. DecodeMigrationStatusFailure reads it.
func (MigrationStatusReport) LastVersion ¶
func (r MigrationStatusReport) LastVersion() int64
LastVersion is the highest version the artifact carries, and zero for an artifact that carries none. It is the artifact's own extent: the document lists the artifact's migrations with what the database did about each, so a revision beyond this number is one the artifact cannot account for at all.
func (MigrationStatusReport) Modified ¶
func (r MigrationStatusReport) Modified() []int64
Modified names the applied migrations whose files no longer account for them. Nothing may execute while one exists, and the controller never resolves it.
func (MigrationStatusReport) OutOfOrder ¶
func (r MigrationStatusReport) OutOfOrder() []int64
OutOfOrder names the pending migrations that sort below a version the database has already applied. Ptah's linear execution order refuses a run while one exists, so a plan that carried them would be a decision nobody could execute.
func (MigrationStatusReport) Pending ¶
func (r MigrationStatusReport) Pending() []int64
Pending names the versions the next run would execute, in the order Ptah would execute them.
The list is Ptah's, because deriving a second one from the per-migration states gets a database that bootstrapped from a checkpoint wrong: the versions the checkpoint replaced report themselves pending afterwards, while Ptah's own floor skips them and its selection is empty. A controller that recounted would publish a plan for migrations that cannot run, and publish it again after every run that correctly did nothing.
A document that carries no selection at all is read the old way, so a build that reports only states still resolves to a list rather than to silence.
type MissingPrivilege ¶ added in v0.2.10
type MissingPrivilege struct {
Objects string `json:"objects"`
}
MissingPrivilege is one entry of missing_privileges. Only the kind of object is read. The entry also names the database, the objects the account could list and not read, and the privilege spelled with the database's name, and none of those may leave the Pod.
type PlanEffect ¶ added in v0.2.12
type PlanEffect struct {
Version int `json:"version"`
Object PlanEffectObject `json:"object"`
Action string `json:"action"`
Properties []PlanEffectProperty `json:"properties,omitempty"`
// contains filtered or unexported fields
}
PlanEffect is what Ptah recorded one plan statement does to one object, computed from the database the plan read: the object, the kind of statement, and each property's value before the statement runs and after.
Ptah adds fields without raising Version, and a reader leaves out what it does not know. So a record is decoded leniently inside the strict plan decoder: a field it does not declare is ignored, and a record whose declared fields do not have the types version 1 gives them is kept unread, as a record at another version is. Nothing in a record reaches the executor. Ptah does not read effects back when it applies a plan, and the plan digest and the approval cover them with the rest of the file.
func (PlanEffect) Read ¶ added in v0.2.12
func (e PlanEffect) Read() bool
Read reports whether the record is one the operator reads: version 1, with its declared fields of the declared types.
func (*PlanEffect) UnmarshalJSON ¶ added in v0.2.12
func (e *PlanEffect) UnmarshalJSON(data []byte) error
UnmarshalJSON decodes one effect record. Only a value that is not a JSON object is an error, which refuses the plan: the list holds records, and something else in it is not a record of any version.
type PlanEffectObject ¶ added in v0.2.12
type PlanEffectObject struct {
Kind string `json:"kind"`
Schema string `json:"schema,omitempty"`
Name string `json:"name"`
}
PlanEffectObject names the object an effect describes, as the database spells it.
type PlanEffectProperty ¶ added in v0.2.12
type PlanEffectProperty struct {
Name string `json:"name"`
Before json.RawMessage `json:"before,omitempty"`
After json.RawMessage `json:"after,omitempty"`
Changed bool `json:"changed"`
}
PlanEffectProperty is one property of the object, before the statement runs and after. An absent value says the object does not exist at that point. The values stay undecoded here: a property a later Ptah adds may hold another type, and each property the operator reads is decoded where it is read.
type PlanFile ¶
type PlanFile struct {
FormatVersion int `json:"format_version"`
Name string `json:"name"`
Dialect string `json:"dialect"`
FromFingerprint string `json:"from_fingerprint"`
ToFingerprint string `json:"to_fingerprint"`
Exclude []string `json:"exclude,omitempty"`
// SchemasBeyondURL names the schemas the source fingerprint covers that the
// connection URL's own scope does not: a desired state that names a schema
// other than the one a schema-scoped URL connects to. Ptah reads the same
// set again when it verifies the plan before applying it. The operator
// carries the plan bytes as they are and reads nothing from this field; it
// is declared so the strict decoder accepts a plan that has it.
SchemasBeyondURL []string `json:"schemas_beyond_url,omitempty"`
// Scope is what the connection URL covered when Ptah computed the plan. Ptah
// v0.19.0 records it so that a stale plan's refusal can name both scopes
// (stokaro/ptah#5239), and it decides nothing else. The operator reads
// nothing from it either; it is declared so the strict decoder accepts every
// plan Ptah saves since then.
Scope *PlanScope `json:"scope,omitempty"`
// ManagedRows and RowsFingerprint describe the declared row sets this plan
// read, and the state it read them in. A plan that changes declared rows
// carries both, and a plan that changes only structure carries neither.
//
// They are names and a digest: a table, its key columns and the columns the
// declaration owns, plus one fingerprint over the rows as they were. No row
// value appears here, which is what lets the operator read them, publish
// them and report on them while no declared value reaches status, an Event
// or an ordinary log.
ManagedRows []PlanRowSet `json:"managed_rows,omitempty"`
RowsFingerprint string `json:"rows_fingerprint,omitempty"`
Destructive bool `json:"destructive"`
Statements []PlanStatement `json:"statements"`
// PrivilegeChanges are the kinds of authority the statements change, read
// by the operator from the SQL: grants, role membership, ownership,
// row-security policies and definer rights. A view's security_invoker is
// read from the statement's effects where Ptah recorded them. Ptah's
// document has no such field and cannot supply one, since a plan is
// decoded strictly; the list is the operator's own, in the order
// PrivilegeChangeKinds gives.
PrivilegeChanges []string `json:"-"`
}
PlanFile is the plan document `schema plan --output` saves. It is decoded strictly: a field it does not declare refuses the plan.
A plan's annotations and a statement's inputs, which Ptah v0.17.0 writes only for an engine an executable provider serves, stay undeclared on purpose. An input names an environment variable that Ptah reads with os.LookupEnv in its own process at Apply and hands to the provider, and in an Apply Pod that environment holds the database credential, so an approved plan could name it. The operator runs PostgreSQL and MySQL, which Ptah plans without a provider, and refuses a plan that carries either field.
type PlanRowSet ¶
type PlanRowSet struct {
Schema string `json:"schema,omitempty"`
Table string `json:"table"`
Keys []string `json:"keys"`
Columns []string `json:"columns"`
}
PlanRowSet is one declared row set a plan read: the table it owns, the columns that identify a row in it, and the columns the declaration writes.
type PlanScope ¶ added in v0.2.10
PlanScope is what the URL of a saved plan covered: "realm" for every schema of a PostgreSQL database, or "schema" with the name of the one schema or MySQL database it pins.
type PlanStatement ¶
type PlanStatement struct {
SQL string `json:"sql"`
Severity string `json:"severity"`
Reason string `json:"reason"`
// Transactions, Owned, Access and AccessReason are what Ptah v0.14.0
// records on a statement a feature owner rendered: CREATE EXTENSION, or a
// row-security policy. The strict decoder refused every such plan until
// they were declared. The operator reads none of them and carries the plan
// bytes as they are. Ptah folds the access assessment into Severity, and
// refuses a plan whose severity is lower than its assessment requires each
// time it reads one, so the plan Job's dry run checks the plan before the
// operator publishes it. The privilege kinds are still read from the SQL.
Transactions []string `json:"transactions,omitempty"`
Owned bool `json:"owned,omitempty"`
Access string `json:"access,omitempty"`
AccessReason string `json:"access_reason,omitempty"`
// Effects is what Ptah v0.26.0 records the statement does to the objects
// it changes, computed from the database the plan read
// (stokaro/ptah#5954): for a PostgreSQL view, its security options before
// the statement runs and after. A statement Ptah does not describe carries
// none, and neither does any statement of a plan from an earlier Ptah. The
// privilege reading takes a view's security_invoker from it and everything
// else from the SQL.
Effects []PlanEffect `json:"effects,omitempty"`
}
type PullRequest ¶ added in v0.2.12
PullRequest is what a pull was asked for: the kind of source, the reference and the path, and for HTTPS the format. A report answers it only if it names the same.
type PulledFile ¶ added in v0.2.12
type PulledFile struct {
Path string `json:"path"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
}
PulledFile is one file a pull read.
type ResolveReport ¶
type ResolveReport struct {
Reference string `json:"reference"`
PinnedReference string `json:"pinned_reference"`
Digest string `json:"digest"`
MediaType string `json:"media_type"`
Size int64 `json:"size"`
}
func DecodeResolve ¶
func DecodeResolve(data []byte) (ResolveReport, error)
type RunLogReference ¶ added in v0.2.13
type RunLogReference struct {
// Written counts the entries the database accepted.
Written int `json:"written"`
// RunReference is the caller's reference the written entries carry.
RunReference string `json:"run_reference,omitempty"`
}
RunLogReference is what a run's document says about the entries it wrote to the database's own log, as far as the run reference goes: how many the database accepted, and the reference they carry. Ptah v0.28.0 reports it as apply_log in the schema apply document and as migration_log in the migrations up document (stokaro/ptah#6014), and leaves the reference out when the run was given none or wrote no entry.
It is read beside the report the frame carries rather than as part of it, so a frame holds what it held before the reference existed.
func DecodeMigrationLogReference ¶ added in v0.2.13
func DecodeMigrationLogReference(data []byte) (*RunLogReference, error)
DecodeMigrationLogReference reads the run reference a migrations up document reports for its log entries. DecodeMigrationRun validates the rest of the document; this reads one more field of the same bytes.
func (*RunLogReference) CheckRunReference ¶ added in v0.2.13
func (r *RunLogReference) CheckRunReference(expected string) error
CheckRunReference holds the reference a run reports to the one it was given.
A document that names another reference is not this run's account: it was written for another run, or by a Ptah that stored a value other than the one it was handed, and either way the entries it counts cannot be joined to this operation. A document that counts written entries and names no reference says the entries carry none. On the SQL engines every entry Ptah writes carries the reference it was given, and only a provider's own log store keeps none, which neither engine this operator runs is. A run that wrote nothing names nothing, and that is the only reading of an absent reference that holds. An absent report is a run that kept no log, and holds.
The reported value is not quoted, because a value that failed the check could be anything.
type SchemaApplyFailure ¶ added in v0.2.11
type SchemaApplyFailure struct {
// Statement is the position of the failed unit among the units the
// document lists, counting from one. It is zero when no unit is to blame:
// the commit after them failed, or the run confirmed every unit and still
// did not succeed.
Statement int `json:"statement"`
// Statements is how many units the document lists.
Statements int `json:"statements"`
// Commit is true when every unit ran and the commit that ends them failed.
Commit bool `json:"commit,omitempty"`
// SQLState is empty when the server gave no answer, and ErrorNumber is
// zero on every protocol but MySQL's.
SQLState string `json:"sqlstate,omitempty"`
ErrorNumber int `json:"error_number,omitempty"`
}
SchemaApplyFailure is the unit or the commit a schema apply stopped at, as Ptah's apply document names it (docs/exit_codes.md, "Where a Run Stopped").
func (SchemaApplyFailure) Failed ¶ added in v0.2.11
func (f SchemaApplyFailure) Failed() bool
Failed reports whether the failure names the statement the run stopped at. A failed commit, and a run that stopped with every unit confirmed, name none: Validate holds both to statement zero.
func (SchemaApplyFailure) Validate ¶ added in v0.2.11
func (f SchemaApplyFailure) Validate() error
Validate holds a failure to the forms Ptah's contract gives it. Nothing here quotes the SQLSTATE back, because a value that failed its form could be anything.
type SchemaApplyReport ¶
type SchemaApplyReport struct {
ContractVersion int `json:"contract_version"`
Command string `json:"command"`
Outcome string `json:"outcome"`
PlanName string `json:"plan_name,omitempty"`
PlanDigest string `json:"plan_digest,omitempty"`
Units []SchemaApplyUnit `json:"units,omitempty"`
Refusal *SchemaRefusal `json:"refusal,omitempty"`
// Error is why the run failed, refused or ended unknown. Only its kind is
// read.
Error *CommandError `json:"error,omitempty"`
// Failure is where a run that sent a statement stopped, and the code the
// database answered with. It carries no text, so it is what may leave the
// Pod. A build before stokaro/ptah#5562 writes none.
Failure *SchemaApplyFailure `json:"failure,omitempty"`
// ApplyLog is what the run's writes to ptah_schema_apply_log came to, read
// for the run reference the entries carry. Its lost entries are not read:
// a lost entry changes nothing about the outcome.
ApplyLog *RunLogReference `json:"apply_log,omitempty"`
}
SchemaApplyReport is Ptah's `schema apply --json` document.
func DecodeSchemaApply ¶
func DecodeSchemaApply(data []byte) (SchemaApplyReport, error)
DecodeSchemaApply reads one apply document under the rules DecodeSchemaPlan states.
func (SchemaApplyReport) SQLStatements ¶ added in v0.2.7
func (r SchemaApplyReport) SQLStatements() ([]string, error)
SQLStatements is the SQL of each listed unit, in order. A unit that is a native operation, or that has no SQL, is refused rather than skipped.
type SchemaApplyUnit ¶ added in v0.2.7
type SchemaApplyUnit struct {
SQL string `json:"sql,omitempty"`
Native json.RawMessage `json:"native,omitempty"`
}
SchemaApplyUnit is one planned operation an apply document lists: its SQL, or a summary of a native provider operation that has none.
type SchemaPlanReport ¶
type SchemaPlanReport struct {
ContractVersion int `json:"contract_version"`
Command string `json:"command"`
Outcome string `json:"outcome"`
PlanDigest string `json:"plan_digest,omitempty"`
PlanPath string `json:"plan_path,omitempty"`
Refusal *SchemaRefusal `json:"refusal,omitempty"`
// Error is why the run failed or refused. Its message is the sentence
// Ptah printed on standard error and may quote a statement, so it is for a
// fence refusal's tables and nothing else; its kind names a target that
// could not be opened.
Error *CommandError `json:"error,omitempty"`
}
SchemaPlanReport is Ptah's `schema plan --json` document.
The plan document it embeds is not declared, so it is not read: the file --output wrote is the plan, and PlanDigest is what binds the report to it.
func DecodeSchemaPlan ¶
func DecodeSchemaPlan(data []byte) (SchemaPlanReport, error)
DecodeSchemaPlan reads one plan document and refuses anything it cannot account for: another contract version, an outcome it does not know, a second JSON value, and an outcome whose fields contradict it.
Fields it does not declare are ignored, because Ptah adds fields without raising the version.
type SchemaRefusal ¶
type SchemaRefusal struct {
Code string `json:"code"`
// Tables are the fenced tables a protected-table refusal names.
Tables []string `json:"tables,omitempty"`
// Changed is what moved under a stale-plan refusal: "schema" or "rows".
Changed string `json:"changed,omitempty"`
PlanFingerprint string `json:"plan_fingerprint,omitempty"`
DatabaseFingerprint string `json:"database_fingerprint,omitempty"`
}
SchemaRefusal is why a plan or an apply refused. Only the fields its code describes are set.
type SourcePullReport ¶ added in v0.2.12
type SourcePullReport struct {
Source string `json:"source"`
Reference string `json:"reference"`
Path string `json:"path"`
ContentDigest string `json:"content_digest"`
Files []PulledFile `json:"files"`
Written []string `json:"written"`
// Commit is the commit a Git pull read.
Commit string `json:"commit,omitempty"`
// Format, DownloadDigest and DownloadSize are what an HTTPS pull read:
// how the download carries the files, as the --format flag named it,
// and the SHA-256 and the size of the bytes the URL served.
Format string `json:"format,omitempty"`
DownloadDigest string `json:"download_digest,omitempty"`
DownloadSize int64 `json:"download_size,omitempty"`
}
SourcePullReport is the document `ptah schema pull` and `ptah migrations pull` print with --json for a Git or an HTTPS reference. Every kind names the reference, the selected path, the content digest of the selected files and the files themselves; the rest belongs to one kind.
func DecodeSourcePull ¶ added in v0.2.12
func DecodeSourcePull(data []byte, asked PullRequest) (SourcePullReport, error)
DecodeSourcePull reads a pull's report and holds it to the pull it answers: the kind, the reference, the path and an HTTPS pull's format asked for, the evidence of that kind and no other's, and a content digest the listed files give. A report that names a digest its own file list does not give is refused, so the digest bound to a plan is the one the files on disk were written from.
type TargetFailureKind ¶ added in v0.2.10
type TargetFailureKind string
TargetFailureKind names why a Ptah command could not open its connection to the target database. It is the closed vocabulary Ptah writes in the kind of a document's error object (stokaro/ptah#5173), and the only part of that object the operator reads.
The message beside it is the sentence Ptah wrote for a person, and it can quote what the database answered: a role, a host, a database name, a row. Nothing here returns it, and the runner and the controller describe a kind in sentences of their own.
const ( // TargetDatabaseUnreachable is a server that never answered: the host did // not resolve, the address refused the connection, or the connection // timed out before the server completed it. TargetDatabaseUnreachable TargetFailureKind = "database_unreachable" // TargetAuthenticationFailed is a server that did not accept the // connection's credentials. TargetAuthenticationFailed TargetFailureKind = "authentication_failed" // TargetDatabaseNotFound is a server that has no database by the name // the connection gives. TargetDatabaseNotFound TargetFailureKind = "database_not_found" // TargetPermissionDenied is a server that accepted the credentials and // refused the role access to the database. TargetPermissionDenied TargetFailureKind = "permission_denied" // TargetTLSFailed is a TLS handshake that did not complete. TargetTLSFailed TargetFailureKind = "tls_failed" )
The vocabulary. Ptah classifies only the failure to open the target connection, from the driver's typed errors, and leaves every other failure without a kind.
func ParseTargetFailureKind ¶ added in v0.2.10
func ParseTargetFailureKind(kind string) (TargetFailureKind, bool)
ParseTargetFailureKind returns the kind a document named, when it is one of the vocabulary. Anything else is no kind: Ptah may add a kind without raising a contract version, and a kind this operator has no sentence for is read as the failure having none, never repeated.
func TargetFailureKinds ¶ added in v0.2.10
func TargetFailureKinds() []TargetFailureKind
TargetFailureKinds returns the vocabulary in a fixed order.
func (TargetFailureKind) Description ¶ added in v0.2.10
func (k TargetFailureKind) Description() string
Description is the runner's sentence for the kind, and empty for a value outside the vocabulary.
type VerificationFinding ¶
type VerifyReport ¶
type VerifyReport struct {
Reference string `json:"reference"`
Digest string `json:"digest"`
Satisfied []string `json:"satisfied"`
Findings []VerificationFinding `json:"findings"`
}
func DecodeVerify ¶
func DecodeVerify(data []byte) (VerifyReport, error)