Documentation
¶
Index ¶
Constants ¶
const ( ReasonDynamicPattern = "dynamic_pattern" ReasonOpaqueMiddleware = "opaque_middleware" ReasonCrossPackageModel = "cross_package_model" ReasonComplexTypeArg = "complex_type_arg" ReasonOther = "other" )
Reason codes for diagnostics.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CallOperation ¶ added in v0.1.12
type CallOperation string
CallOperation is the static-analysis meaning of a configured function.
const ( CallRequestBind CallOperation = "request_bind" CallResponseWrite CallOperation = "response_write" CallResponseWriteStatus CallOperation = "response_write_status" CallStreamCreate CallOperation = "stream_create" CallRouteRegister CallOperation = "route_register" CallErrorResponse CallOperation = "error_response" // A socket carries two type arguments in opposite directions, so it takes // two operations against one target rather than one carrying both: a // pattern holds a single TypeArgument, and the inbound type is decoded // where the outbound one is encoded. CallSocketReceive CallOperation = "socket_receive" CallSocketSend CallOperation = "socket_send" )
type CallPattern ¶ added in v0.1.12
type CallPattern struct {
Target RouteSymbol
Operation CallOperation
TypeArgument int
TypeValueArgument *int
StatusArgument *int
StatusConstant *int
ErrorName string
PatternArgument int
PatternConstant *string
HandlerArgument int
}
CallPattern maps a resolved function or method to handler-body semantics.
type Config ¶
type Config struct {
Calls []CallPattern
// GeneratedHeaders names header prefixes, beside this module's own, whose
// files discovery must skip. A framework generating routes with tinybind and
// branding the output writes a header nothing here recognizes, and an
// unrecognized generated registry is read as if a user had written it: its
// page registrations become routes, and an HTML page enters an OpenAPI
// document. Naming the prefix here is what prevents that.
//
// Each entry still requires the conventional "DO NOT EDIT." ending.
GeneratedHeaders []string
}
Config provides the authoritative semantic calls explored by the parser.
func DefaultConfig ¶
func DefaultConfig() Config
type Diagnostic ¶
type Diagnostic struct {
File string `json:"file"`
Line int `json:"line"`
Column int `json:"column"`
Reason string `json:"reason"` // dynamic_pattern|opaque_middleware|cross_package_model|complex_type_arg|other
Message string `json:"message"`
OmitsOpenAPI bool `json:"omits_openapi"`
}
Diagnostic is a host-side analysis finding for an incomplete route-like site.
func CheckPackage ¶
func CheckPackage(dir string) ([]Diagnostic, error)
CheckPackage runs analysis and returns diagnostics for undiscoverable route candidates. Non-empty diagnostics mean OpenAPI would omit incomplete candidates.
func CheckPackageWithConfig ¶
func CheckPackageWithConfig(dir string, config Config) ([]Diagnostic, error)
CheckPackageWithConfig runs diagnostics with an authoritative symbol config.
func (Diagnostic) String ¶
func (d Diagnostic) String() string
String formats a diagnostic for CLI output.
type Handler ¶
type Handler struct {
Form string `json:"form"` // named | inline | struct
Name string `json:"name,omitempty"` // function or type name when known
Doc string `json:"doc,omitempty"` // godoc of the handler func or type
}
Handler describes how the leaf handler was expressed in source.
type Position ¶ added in v0.5.18
type Position struct {
File string `json:"file"`
Line int `json:"line"`
Column int `json:"column"`
}
Position is a source location. Resolved routes report their registration site at the same precision Diagnostic reports an unresolved one, so a consumer can name both sides of a pattern collision.
type Result ¶
type Result struct {
Routes []Route `json:"routes"`
Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
}
Result is the structured parse output for a single Go package.
func ParseLoadedPackage ¶ added in v0.1.17
ParseLoadedPackage analyzes a package that the caller already type-checked. Loading dominates the cost of analysis, so a generator run that needs both routes and type plans loads the package once and shares it.
func ParsePackage ¶
ParsePackage analyzes Go sources in dir (same package only) and returns statically discoverable httpbind route IR.
Symbol identity for route registration and httpbind calls is resolved with go/types (host-side only); see rule:go-types-symbol-identity.
func ParsePackageWithConfig ¶
ParsePackageWithConfig analyzes dir with customizable discovery symbols.
type Route ¶
type Route struct {
Method string `json:"method"`
Path string `json:"path"`
// Site is where the registration call was written.
Site Position `json:"site"`
Handler Handler `json:"handler"`
Request string `json:"request,omitempty"`
Response string `json:"response,omitempty"`
Stream string `json:"stream,omitempty"` // element type when response is Stream[T]
SocketIn string `json:"socket_in,omitempty"` // inbound message type of a WebSocket route
SocketOut string `json:"socket_out,omitempty"` // outbound message type of a WebSocket route
Errors []string `json:"errors,omitempty"`
SuccessStatuses []int `json:"success_statuses,omitempty"` // 200 from Write, others from WriteStatus
Wrappers WrapperMeta `json:"wrappers"`
}
Route is one statically discovered net/http route registration.
type RouteSymbol ¶
type WrapperMeta ¶
type WrapperMeta struct {
MaxRequestBodyBytes *int64 `json:"max_request_body_bytes,omitempty"`
Timeout string `json:"timeout,omitempty"`
}
WrapperMeta holds statically known stdlib wrapper metadata.
Source Files