Documentation
¶
Overview ¶
Package httpreq exposes a single model-callable HTTP-request tool. It uses net/http and enforces host, method, redirect, timeout, and response-size policy at one client boundary.
The host redirect policy can refuse a redirect but cannot extend the allowlist. Cross-origin redirects discard carried headers and refuse body replay. The host allowlist is mandatory; there is no "allow all" mode. A request the client refuses before sending is a definite core/tool.Failure: rejected for host or method policy, failed for invalid input. A redirect the policy refuses stays an ordinary error, because the first request was sent. An interrupted response remains an error. Received status, headers, and body bytes are preserved as core/tool.CallError evidence, not a complete tool result. Body and header values use content.Content; UTF-8 text is readable and binary data, partial characters, and HTTP obs-text remain lossless.
Index ¶
Examples ¶
Constants ¶
Variables ¶
var ( ErrNilClient = errors.New("httpreq: client must not be nil") ErrNilRequest = errors.New("httpreq: request must not be nil") ErrMissingAllowedHosts = errors.New("httpreq: allowed hosts must not be empty; configure an explicit network allowlist") ErrInvalidClientConfig = errors.New("httpreq: client configuration is invalid") ErrInvalidHostPattern = errors.New("httpreq: host pattern is invalid") ErrEmptyURL = errors.New("httpreq: url must not be empty") ErrInvalidURL = errors.New("httpreq: url must be an absolute http(s) URL") ErrInvalidMethod = errors.New("httpreq: method must be GET, HEAD, POST, PUT, PATCH, or DELETE") ErrInvalidRequestTimeout = errors.New("httpreq: timeout_ms must be between 1 and 120000 when set") ErrHostNotAllowed = errors.New("httpreq: host is not allowed by client policy") ErrHostHeaderOverride = errors.New("httpreq: model-supplied Host header overrides are prohibited") ErrBodyNotAllowed = errors.New("httpreq: method does not carry a request body") ErrDuplicateQueryParameter = errors.New("httpreq: query parameter is named by both the URL and Query") ErrDuplicateHeader = errors.New("httpreq: header names one field more than once") ErrInvalidHeaderField = errors.New("httpreq: header name or value is not valid HTTP syntax") ErrMethodNotAllowed = errors.New("httpreq: method is not allowed by client policy") ErrRedirectBody = errors.New("httpreq: a redirect cannot replay a request body to another origin") ErrRedirectLimitReached = errors.New("httpreq: redirect limit reached") )
Functions ¶
This section is empty.
Types ¶
type Allowlist ¶
type Allowlist struct {
// contains filtered or unexported fields
}
Allowlist is a compiled host policy. Exact and leading-wildcard patterns share the same case, trailing-dot, IP, and IDNA normalization as request hosts. The zero value allows nothing.
func NewAllowlist ¶
Example ¶
package main
import (
"fmt"
"github.com/Tangerg/scope/tools/httpreq"
)
func main() {
allowlist, err := httpreq.NewAllowlist([]string{"api.example.com", "*.services.example.com"})
if err != nil {
panic(err)
}
fmt.Println(
allowlist.Allows("API.EXAMPLE.COM"),
allowlist.Allows("search.services.example.com"),
allowlist.Allows("example.net"),
)
}
Output: true true false
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client executes requests through an immutable network and resource policy.
func NewClient ¶
func NewClient(config ClientConfig) (*Client, error)
type ClientConfig ¶
type ClientConfig struct {
// AllowedHosts accepts exact hosts and one leading wildcard, such as
// "api.example.com" or "*.example.com". A wildcard does not match its root.
AllowedHosts []string
// AllowedMethods defaults to GET and HEAD. Comparison is case-insensitive.
AllowedMethods []Method
// DefaultHeaders are added unless [Request.Headers] overrides them.
DefaultHeaders map[string]string
// MaxResponseBytes selects [DefaultMaxResponseBytes] at zero.
MaxResponseBytes int64
// DefaultTimeout selects [DefaultTimeout] at zero.
DefaultTimeout time.Duration
// HTTPClient supplies caller-owned transport, cookie jar, proxy, and TLS
// settings. NewClient clones the value before installing redirect policy.
HTTPClient *http.Client
}
ClientConfig requires AllowedHosts; there is no default network access.
func (ClientConfig) Validate ¶
func (c ClientConfig) Validate() error
type Method ¶
type Method string
const ( MethodGET Method = http.MethodGet MethodHEAD Method = http.MethodHead MethodPOST Method = http.MethodPost MethodPUT Method = http.MethodPut MethodPATCH Method = http.MethodPatch MethodDELETE Method = http.MethodDelete )
func (Method) JSONSchemaEnum ¶ added in v0.54.0
type Request ¶
type Request struct {
URL string `json:"url" jsonschema:"minLength=1" jsonschema_description:"Absolute http(s) URL. Host must match the configured allowlist."`
Method Method `` /* 155-byte string literal not displayed */
Headers map[string]string `` /* 197-byte string literal not displayed */
Query map[string]string `` /* 146-byte string literal not displayed */
Body string `` /* 197-byte string literal not displayed */
TimeoutMS int `` /* 157-byte string literal not displayed */
}
func (Request) JSONSchemaConstraints ¶ added in v0.54.0
func (Request) JSONSchemaConstraints() jsonschema.Constraints
type Response ¶
type Response struct {
Status int `json:"status"`
Headers map[string][]content.Content `json:"headers,omitempty"`
Body content.Content `json:"body"`
Truncated bool `json:"truncated,omitzero"`
// Duration includes transport execution, body reading, and body closure.
Duration string `json:"duration"`
}
Response is the model-facing result. Body and header values preserve bytes; UTF-8 remains readable text and other bytes use explicit base64 on the wire. Alongside an error from Client.Do it contains incomplete observations only; Truncated reports the configured size cap, not successful body completion.
Source Files