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.
Index ¶
Constants ¶
This section is empty.
Variables ¶
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 OverByteBudget ¶
func OverByteBudget(prov ir.Provenance, data []byte, limit int) (ir.Diagnostic, bool)
OverByteBudget reports whether a source of data is past the byte budget limit, zero being none, 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.
func SupportedMinor ¶
SupportedMinor returns the normalized major.minor prefix of an OpenAPI version string and whether the compiler supports it (3.0, 3.1, or 3.2).
Types ¶
type Document ¶
type Document struct {
Doc *soa.OpenAPI // parsed, reference-resolved document
Source ir.SourceInfo // format tag, path, content hash
// 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
}
Document is the successful output of the load phase: a parsed, resolved speakeasy document plus 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 Options ¶
type Options struct {
// AllowExternalRefs lets reference resolution reach outside the document —
// off the filesystem or over the network. Off is the default, so the zero
// value performs no I/O.
AllowExternalRefs bool
// Overlay is the OpenAPI Overlay document to apply to the source before the
// model is built, or nil for none. Its bytes are the caller's to read, like
// the source's.
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 source document's size in bytes. Zero is
// unbounded: the compiler's public Limits resolves its defaults and translates
// its own spelling of "unbounded" before projecting onto this, so a budget
// still zero here is one no caller set.
MaxSourceBytes int
// MaxSourceNodes bounds the YAML nodes the source parses to, counted after any
// overlay is applied. Zero is unbounded, as in MaxSourceBytes.
MaxSourceNodes int
// MaxAliasSurplus bounds the nodes YAML aliases may add to the source, and to
// the overlay, beyond their own. Zero is unbounded, as in MaxSourceBytes; the
// ratio refusal scan makes beside it holds either way.
MaxAliasSurplus int
// 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 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 own keys off it to name the format, and the compile it routes to lowers that same tree rather than reading the bytes again. The two happen back to back over one source, so parsing in both is parsing twice.
It is the value this compiler puts in compilers.Source.Parsed, and the only type it reads back out of one. Holding the digest of the bytes it came from is what lets a reader check that: a Parsed reached its Compile beside the Data it describes, or it is ignored and the bytes are read afresh.
The digest is what SourceInfo.Hash records, so the hash a document carries is the hash of the bytes that document was lowered from — not of whatever bytes sat beside the tree at the time. Nothing here pays for that: the hash was already computed on every compile for exactly that field, and comparing it is the same work done once instead of trusted.
The tree is live, not a snapshot: an overlay patches it in place, so a Parsed belongs to one compile (compilers.Source.Parsed says so).
func Decode ¶
Decode parses source bytes into the document the compile lowers and what follows it. It is decode under an exported name, 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 parser's own, unwrapped, since detection quotes it; the compile wraps it as ErrParse.
Source Files