Documentation
¶
Overview ¶
Package contractcheck checks an application's generated contract artifacts (the resource *.gen.go, the OpenAPI document, the TypeScript client) after an upgrade, with the existing drift gates' own checks: gombit upgrade contract (UPGRADE-8).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Artifact ¶
type Artifact string
Artifact names a kind of generated contract artifact.
const ( // Resources are the generator-owned resource files (*.gen.go) // gombit generate derives from the app's models. Resources Artifact = "resources" // OpenAPI is the committed OpenAPI document. OpenAPI Artifact = "openapi" // Client is the generated TypeScript client. Client Artifact = "client" )
type Options ¶
type Options struct {
// SpecPath is the committed OpenAPI document and OutDir the generated
// client directory, relative to the application directory: by default
// gombit new's (client.DefaultSpecPath, client.DefaultOutDir).
SpecPath string
OutDir string
// LiveSpec is the running application's OpenAPI document (gombit
// upgrade contract --url fetches it). Without it the committed
// document cannot be checked, since it is derived from the running app,
// and the client is checked against the committed one.
LiveSpec []byte
// Write regenerates stale artifacts with the normal generation:
// gombit generate for the resources, gombit client generate (from the
// live document, which is written too, or the committed one) for the
// client. Only generator-owned files are written: never a resource's
// hooks file, nor a file of the client directory gombit did not
// generate.
Write bool
// NPXBinary runs openapi-typescript, as gombit client generate does.
// Default: npx.
NPXBinary string
Stderr io.Writer
}
Options configures Check.
type Report ¶
type Report struct {
Checks []Result `json:"checks"`
}
Report is the state of an application's generated contract artifacts.
func Check ¶
Check reports whether the generated contract artifacts of the application in workDir are what generation produces now, which an upgrade can change: the framework renders the resource files and the client, and the running app derives the OpenAPI document. Each check is the same one the existing drift gates make (gombit generate --check, gombit client check), so it agrees with them:
- the resource files are rendered as gombit generate --check renders them, by a loader run inside the application's module, so with the framework version its go.mod requires; they are unchecked when the loader fails (the models do not compile);
- the OpenAPI document is compared with LiveSpec (semantically), and is unchecked without it;
- the client is regenerated, as gombit client generate does, from LiveSpec or else the committed document, and compared byte for byte; it is unchecked when there is no document, or no npx to run openapi-typescript.
The artifacts depend on each other: the running app is built from the resource files, and serves the document the client is generated from. So while the resources are not current (stale, just regenerated, or unchecked), the checks against LiveSpec are unchecked: the app must be rebuilt first.
With Write it regenerates what is stale, through the same generation, and reports what it wrote; it never writes the document or the client from an app built before the resources were. A failed write is an error, naming the files written before it.
type Result ¶
type Result struct {
Artifact Artifact `json:"artifact"`
Status Status `json:"status"`
// Files are the files the status is about, relative to the
// application directory: the stale ones, or (Written) the ones
// regenerated.
Files []string `json:"files"`
// Reason says why it is unchecked; for a stale one, what else there is
// to know: why the document is stale, or why a write was refused.
Reason string `json:"reason,omitempty"`
// Regenerate is the command that regenerates them.
Regenerate string `json:"regenerate"`
}
Result is one kind of artifact, checked.
type Status ¶
type Status string
Status is what a check found.
const ( // Current: the committed artifacts are what generation // produces. Current Status = "current" // Stale: some differ (Files lists them). Stale Status = "stale" // Written: they were stale, and regenerated (Write). Written Status = "written" // Absent: the application has none of them. Absent Status = "absent" // Unchecked: they could not be checked (Reason says why). A gate // that must not pass on what it could not see fails on it too // (Report.Unchecked; gombit upgrade contract --strict). Unchecked Status = "unchecked" )
Source Files