orbitrecord

type Call struct {
	// Action is the canonical action ID whose handler made the call.
	Action string `json:"action"`
	// Variant tells two calls of one action apart: the response format it
	// asked for, what else it asked (an expanded node), or "default" for a
	// route that takes no parameter and so has one answer.
	Variant string `json:"variant"`
	// Output is the Go type the handler returned, repository relative
	// (internal/tools/orbit.StatusOutput). It is what the audit judges
	// against the keys below.
	Output   string   `json:"output"`
	Request  Request  `json:"request"`
	Response Response `json:"response"`
}

type CallID struct {
	Action  string
	Variant string
}

type Document struct {
	SchemaVersion int    `json:"schema_version"`
	Note          string `json:"note"`
	Source        Source `json:"source"`
	// Calls are the recorded calls, sorted by action and variant.
	Calls []Call `json:"calls"`
}

type Key struct {
	Path  string   `json:"path"`
	Kinds []string `json:"kinds"`
	// Verbatim marks a subtree recorded as its root only, because its keys
	// are data rather than a response shape. Nothing below it is recorded.
	Verbatim bool `json:"verbatim,omitempty"`
}

type Request struct {
	Method string `json:"method"`
	// Path is the route below /api/v4.
	Path string `json:"path"`
	// Query are the query parameter names the handler sent, sorted.
	Query []string `json:"query,omitempty"`
	// Body are the top-level names of the JSON body the handler sent, sorted.
	Body []string `json:"body,omitempty"`
}

type Response struct {
	Status int `json:"status"`
	// ContentType is the media type without its parameters.
	ContentType string `json:"content_type"`
	// Keys is every path the body carried, sorted, the body itself first.
	Keys []Key `json:"keys"`
}

type Source struct {
	// Instance is the GitLab the calls were made against.
	Instance string `json:"instance"`
	// OrbitVersion is the Knowledge Graph service version GitLab.com
	// reported in the status call, which is what moves between two
	// recordings far more often than GitLab's own release does.
	OrbitVersion string `json:"orbit_version"`
	// DSLSchema is the $id of the query DSL GitLab.com served beside the
	// answers (orbit.dsl, raw): the language orbit.query's guidance teaches,
	// graph_query/v12 when this field was added. A new $id is a new major
	// version of that language.
	DSLSchema string `json:"dsl_schema"`
	// DSLVersion is the DSL's own version field, which moves with every
	// change GitLab makes to the language (query_dsl in config/versions.yaml
	// of gitlab-org/orbit/knowledge-graph). With [DSLSchema] it is the drift
	// alarm issue 1031 asked for: [Diff] reports either changing, so a
	// recording fails until somebody has read orbit.query's guidance against
	// the new language and committed the record.
	DSLVersion string `json:"dsl_version"`
	// Namespace is the fixture namespace the indexing status and the query
	// were asked about (test/fixtures/orbit, docs/development/orbit-fixtures.md).
	Namespace string `json:"namespace"`
	// RetrievedAt is the day of the recording, YYYY-MM-DD.
	RetrievedAt string `json:"retrieved_at"`
}