Documentation
¶
Overview ¶
Package orbitrecord is the committed record of what GitLab.com's Orbit routes answer, and the one reader of it.
It exists because the six Orbit actions were outside every oracle the 1:1 audit reads. The live API record (cmd/internal/apilive) is taken from a booted self-managed GitLab, and no self-managed instance serves Orbit; the routes it does list carry no response entity, because ee/lib/api/orbit/data.rb presents hashes that ee/lib/analytics/knowledge_graph/grpc_client.rb builds by hand from gRPC messages. GitLab's generated OpenAPI document gives no 200 schema for them either. A recorded answer is therefore the only oracle that covers every Orbit output type, and this is that recording, reduced to what a comparison needs and nothing a reader could mistake for data.
What it keeps is a key tree per recorded call: every path a response carried, each with the JSON kinds seen there, and never a value. A subtree whose keys are chosen by data rather than by GitLab's code (a JSON Schema document, the rows a query asked for by column) is kept only as its root, marked verbatim, because the server passes it through as it came and its keys are not a response shape. Each call also names the canonical action that made it, the Go type that action returned, and the query and body parameter names the handler sent, which is what lets the audit join a recorded answer to an output type without inferring anything: the join is the handler the generator called.
cmd/gen_orbit_record writes it from a run against GitLab.com, which needs a token and the network and so can never gate; its -check reads the committed file with neither, holds it to Problems and to its own canonical form, and cmd/audit_1to1's R-PATH scope compares the Orbit output types against it. The retrieval date is held to the window github.com/jmrplens/gitlab-mcp-server/v3/cmd/internal/provenance records for every pinned truth.
Index ¶
- Constants
- func Child(parent, key string) string
- func Diff(before, after Document) []string
- func ElementOf(parent string) string
- func Elided(path string) string
- func Encode(doc Document) []byte
- func Parent(path string) string
- func Path(dir string) string
- func Problems(doc Document, now time.Time) []string
- func SortKeys(keys []Key)
- func ValidKey(key string) bool
- func ValidSegment(segment string) bool
- type Call
- type CallID
- type Document
- type Key
- type Request
- type Response
- type Source
Constants ¶
const ( KindObject = "object" KindArray = "array" KindString = "string" KindNumber = "number" KindBoolean = "boolean" KindNull = "null" KindText = "text" )
The kinds a key can be recorded with: the six JSON kinds, and Text for a body that is not JSON at all, which is what the llm answer to a query is.
const DefaultDir = "docs/development"
DefaultDir is where the record lives, beside the other pinned records.
const Element = "[]"
Element is the segment suffix for the elements of an array: the elements of the array at "domains" are at "domains[]", and a bare array body's at "[]".
const FileName = "orbit-responses.json"
FileName is the record's name on disk.
const Instance = "https://gitlab.com"
Instance is the one GitLab that serves Orbit, and so the one a record may be taken from.
const Root = "$"
Root is the path of the response body itself.
const SchemaAction = "orbit.schema"
SchemaAction is the one action a record holds three calls of, one per way its schema is asked for, spelled once here and in the generator that makes the calls.
const SchemaVersion = 1
SchemaVersion is the shape of this record. A reader refuses a version it was not written for rather than guessing at a field that moved.
Variables ¶
This section is empty.
Functions ¶
func Diff ¶
Diff lists what changed between two records' key trees, one line per change, sorted: a call added or dropped, a key added or dropped, a key's kinds changed, and a key that became or stopped being verbatim. Provenance and request names are not compared, since a new day or version is what every recording brings and is not a change to the shape.
func Elided ¶
Elided is a path with its element markers removed, which is how a Go field path reads: "system.components[].name" is "system.components.name", and the elements of a bare array body are the body.
func Encode ¶
Encode renders a record in its canonical form: calls sorted by action and variant, keys by path, kinds and parameter names alphabetically, indented so a re-recording is a readable diff. A committed record that is not in this form was edited by hand or written by another build, which is what the generator's -check holds it to.
func Problems ¶
Problems reports every way a record fails to be a whole, current and value-free recording of the expected calls. It judges the document as decoded; whether the file is in canonical form is the caller's question, since only the caller holds the bytes.
func SortKeys ¶
func SortKeys(keys []Key)
SortKeys orders keys by path, the root before every other path, which is where a reader looks for what the body was.
func ValidSegment ¶
ValidSegment reports whether one segment of a path is one of the shapes segmentPattern allows.
Types ¶
type Call ¶
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"`
}
Call is one handler invocation and what GitLab answered it with.
type CallID ¶
CallID names one recorded call.
func ExpectedCalls ¶
func ExpectedCalls() []CallID
ExpectedCalls is every call a whole record holds, in the order the generator makes them. The status call comes first because it carries the version the record is stamped with.
type Document ¶
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"`
}
Document is the committed record.
func Canonical ¶
Canonical returns a copy of doc with every list in its sorted order. The input is left as it was.
func Decode ¶
Decode reads a record from its bytes, wherever they came from: the file on disk, or the version a commit holds.
A schema version this build was not written for is refused rather than decoded, for the reason SchemaVersion gives.
type Key ¶
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"`
}
Key is one path of a response body and the kinds seen there.
type Request ¶
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"`
}
Request is what the handler sent, by name only.
type Response ¶
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"`
}
Response is what GitLab answered, reduced to its key tree.
type Source ¶
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"`
// 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"`
}
Source is what the record was taken from and when.
Source Files