Documentation
¶
Overview ¶
Package pwrequest is what pw request works from: the operation catalog projected out of the application's OpenAPI document, the routing of named parameters against one operation, and the one request that results.
The catalog is data:operation-catalog and the routing is rule:request-parameter-routing. Nothing here reads a project or a configuration file; pw request feeds it the document and the pairs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Catalog ¶
type Catalog struct {
Operations []Operation `json:"operations"`
}
Catalog is the projection of one OpenAPI document.
func ParseOpenAPI ¶
ParseOpenAPI projects a document into a catalog. Operations come out sorted by path and then method, so --list is stable across runs.
func (*Catalog) MarkProtected ¶
MarkProtected sets Protected on every operation whose path the include and exclude patterns of policy:authenticated-path-protection guard.
A template path is matched with its parameters replaced by a placeholder segment, which is what a real request would present once filled: the guard patterns match segments, and a single-segment wildcard matches any one.
func (*Catalog) Match ¶
Match selects the operations whose template matches a literal or template path, the way net/http matches segments. An empty method matches every method, which is how an ambiguity between methods is reported rather than resolved by a guess. The returned bindings are the path parameters a literal path filled.
type Input ¶
type Input struct {
// Method is the explicit -X value, or empty for the curl default: GET, or
// POST once there is data.
Method string
// Path is the literal path the caller named, or empty when an operation
// was selected by id and every segment comes from a pair.
Path string
// Pairs are the -d key=value arguments, in order.
Pairs []Pair
// Raw is a -d argument that was not a pair: a literal body, or @file.
Raw string
RawSet bool
// Forms are the -F fields, key=value or key=@file.
Forms []Pair
// Headers are the -H lines, already split.
Headers []Pair
// Cookies is the -b string, when it was not a file.
Cookies string
// Query moves pairs to the query string under -G, as curl does.
Query bool
// JSON sends pairs as a JSON object with no operation, the curl --json
// spelling.
JSON bool
// Strict makes a pair that names nothing in the operation an error.
Strict bool
}
Input is everything the caller said about one request, before routing.
type Operation ¶
type Operation struct {
ID string `json:"operationId"`
Method string `json:"method"`
Path string `json:"path"`
Summary string `json:"summary,omitempty"`
Parameters []Parameter `json:"parameters,omitempty"`
// ContentType is the first media type the request body declares, which is
// the one routing assembles pairs into. Empty when the operation takes no
// body.
ContentType string `json:"contentType,omitempty"`
// ContentTypes is every media type the body declares, so a -H Content-Type
// naming one of them is honoured with the matching encoding.
ContentTypes []string `json:"contentTypes,omitempty"`
// Body lists the top-level fields of an object body, with their schema
// types, which drive coercion.
Body []Parameter `json:"body,omitempty"`
// Responses is the status codes the operation declares, for the report.
Responses []string `json:"responses,omitempty"`
// Protected is whether policy:authenticated-path-protection guards the
// path in the environment the command read. It is a projection of
// configuration, not of the document.
Protected bool `json:"protected,omitempty"`
// contains filtered or unexported fields
}
Operation is one invocable entry of the catalog.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In Location `json:"in"`
Type string `json:"type,omitempty"`
Required bool `json:"required,omitempty"`
}
Parameter is one named input of an operation.
type Plan ¶
type Plan struct {
Method string
Path string
Query url.Values
Headers map[string]string
Cookies []string
Body []byte
ContentType string
Routing []Routed
// Operation is what the pairs were routed against, or nil under curl
// semantics.
Operation *Operation
// Reason says why no operation was used, when Operation is nil.
Reason string
}
Plan is the one request routing decided on.
type Report ¶
type Report struct {
Status int `json:"status"`
Headers http.Header `json:"headers"`
Body any `json:"body"`
Request SentRequest `json:"request"`
Operation *Operation `json:"operation"`
Reason string `json:"reason,omitempty"`
Routing []Routed `json:"routing"`
// Target says how the origin was found: url, dev, guess.
Target string `json:"target"`
Origin string `json:"origin"`
}
Report is the one JSON object --format json prints.
type Result ¶
type Result struct {
Status int `json:"status"`
Headers http.Header `json:"headers"`
// Body is the response bytes; the JSON report parses it when the response
// says it is JSON.
Body []byte `json:"-"`
// Request is what was sent, so a reader can copy it into curl.
Request SentRequest `json:"request"`
}
Result is one response, as the report prints it.
func Send ¶
func Send(ctx context.Context, client *http.Client, origin string, plan Plan, follow bool, extraHeaders []Pair, cookieHeader string, basic string) (Result, error)
Send issues the planned request against origin with client, without following redirects unless follow is set. A cookie-jar client already holds the caller's cookies; explicit -b cookies join them on this one request.
func (Result) HeaderLines ¶
HeaderLines returns the response headers in a stable order for -i.
type Routed ¶
type Routed struct {
Key string `json:"key"`
In Location `json:"in"`
Value string `json:"value"`
// Note explains a coercion that did not happen or a pair the operation did
// not name.
Note string `json:"note,omitempty"`
}
Routed says where one pair went.
type SentRequest ¶
SentRequest is the request as it left, for the report.