load

package
v0.0.0-...-38da05c Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package load turns one source document into a parsed, reference-resolved OpenAPI document plus the identity metadata the rest of the compiler stamps into the IR.

It sits on the entry side of the pipeline: nothing below it in the compiler calls back into it, and it knows nothing about lowering. Spec problems leave as ir.Diagnostic values; the Go error return is reserved for I/O and programmer errors.

Much of it answers how the parser library behaves, which docs/parser-library.md records; each declaration that does cites its entry.

Index

Constants

This section is empty.

Variables

View Source
var ErrParse = errors.New("parse source")

ErrParse marks a hard failure to read a source document: bytes that are not YAML, or that fault the parser. It is exported because the compiler above converts it into a diagnostic — a document that will not parse is a problem with the document, and engine.Run turns a Go error from a compiler into one of its own, which the CLI reports on the channel it uses for being invoked wrong.

Functions

func Location

func Location(src compilers.Source) string

Location is where src lies, as the references in it are read against: its Location, or its Path where the caller gave none (compilers.Source).

func OverByteBudget

func OverByteBudget(prov ir.Provenance, data []byte, limit budget.Limit) (ir.Diagnostic, bool)

OverByteBudget reports whether a source of data is past the byte budget limit, and if so the refusal to report at prov. It is exported for detection, which reads a source before Load does and is held to the same budget with the same words, so a source refused at either reads alike.

The refusal names the budget and not the size: a caller may hand on only the first limit+1 bytes of a source past it (compilers.Compiler.SourceLimit), and the size of that is not the document's.

func OverNodeBudget

func OverNodeBudget(prov ir.Provenance, err error) (ir.Diagnostic, bool)

OverNodeBudget reports whether err is the refusal of a source past the node budget, and if so the refusal to report at prov. It is exported for detection, which reads a source before Load does and is held to the same budget with the same words, as OverByteBudget is.

func ReadLimit

func ReadLimit(limit budget.Limit) int

ReadLimit spells the byte budget limit as a read is held to one in compilers.DocumentRequest and compilers.Compiler.SourceLimit: its most, or zero for none. A bound of zero bytes, which no budget option resolves to, would read as none there; what a read returns is held to limit again after it, so a document past it is refused either way.

Types

type Dialects

type Dialects struct {
	// contains filtered or unexported fields
}

Dialects is the rows the schemas a resource root naming its dialect holds (bind.Document.Dialects) are read with: by where each is (At), and by each node of that root's tree (Of), a root it holds governing its own. A schema no such root holds reads its document's rows. Nothing writes it once the load phase returns it, so every context copying it may read it at once.

func (Dialects) At

At returns the rows the schema at p is read with where a root at or above it names its dialect, the innermost such root's, and false where none does.

func (Dialects) Of

func (d Dialects) Of(n *yaml.Node) (oas.SchemaRules, bool)

Of is At for a reading that has the schema's node and not where it is, and is false for a node that reads the source's own rows. A node an alias places at several positions reads at all of them the rows of the root last in pointer order among those whose trees hold it, as readDialects governs them, so a reading asks it of a schema typed.Bindings.SiteOf does not place: one the bindings place nowhere, or, where no schema names a dialect, one writing no list of items, as each node then reads one.

type Document

type Document struct {
	Doc    *soa.OpenAPI  // parsed document, whose references Bindings resolve
	Source ir.SourceInfo // the entry Document.Sources records for this source
	// Location is where the source lies, as its references are read against
	// (see Location), and Places where every file the compile names lies.
	Location string
	Places   *refscope.Places
	// Bindings answers where each $ref lands and where its chain ends, a
	// schema's or a Reference Object's, as the compiler resolved it (bindAll),
	// and the models there.
	Bindings *typed.Bindings
	// Overlay attributes the positions an applied overlay is answerable for. Its
	// zero value — nothing applied — is the answer for a compile with no overlay.
	Overlay overlay.Origin
	// Siblings holds the fields the source writes beside its path items' $refs,
	// modelled and resolved with the document, and MediaTypes the media types
	// it reuses, which the parser does not model.
	Siblings   Siblings
	MediaTypes MediaTypes
	// Others is every document a reference read beside the source, in the
	// order Document.Sources lists them after the source and its overlay, and
	// Dialects the rows each schema resource root naming its dialect governs.
	Others   Others
	Dialects Dialects
	// Rows is what the table says at the minor the source declares, in the
	// dialect its jsonSchemaDialect names, which its Encoding Objects and its
	// schemas where none names its own (Dialects) are read with, from the table
	// the load judged it against: a document of Others read at that minor in
	// that dialect shares them.
	Rows Rows
}

Document is the successful output of the load phase: a parsed speakeasy document, where each of its references lands, and the identity metadata the rest of the compiler needs. A nil *Document with error-severity diagnostics means the source is a spec problem the compiler refuses to lower (e.g. an unsupported version). The normalized "openapi" + major.minor format reaches the IR through Source.Format alone; Document does not separately carry a compilers.SourceFormat, since nothing downstream ever read one.

func Load

func Load(ctx context.Context, srcIndex int, src compilers.Source, opts Options) (*Document, []ir.Diagnostic, error)

Load parses, validates, and resolves one source document. Spec problems become ir.Diagnostic values; the Go error return is reserved for I/O and programmer errors (a hard unmarshal failure). A nil document with diagnostics signals a refusal to lower (unsupported version) without aborting the batch.

type Mapping

type Mapping struct {
	Prefix   string
	Location string
}

Mapping puts the documents under a URI prefix at a location, as the caller writes it (openapi.Location): the URL Prefix + rest is read at Location + rest. Prefix is an absolute URI ending in "/", spelled as resolve.Locate spells a located URL; Location is a directory, a relative one read against the source's, or an http(s) URL ending in "/".

type MediaTypes

type MediaTypes struct {
	// contains filtered or unexported fields
}

MediaTypes holds the reusable Media Type Objects OpenAPI 3.2 adds, which the parser models neither as a section nor as a reference (docs/parser-library.md#media-type-references): each components/mediaTypes entry of the source, and each content entry written as a $ref, modelled as a refscope.ReferencedMediaType. Every pass of this phase meets them as it meets the source's own reference objects (walkSource), so they are indexed where the binder reads them, and their findings are reported alike (GitHub #856). The zero value holds none.

func (MediaTypes) Use

Use returns the model of media, a content entry, when its mapping writes a $ref, read as the model reads a mapping, a `<<` merging one in included, as the binder reads a reference (docs/compilers/openapi.md#references), and whether it does. The model is nil for one whose $ref holds no value, which the rule table reports, and one the parser faulted on, which the load phase reports (mediaFaults).

type Options

type Options struct {
	// Reader reads the documents references name beyond the source, or nil to
	// read none, so the zero value reads nothing: a reference leaving the source
	// is reported unresolved. Every read goes through it; the load phase makes
	// none of its own.
	Reader compilers.DocumentReader
	// Within confines Reader's reads to one directory, or "" to confine them
	// nowhere. It is read only when Reader is set.
	Within string
	// Overlay is the OpenAPI Overlay document to apply to the source before the
	// model is built, or nil for none. With empty Data, the document its Path
	// names is read through Reader (readOverlay).
	Overlay *overlay.Options
	// OverlaySrcIndex is the index the overlay document takes in Document.Sources.
	// It is read only when Overlay is set.
	OverlaySrcIndex int
	// MaxSourceBytes bounds the size in bytes of the source, of the overlay and
	// of each document a reference reads, each checked before anything reads
	// it. The compiler's public Limits resolves its defaults and its spelling of
	// "unbounded" before projecting onto this (budget.FromOption), so the zero
	// Limit, unbounded, is a budget no caller set, as in each budget below.
	MaxSourceBytes budget.Limit
	// MaxSourceNodes bounds the nodes a document holds as it is read: the
	// source, the overlay and each document a reference reads, and the source
	// again as the overlay leaves it. A JSON text is held to it as it is read,
	// and a YAML text once it is parsed (doctree.Read).
	MaxSourceNodes budget.Limit
	// MaxAliasSurplus bounds the nodes YAML aliases may add to the source, and to
	// the overlay, beyond their own. The ratio refusal scan makes beside it holds
	// either way.
	MaxAliasSurplus budget.Limit
	// MaxExternalDocuments bounds the documents external references read in one
	// compile, each counted once however often it is asked for.
	MaxExternalDocuments budget.Limit
	// Mappings is where the caller put the documents under a URI prefix,
	// applied where a document is opened, before any read judges it, and never
	// to an identifier; none is applied by inference.
	Mappings []Mapping
	// contains filtered or unexported fields
}

Options is what Load needs from the compiler's own options. It is a separate type rather than the compiler's, because openapi.Options is public API whose shape is a published contract (its own doc comment says why) and most of it describes lowering, which nothing here can see.

type Other

type Other struct {
	// Index is its position in Document.Sources.
	Index int
	// Label is its location as the source's directory reaches it, which
	// qualifies the IDs of what it declares (ids.In).
	Label string
	// Info is its Document.Sources entry, whose Format names the minor.
	Info ir.SourceInfo
	// Rows is what the table says at the minor in the dialect its
	// jsonSchemaDialect names, which its Encoding Objects and its schemas where
	// none names its own (Dialects) are read with.
	Rows Rows
	// contains filtered or unexported fields
}

Other is a document the compile read beside the source because a reference named it: where Document.Sources records it, how the IDs of what it declares name it, and the minor it is read at, which is the one it declares, or the source's where it declares none the table covers.

type Others

type Others struct {
	// contains filtered or unexported fields
}

Others is every document a reference reached beside the source, in the order Document.Sources lists them, the names a reference reads each by, and where each one's trees write a node (see tree).

func (Others) At

func (o Others) At(index int) (Other, bool)

At returns the document at index in Document.Sources, and false for an index no document of o is at.

func (Others) List

func (o Others) List() []Other

List returns the documents, in the order Document.Sources lists them.

func (Others) Named

func (o Others) Named(name string) (Other, bool)

Named returns the document a reference reads by name, as the binder spells it, and false for one the compile did not read beside the source.

type Parsed

type Parsed struct {
	// contains filtered or unexported fields
}

Parsed is a source's decoded form, produced once and used twice: detection reads the document's keys off it, and the compile it routes to lowers the same tree. It travels in compilers.Source.Parsed.

It holds the digest of the bytes it came from and the node budget it was read within, so a reader can check it describes the Data beside it under its own budget. The digest is what SourceInfo.Hash records.

The tree is live: an overlay patches it in place, so a Parsed belongs to one compile.

func Decode

func Decode(ctx context.Context, data []byte, maxNodes budget.Limit) (*Parsed, error)

Decode reads source bytes into the document the compile lowers and what follows it (doctree.Read), held to maxNodes, for detection to read the same document the compile will (GitHub #481) and to leave the parse behind for it (Parsed). The error is the reader's own, unwrapped, since detection quotes it; the compile wraps it as ErrParse.

func (*Parsed) Hash

func (p *Parsed) Hash() string

Hash is the lowercase hex SHA-256 of the bytes this parse was built from, for SourceInfo.Hash.

func (*Parsed) Root

func (p *Parsed) Root() *yaml.Node

Root is the document the compile lowers — the first in the stream that holds content — for a reader that wants only what the source declares.

type Rows

type Rows struct {
	Schema   oas.SchemaRules
	Encoding oas.EncodingRules
	Security oas.SecurityRules
}

Rows is what the rule table says at the minor a document is read at, in a dialect: how its schemas read (oas.SchemaRules), what its Encoding Objects leave unwritten (oas.EncodingRules), and how its Security Requirement Objects name a scheme (oas.SecurityRules).

type Sibling

type Sibling struct {
	Item    *soa.PathItem
	Pointer jsontext.Pointer
}

Sibling is the fields one use site writes beside its $ref: the Path Item they model, and the pointer of the first position the walk met them at.

type Siblings

type Siblings struct {
	// contains filtered or unexported fields
}

Siblings holds what the source writes beside its path items' $refs, each use site's fields modelled as a Path Item of their own. The library's reference wrapper keeps none of them: its Object is nil on the $ref branch, so the operations, parameters, servers, x-* and undeclared keys beside a $ref reach no model (GitHub #577). Every pass of this phase reads them as part of the source, so their references are indexed where the binder reads them, and their findings are reported, as the document's own are. The zero value holds none.

func (Siblings) Of

Of returns the fields written beside rp's $ref, and false when rp is no reference or writes nothing beside one.

It answers by the mapping the use site is written as, not by rp, so a reference a chain passes finds the fields its own wrapper was built from, and an alias reaching one mapping twice finds one model.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL