internal/api/contract.go
internal/api · 373 lines · 12 declarations · source
This file carries the package documentation, rendered on the package page.
Declarations
func Contract
func Contract() string
Contract renders the public description of this surface.
Deterministic: the same surface produces byte-identical output on every run and on every machine, because a generated file that reorders itself makes every diff unreadable and teaches reviewers to skim the one that matters. Operations come out in declaration order and types in field order, both of which are choices a person made and can see.
func writeShape
func writeShape(b *strings.Builder, v any)
writeShape renders a struct's JSON shape: the field names on the wire, and their types.
Names and types rather than a description of meaning. A widened response is as breaking as a narrowed one — a client that unmarshals strictly fails on a field nobody told it about — so what this has to capture is the exact set of names, and it is generated so it cannot fall behind.
type field
type field struct{ name, kind string }
type Field
type Field struct {
Name string `json:"name"`
Kind string `json:"kind"`
}
Field is one wire field as a client sees it: its JSON name and the type wireType names.
type OperationShape
type OperationShape struct {
Name string `json:"name"`
Method string `json:"method"`
Path string `json:"path"`
Success int `json:"success"`
// NoBody marks an operation that takes none, which is different from one taking an object
// with no fields: a client that sends a body to the first is refused.
NoBody bool `json:"no_body,omitempty"`
Request []Field `json:"request,omitempty"`
Response []Field `json:"response"`
}
OperationShape is one operation of the surface with the shapes it takes and returns, the form the freeze is taken in and compared against.
type Frozen
type Frozen struct {
Version string `json:"version"`
Operations []OperationShape `json:"operations"`
// Management is the operator surface, frozen under the same rule: reached with an
// operator credential under its own prefix, and never by a project credential.
Management []OperationShape `json:"management,omitempty"`
Codes []string `json:"codes"`
}
Frozen is the whole surface in the form that is compared across time: what a client of the version can rely on. It carries no prose, because prose is not something a test can hold to.
func Surface
func Surface() Frozen
Surface reports the served surface in the frozen form, from the same operation table and the same reflection the document is rendered from, so the two cannot disagree.
func exported
func exported(fields []field) []Field
func FreezeJSON
func FreezeJSON() ([]byte, error)
FreezeJSON renders the surface as the snapshot a freeze commits: indented and in declaration order, so a diff against an earlier freeze reads as a list of what changed.
func shapeOf
func shapeOf(t reflect.Type) []field
shapeOf walks a struct in field order and reports what a client sees.
Embedded structs are flattened the way encoding/json flattens them, so the document says what is on the wire rather than how the Go types are arranged — a client cannot see the difference and should not be told about it.
func wireType
func wireType(t reflect.Type) string
wireType names a Go type as a client sees it after JSON.
A pointer is "optional" rather than "a pointer", because that is the only thing a pointer means once it has been through encoding/json: the field may be absent or null. Every nested object is expanded inline, so the document has no type names a reader has to look up somewhere else.
func ErrorCodes
func ErrorCodes() []string
ErrorCodes is the refusal vocabulary, for anything that has to enumerate it rather than remember it — the same reason Operations exists.
Sorted, because it is used to answer "is this code one of ours" rather than to render anything; the contract document publishes them in declaration order, which is the order a person chose.