Documentation
¶
Overview ¶
Package service holds the context the service lowerings read: the operation walk, the security schemes and requirements, the servers and the document's own metadata.
It is the schema lowering's context (lowering.Ctx) and what only those lowerings read beside it: the parsed document, the source's index, the fields the load phase modelled beside path items' $refs and the media types it resolved, how operations group, which media types stream or are binary, and the budget a $ref's copies are charged against. The schema walk reads none of it, so it reaches lowering and never this package.
Index ¶
- Constants
- func Beside[T, S any, R chainable[T, S]](c Ctx, ref R, usePtr jsontext.Pointer, folds bool) (ir.Unmodeled, []ir.Diagnostic)
- func ChargeExpansion(c Ctx, raw int)
- func ChargeExpansionAt(c Ctx, at jsontext.Pointer, node *yaml.Node)
- func DefaultBinaryMediaTypes() []string
- func DefaultStreamingMediaTypes() []string
- func EncodingRules(c Ctx) oas.EncodingRules
- func ExpansionCrossed(c Ctx) bool
- func HoldsOneDocument(mediaType string) bool
- func NormalizeMediaType(mediaType string) string
- func OtherIDs(c Ctx) []ids.Document
- type BinaryInference
- type Ctx
- type ExtensionLists
- type GroupingExtension
- type GroupingStrategy
- type Policy
- type Repeat
- type StreamingInference
Constants ¶
const BinaryInferenceHeuristic ir.Inferred = "binary-inference"
BinaryInferenceHeuristic is the name FileInfo.Inferred and PartEncoding.Inferred carry on a body or part read as a file because its media type is binary, rather than because its schema or application/octet-stream says so. It is a constant for the reason StreamingInferenceHeuristic is.
const GroupExtensionHeuristic ir.Inferred = "group-extension"
GroupExtensionHeuristic is the name Provenance.Inferred carries on an operation GroupByExtension filed by the path its extension states. OpenAPI gives an x-* key no meaning, so reading one as a group is a convention's reading, not the document's.
const GroupPathPrefixHeuristic ir.Inferred = "group-path-prefix"
GroupPathPrefixHeuristic is the name Provenance.Inferred carries on an operation GroupByPathPrefix filed. It is a constant for the reason StreamingInferenceHeuristic is: an auditor greps for it.
const MaxGroupPathDepth = 16
MaxGroupPathDepth bounds the segments of a group path, so the groups it nests: 16, a 2.3x margin over the 7 the golden spec's deepest writes (spec @e411be7e). Each group's ID spells the path to it, so the IDs of a path's groups weigh half its depth times its length, and the bound is that factor.
const StreamingInferenceHeuristic ir.Inferred = "streaming-inference"
StreamingInferenceHeuristic is the name Provenance.Inferred carries on an operation whose streaming was read out of a media type rather than declared. It is a constant because the marker is what an auditor greps for, and a spelling written at the producing site and again at a reading test can drift.
Variables ¶
This section is empty.
Functions ¶
func Beside ¶
func Beside[T, S any, R chainable[T, S]](c Ctx, ref R, usePtr jsontext.Pointer, folds bool) (ir.Unmodeled, []ir.Diagnostic)
Beside returns what the Reference Objects of ref's chain write beside their $ref that the use does not read, keyed "openapi:reference/<i>/<key>": i is 0 for the use written at usePtr, then counts the aliases the chain passes, nearest first. folds says the use folds summary and description into docs.
func ChargeExpansion ¶
ChargeExpansion charges the expansion raw more bytes that a lowering copies as raw values with no $ref naming them: what a path item keeps onto each of its additionalOperations entries, and the servers it names on them.
func ChargeExpansionAt ¶
ChargeExpansionAt charges the expansion one more copy of the declaration at node, written at at in c's document, that a lowering makes with no $ref naming it: an inline parameter of a path item, at each additionalOperations entry that takes it (GitHub #1428). It weighs the copy as Declared weighs a $ref's. Whether the copies have crossed the budget is ExpansionCrossed's to say.
func DefaultBinaryMediaTypes ¶
func DefaultBinaryMediaTypes() []string
DefaultBinaryMediaTypes is the list the policy uses when the caller states none. It is a default and not a standard: it names registered binary types, and top-level types whose members are binary but for rare text ones such as an ASCII image/vnd.dxf. A caller who reads them otherwise names its own list.
func DefaultStreamingMediaTypes ¶
func DefaultStreamingMediaTypes() []string
DefaultStreamingMediaTypes is the list the policy uses when the caller states none. It is a default and not a standard: `text/event-stream`, `application/json-seq` (RFC 7464) and the `+json-seq` suffix (RFC 8091) are registered, and the two JSON-lines spellings are conventions that happen to be what generators in this space already look for. A document using another spelling is not wrong — it names its own list.
func EncodingRules ¶
func EncodingRules(c Ctx) oas.EncodingRules
EncodingRules returns the Encoding Object's rows an encoding c lowers is read with, those of the document whose content c reads, as c.SchemaRules returns the Schema Object's: what a part takes where its encoding leaves a field unwritten.
func ExpansionCrossed ¶
ExpansionCrossed reports whether the copies made so far weigh past the budget, for a lowering to ask before it makes one more: the document is then refused (Ctx.ExpansionRefusal), so nothing more need copy.
func HoldsOneDocument ¶
HoldsOneDocument reports whether mediaType names a syntax whose body is one document, JSON's or XML's, by name or structured suffix (RFC 6839, RFC 7303). It answers only for those two: which other media types repeat a structure is not a closed set, as vendor types and multipart/mixed show.
func NormalizeMediaType ¶
NormalizeMediaType reduces a media type to the form a classification compares: lowercased, parameters dropped, surrounding space trimmed. RFC 6838 §4.2 makes the type and subtype case-insensitive, and a parameter states how a body is encoded rather than naming another type.
Every classification reads this one rule, so a policy and a lowering cannot drift apart. The IR never records the result: a caller normalizes a copy, and the IR keeps the spelling the document wrote.
Types ¶
type BinaryInference ¶
type BinaryInference struct {
// MediaTypes replaces the default list rather than extending it. Empty
// means the default.
//
// Entries are matched as StreamingInference's are, case-insensitively and
// without parameters, an entry starting with `+` naming a structured
// suffix. An entry `type/*` matches each media type of that type whose
// subtype has no structured suffix, since a suffix names the syntax the
// body is written in: `image/*` matches `image/png`, not `image/svg+xml`.
MediaTypes []string `json:"mediaTypes,omitempty"`
// Disabled turns the inference off: a body or part is then a file only
// where its schema or application/octet-stream declares one.
Disabled bool `json:"disabled,omitzero"`
}
BinaryInference is the binary media-type policy: which media types mean "this body is a file" where its schema says no more than that it is a string.
It is a policy rather than a table in the lowering because the reading is a guess (architecture principle 6). OpenAPI says any binary media type marks binary content, but no registry says which types are binary, so a list is a judgment a caller may not share. application/octet-stream is not on it: RFC 2046 defines that type as arbitrary octets, so the lowering reads it as declared, whatever this says.
type Ctx ¶
type Ctx struct {
lowering.Ctx
// Doc is the parsed, reference-resolved source document. Lowering reads it
// and never writes through it.
Doc *soa.OpenAPI
// SrcIndex is the source's index within the compile.
SrcIndex int
// Grouping selects how operations are grouped into OperationGroups, and
// GroupingExtension is what GroupByExtension reads. Both arrive as the
// caller wrote them: the compiler's Options fills an unset one in, and a
// strategy the operation lowering does not recognize groups by tags, which
// is what makes the unnormalized zero value harmless.
Grouping GroupingStrategy
GroupingExtension GroupingExtension
// contains filtered or unexported fields
}
Ctx is everything a service lowering may read: the schema lowering's context, which it embeds, and what only the service lowerings read beside it. New builds one; the zero Ctx is invalid.
It is a value, as lowering.Ctx is, and its maps stay unexported for the same reason: a copy shares a map, which an exported one would let a callee write through. Of what copies share, only expansion changes an answer: past its budget, no $ref resolves.
func Declared ¶
func Declared[T, S any, R chainable[T, S], P interface { *T GetRootNode() *yaml.Node }](c Ctx, ref R, usePtr jsontext.Pointer) (*T, Ctx, jsontext.Pointer)
Declared returns what the entry ref, written at usePtr in c's document, resolves to, with the context its declaration is lowered in and the pointer declaring it there: the position the chain of its Reference Object ends on, in whichever document (InDocument), as the bindings' table places it, or, for an inline entry, c and usePtr themselves. Past Policy.MaxReferenceExpansion a $ref resolves to nothing (Ctx.ExpansionRefusal).
func InDocument ¶
InDocument returns c for lowering what document id of the bindings' table declares, at that document's own coordinates (lowering.InDocument), and false, c unchanged, for a document the compile did not read beside the source.
func New ¶
New derives the context for doc, at srcIndex, under p. doc must not be nil: the compiler lowers only a document its load returned. The streaming and binary policies are normalized here so readers cannot disagree about a media type.
It is the one place the load phase's document and the schema lowering's values meet: what lowering.New reads of the load is built here.
func (Ctx) ExpansionRefusal ¶
func (c Ctx) ExpansionRefusal() (ir.Diagnostic, bool)
ExpansionRefusal returns the error refusing the document when the copies its $refs and path items made weighed past Policy.MaxReferenceExpansion, and false when they did not. It is meant to be asked once every lowering has returned: a copy past the budget lowers nothing, so a crossing after the question goes unreported.
func (Ctx) MediaTypeBinary ¶
MediaTypeBinary reports whether the policy classifies mediaType as binary. It is a predicate rather than a getter for the reason MediaTypeStreams is.
func (Ctx) MediaTypeStreams ¶
MediaTypeStreams reports whether the policy classifies mediaType as a stream of frames. It is a predicate rather than a getter because handing back the set would make it writable through a copy of the context.
func (Ctx) MediaTypeUse ¶
MediaTypeUse returns the model the load phase built of media, a content entry, and whether media is written as a $ref (load.MediaTypes.Use).
type ExtensionLists ¶
type ExtensionLists string
ExtensionLists is what a list value of a grouping extension means. A string is one path either way, its segments separated by dots.
const ( // ListsAreSegments reads a list as one path, each entry adding its // segments, as x-fern-sdk-group-name writes one. ListsAreSegments ExtensionLists = "segments" // ListsAreGroups reads a list as several paths, each a group the operation // belongs to, as x-speakeasy-group writes them. The operation is filed under // the first, and a group is minted for each of the rest, for the remount a // consumer reads from the extension, which stays kept. ListsAreGroups ExtensionLists = "groups" )
The readings of a list value.
type GroupingExtension ¶
type GroupingExtension struct {
// Key is the extension read, x- prefix included. Empty reads none.
Key string `json:"key,omitempty"`
// Lists is what a list value means under Key. Any value but ListsAreGroups
// reads one as ListsAreSegments; the compiler's options refuse a Key that
// names none.
Lists ExtensionLists `json:"lists,omitempty"`
// Aliases is the extension listing an operation's aliases, each an object
// stating a further group path under Key (AliasPaths). A group is minted for
// each, for a remount to name, and no operation is filed in it, so no
// GroupExtensionHeuristic marks it: a group has no provenance. Empty reads
// none. An embedded-policy mapping reading the extension into AlsoMount is
// its second reader, and must name this key for its mounts to name these
// groups.
Aliases string `json:"aliases,omitempty"`
// Fallback groups an operation Key states no path for: GroupByTags or
// GroupByPathPrefix, any other value, empty included, grouping by tags.
Fallback GroupingStrategy `json:"fallback,omitempty"`
}
GroupingExtension is what GroupByExtension reads: which extension states an operation's group path, what a list there means, which extension lists the further paths it is exposed under, and how an operation stating none is grouped. Conventions disagree on a list, so its reading is the key's and is never assumed from another key's.
func DefaultGroupingExtension ¶
func DefaultGroupingExtension() GroupingExtension
DefaultGroupingExtension returns the extension GroupByExtension reads where the caller names none: x-fern-sdk-group-name, whose list is one path, beside x-forge-aliases, whose entries restate it for each alias. It is a default and not a standard, as promotion.DefaultExtensionPromotions is.
func (GroupingExtension) AliasPaths ¶
func (g GroupingExtension) AliasPaths(raw ir.RawValue) ([][]string, bool)
AliasPaths reads the group paths raw, the Aliases extension's value as Unmodeled keeps it, names: a list of objects, each stating paths under Key as Key's own value does (Paths). An object without Key, an empty list and null state none. It returns false for a misfit: any other value, an entry that is no object, or one whose paths are a misfit, the list judged whole as Paths judges one.
func (GroupingExtension) Keys ¶
func (g GroupingExtension) Keys(strategy GroupingStrategy) []string
Keys returns the extensions grouping reads under strategy: Key and Aliases, each where it names one, under GroupByExtension, and none under any other strategy. It is the one list of them, so the lowering filing operations and the audit of an owned prefix (promotion.UnreadExtensions) read the same keys.
func (GroupingExtension) Paths ¶
func (g GroupingExtension) Paths(raw ir.RawValue) ([][]string, bool)
Paths reads the group paths raw states, an extension's value as Unmodeled keeps it, each outermost segment first: one under ListsAreSegments, each entry's under ListsAreGroups, the first being the one the operation is filed under. Empty text, an empty list and null state none. It returns false for a misfit: any other value, or a path holding an empty segment, which no group is named by, or one deeper than MaxGroupPathDepth. A list is a misfit if any entry is, since the value is the document's whole statement.
type GroupingStrategy ¶
type GroupingStrategy string
GroupingStrategy selects how operations are grouped into OperationGroups. It is the injectable-policy seam (architecture principle 6): grouping is inferred policy, not source semantics, and can be switched or disabled.
The vocabulary is declared here, below both walks, and re-exported by the compiler's public options rather than restated there. One declaration is what keeps the two spellings from drifting apart: a strategy the public type names and the lowering does not recognize would silently fall through to the default, and nothing would report it.
const ( // GroupByTags groups operations by their first OpenAPI tag (default). GroupByTags GroupingStrategy = "tags" // GroupByPathPrefix groups operations by the first path segment. GroupByPathPrefix GroupingStrategy = "path-prefix" // GroupByExtension groups operations by the group path a vendor extension // states, nesting a group for each segment, and an operation stating none by // GroupingExtension.Fallback. GroupByExtension GroupingStrategy = "extension" )
Grouping strategies.
type Policy ¶
type Policy struct {
Schema lowering.Policy
Grouping GroupingStrategy
GroupingExtension GroupingExtension
MaxReferenceExpansion budget.Limit
StreamingInference StreamingInference
BinaryInference BinaryInference
}
Policy is the caller's choice of how a source is lowered, as the compiler's Options resolve it: the schema lowering's, and what only the service lowerings honour.
type Repeat ¶
type Repeat struct{ At, First int }
Repeat is an entry of a list written again: the entry at At repeats the one at First, its first occurrence.
func FirstOccurrences ¶
FirstOccurrences returns entries with each kept at its first occurrence, in the order written, and every repeat with the index it repeats, in order. Entries compare as the text written. A list repeating nothing is returned as it is, with no repeat, and one of at most pairwiseEntries allocates nothing.
type StreamingInference ¶
type StreamingInference struct {
// Disabled turns the inference off. Off means off: an operation then carries
// the streaming fields a 3.2 itemSchema declares and nothing else, which is
// what a caller who does not want guesses in their IR asked for.
Disabled bool `json:"disabled,omitzero"`
// MediaTypes replaces the default list rather than extending it, so a caller
// who states a list gets exactly that list. Empty means the default.
//
// Entries are matched against the media type alone: the comparison is
// case-insensitive and ignores parameters, because `text/event-stream` and
// `text/event-stream; charset=utf-8` name one type. An entry starting with
// `+` names a structured suffix, and matches every media type ending in it.
MediaTypes []string `json:"mediaTypes,omitempty"`
}
StreamingInference is the media-type streaming policy: which media types mean "this body is a sequence of frames" in a document that declares nothing saying so.
It is a policy rather than a table in the lowering because the reading is a guess (architecture principle 6). OpenAPI below 3.2 has no keyword for a sequential body, so an SSE or NDJSON API says what it does only by naming a media type, which is a content encoding, not a promise about framing. The vocabulary is declared here, below both walks, and re-exported by the compiler's public options, as GroupingStrategy is.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package servicetest builds the context the compiler's tests lower under, over a document the load phase read, as the compiler builds its own.
|
Package servicetest builds the context the compiler's tests lower under, over a document the load phase read, as the compiler builds its own. |