pwrequest

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

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

func ParseOpenAPI(document []byte) (Catalog, error)

ParseOpenAPI projects a document into a catalog. Operations come out sorted by path and then method, so --list is stable across runs.

func (*Catalog) ByID

func (c *Catalog) ByID(id string) *Operation

ByID selects the operation whose operationId is id, or nil.

func (*Catalog) MarkProtected

func (c *Catalog) MarkProtected(include, exclude []string) error

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

func (c *Catalog) Match(method, path string) []Matched

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 Location

type Location string

Location is where a handler reads one parameter from.

const (
	InPath   Location = "path"
	InQuery  Location = "query"
	InHeader Location = "header"
	InCookie Location = "cookie"
	InBody   Location = "body"
)

type Matched

type Matched struct {
	Operation *Operation
	Bindings  map[string]string
}

Matched is one operation a path selected, with the segments it filled.

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.

func (*Operation) Template

func (o *Operation) Template() bool

Template reports whether the operation's path carries a segment the caller fills in.

type Pair

type Pair struct {
	Key   string
	Value string
}

Pair is one -d key=value the caller gave.

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.

func Route

func Route(op *Operation, bindings map[string]string, input Input) (Plan, error)

Route applies rule:request-parameter-routing. With an operation, every pair goes where the operation reads it; without one, the pairs mean what they mean to curl. bindings are the path segments a literal path already filled.

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.

func NewReport

func NewReport(result Result, plan Plan, target, origin string) Report

NewReport folds a result and its plan into the report shape. A JSON body is parsed so an agent reads one shape; anything else is a string.

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

func (r Result) HeaderLines() []string

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

type SentRequest struct {
	Method string `json:"method"`
	URL    string `json:"url"`
}

SentRequest is the request as it left, for the report.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL