Documentation
¶
Overview ¶
Package routes lists an app's HTTP routes for orb routes and the Dev Portal (ADR-0082, ADR-0083): what each route is, from the app's OpenAPI document (method, path, operation ID, summary, tags, guards from x-gorbital-guards, whether it is public), joined with where it is in the app's source, found with go/parser (the registration's file and line, the handler and its declaration, the module, and the middleware gorbital.Use and Module.Middleware add).
The document is the truth about what the app serves; the source scan is best effort: a route registered through a helper that builds its path at run time has no source position. Apps on the v0.1 layout have no x-gorbital-guards and no gorbital.Use, so their routes list no guards or middleware, and List.GuardsKnown is false.
Index ¶
Constants ¶
const ( SourceApp = "app" SourceExport = "export" SourceFile = "file" )
Sources of the OpenAPI document.
const ExportTimeout = 3 * time.Minute
ExportTimeout bounds go run ./cmd/api openapi, including a cold build.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Found ¶
type Found struct {
// contains filtered or unexported fields
}
Found are the registrations Scan found.
type List ¶
type List struct {
App string `json:"app"`
// Source is where the OpenAPI document came from: "app" (the running
// app's /openapi.json), "export" (go run ./cmd/api openapi) or "file".
Source string `json:"source"`
// GuardsKnown is false when the document has no x-gorbital-guards, as
// in apps on the v0.1 layout: routes then list no guards.
GuardsKnown bool `json:"guards_known"`
Total int `json:"total"`
Public int `json:"public"`
Routes []Route `json:"routes"`
// Warnings explain what couldn't be found, such as routes without a
// source position.
Warnings []string `json:"warnings"`
// contains filtered or unexported fields
}
List is every route of an app.
func Build ¶
Build returns the routes of the app in dir from its OpenAPI document doc, with positions from the app's source.
func (List) Filter ¶
Filter keeps the routes of module (when not empty), only public ones with publicOnly, and only the routes found in the app's source with appOnly, leaving out those of library modules; it recounts.
func (List) Scopes ¶ added in v0.3.0
Scopes fills in each route's access rule (ADR-0091): modules maps a module's directory to the scope it was generated with, as the app's gorbital.yaml records it, and tenant is what the app calls its tenant. A route whose module records a scope takes it; otherwise a public route is "public" and a route with a scope guard is the tenant's. Nothing is inferred from a plain permission guard, which says who may call a route and not whose records it serves.
type Pos ¶
Pos is a position in the app's source. File is slash-separated and relative to the app directory.
type Route ¶
type Route struct {
// Method is upper case, such as GET.
Method string `json:"method"`
Path string `json:"path"`
OperationID string `json:"operation_id"`
Summary string `json:"summary"`
Tags []string `json:"tags"`
// Module is the module the route was found in (internal/modules/<dir>,
// or the Name of its gorbital.Module); empty without a source position.
Module string `json:"module"`
// Handler is the handler expression, such as h.createBook.
Handler string `json:"handler"`
// Source is where the route is registered: the gorbital.Get (or
// huma.Register) call. Nil when the scan didn't find it.
Source *Pos `json:"source"`
// HandlerSource is the handler's declaration, when found in the same
// package.
HandlerSource *Pos `json:"handler_source"`
// Guards are x-gorbital-guards: "public" or "authenticated", then each
// guard, such as "permission:books.book.read".
Guards []string `json:"guards"`
// Middleware are the expressions of Module.Middleware, then the groups'
// gorbital.Use (outer first), then the route's, in the order they run.
Middleware []string `json:"middleware"`
// Public reports a route that needs no sign-in.
Public bool `json:"public"`
// Scope is the access rule the route serves under (ADR-0091): the
// app's tenant ("organisation", "merchant"), "user", "public" or
// "custom". It is the scope the module was generated with, as
// gorbital.yaml records it, or what the route's own guards say; empty
// when neither knows, as for a library module's routes.
Scope string `json:"scope"`
Deprecated bool `json:"deprecated"`
}
Route is one operation of the app. Its JSON form is public API (orb routes --json, ADR-0054): fields may be added, never removed, renamed or retyped.
Source Files