runner

Documentation

Overview

Package runner executes parsed requests over HTTP: it builds a net/http request from an httpfile.Request plus values resolved by vars, sends it, and captures the response (status, headers, body, timing).

Requests execute over net/http by default. Requests carrying a @curl--* operator shell out to a curl binary instead, scoping that external dependency to files that actually use it — see the "curl passthrough" entry in docs/PRD.md's decisions log. See docs/build-order.md, Phase 3.

Index

• Variables
• type Option
  • func WithCurlExec(f curlExecFunc) Option
  • func WithHTTPClient(c *http.Client) Option
• type Response
• type Runner
  • func New(opts ...Option) (*Runner, error)
  • func (r *Runner) Send(ctx context.Context, baseDir string, file *httpfile.File, ...) (*Response, error)

Variables

var ErrMissingHost = errors.New("runner: origin-form request has no Host header")

ErrMissingHost indicates a relative (origin-form) request URL had no Host header to resolve a scheme and authority from.

var ErrUnexpectedStatusCode = errors.New("runner: response status code not in @expect-status-code list")

ErrUnexpectedStatusCode indicates a response's status code wasn't in the list an @expect-status-code operator declared.

Types

type Option

type Option func(*Runner)

Option configures a Runner constructed with New.

func WithCurlExec

func WithCurlExec(f curlExecFunc) Option

WithCurlExec overrides how curl is invoked for @curl-* requests. Its main purpose is letting tests exercise the curl argument-building and response-parsing logic without a real curl binary on PATH.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient overrides the default http.Client (which has a cookie jar and a cloned http.DefaultTransport already set). Mainly a test hook; callers wanting a custom transport should generally prefer that.

type Response

type Response struct {
	StatusCode int
	Status     string
	Proto      string
	Header     http.Header
	Body       []byte
	Duration   time.Duration
}

Response captures an executed request's result: status, headers, body, and total wall-clock duration.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner executes parsed requests over HTTP, either via net/http (default) or by shelling out to curl for requests carrying a @curl-* operator. See docs/build-order.md, Phase 3, and the "curl passthrough" entry in docs/PRD.md's decisions log.

A Runner's cookie jar and http.Client are shared across every Send call, so cookies set by one request in a document are sent on later ones automatically — a single cookie jar maintained per document.

func New

func New(opts ...Option) (*Runner, error)

New builds a Runner from opts.

func (*Runner) Send

func (r *Runner) Send(ctx context.Context, baseDir string, file *httpfile.File, req *httpfile.Request, resolver *vars.Resolver, st store.Store) (*Response, error)

Send builds, resolves, and executes req (from file, for its document-wide comments/vars), returning the captured response. file.Comments are merged ahead of req.Comments when parsing operators (@timeout, @connection-timeout, @no-redirect, @curl-*, @expect-status-code), so a block's own operator overrides a file-header default of the same tag; resolver must already reflect both file- and request-scope variables (see vars.MergeVars). baseDir resolves "< ./path" body-from-file references, and req.SaveToFile's path, relative to the .http file's directory.

st resolves {{NAME.response...}} chaining references (see store.Substitute) in the URL, headers, and body, as a second pass after resolver's — and, when req is named (req.Name != ""), Send records its response into st automatically after a successful send, so a later request in the same run can chain off it. st may be nil, meaning no chaining: references of that shape are left verbatim (same as any other unresolved placeholder) and nothing is recorded.

Once the HTTP round-trip itself succeeds, a mismatched @expect-status-code or a save-to-file failure (req.SaveToFile, from a ">>"/">>!" directive) returns the received *Response alongside the error rather than discarding it — the caller can still inspect what was actually received.