Documentation
¶
Overview ¶
Package throws resolves method error declarations (ADR-0013) from the descriptor set of a CodeGeneratorRequest.
It is the single implementation of the marker-claiming rules shared by protoc-gen-openapi, which turns declarations into exact error responses, and protoc-gen-go-middleware, which compiles them into runtime assertions (ADR-0014). One resolver means one set of failure semantics: a declaration that is invalid for one generator is invalid for both.
Plugins compile against the published Forge API module, while the marker and the application's marked extension fields arrive as descriptors, so everything is resolved dynamically: options are re-unmarshaled against a type registry built from the request's own descriptors. Extensions the registry cannot resolve stay unknown and are ignored; everything it can resolve is visited, so a marked declaration is never silently dropped.
Index ¶
Constants ¶
const (
MarkerName = "sylphy.errors.v1.throws"
)
The extension full names the analyzer resolves dynamically. The plugins compile against the published Forge API module, so these are matched by name against the descriptors the build supplies rather than by generated extension types: the descriptors in the CodeGeneratorRequest are the authority on what the application declared.
Variables ¶
var StatusOf = forgehttp.StatusOf
StatusOf projects an error Kind onto an HTTP status code. It is the same projection the Forge runtime applies when it encodes an error, taken directly from the published runtime so no generator can drift from the wire behavior. It is a variable only so tests can prove the 4xx/5xx guard fires on a projection that leaves the error range.
Functions ¶
func ProjectDeclaredStatus ¶
ProjectDeclaredStatus projects a Kind wire name onto the HTTP status the runtime would answer with, and rejects a projection outside the error range: a declared error that documents a success status is a contradiction.
Types ¶
type Analyzer ¶
type Analyzer struct {
// contains filtered or unexported fields
}
Analyzer resolves method error declarations from the descriptor set of a CodeGeneratorRequest.
func NewAnalyzer ¶
func NewAnalyzer(request *pluginpb.CodeGeneratorRequest) (*Analyzer, error)
NewAnalyzer builds an analyzer over the request's own descriptors.
func (*Analyzer) Declarations ¶
Declarations collects the error identities declared through marked extensions on one options message.
func (*Analyzer) MethodDeclarations ¶
func (a *Analyzer) MethodDeclarations(serviceOptions, methodOptions proto.Message) ([]Identity, error)
MethodDeclarations resolves the effective declared identity set of one method: the union of its service's and its own throws declarations, with the duplicate-declaration guard applied across the union.
func (*Analyzer) Resolved ¶
Resolved re-unmarshals an options message against the request's descriptor pool so extension fields that arrived as unknown bytes become inspectable.
func (*Analyzer) ScanMarkers ¶
ScanMarkers walks every field and extension descriptor in the pool and fails on any throws marker attached to an illegal host. Running the scan over the whole pool, not just the fields a method happens to use, turns a misplaced marker into a build failure instead of a silently dead annotation.
type Identity ¶
type Identity struct {
Kind string // wire name of the Kind, e.g. "NOT_FOUND"
Domain string // proto package of the declaring enum
Reason string // enum value name
Status int
// DedupeKey identifies the declaration for duplicate detection. It is the
// enum value full name for declared reasons and empty for identities a
// generator merges in itself, such as the framework validation identity.
DedupeKey string
}
Identity is one declared error identity a method can produce, joined with the HTTP status its Kind projects to.
Source Files