Documentation
¶
Overview ¶
Package httpclient bounds an API client's requests to its configured origin.
Example ¶
package main
import (
"context"
"errors"
"fmt"
"net/http"
"github.com/Tangerg/scope/core/httpclient"
)
func main() {
ctx := context.Background()
host := &http.Client{}
client, err := httpclient.New(ctx, httpclient.Config{
HTTPClient: host,
BaseURL: "https://api.example/v1",
})
if err != nil {
panic(err)
}
redirect, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example:9443/result", nil)
if err != nil {
panic(err)
}
err = client.CheckRedirect(redirect, nil)
fmt.Println("independent client:", client != host)
fmt.Println("host transport unchanged:", host.Transport == nil)
fmt.Println("other port rejected:", errors.Is(err, httpclient.ErrOriginNotAllowed))
}
Output: independent client: true host transport unchanged: true other port rejected: true
Index ¶
- Constants
- Variables
- func New(_ context.Context, config Config) (*http.Client, error)
- type Config
- type Origin
- type ResponseBodyLimit
- func (r ResponseBodyLimit) Apply(request *http.Request, next func(*http.Request) (*http.Response, error)) (*http.Response, error)
- func (r ResponseBodyLimit) ApplyErrors(request *http.Request, next func(*http.Request) (*http.Response, error)) (*http.Response, error)
- func (r ResponseBodyLimit) ApplyEventStream(request *http.Request, next func(*http.Request) (*http.Response, error)) (*http.Response, error)
- type ResponseError
Examples ¶
Constants ¶
const DefaultMaxJSONResponseBytes = 32 << 20
Variables ¶
var ErrOriginNotAllowed = errors.New("httpclient: request origin is not authorized")
ErrOriginNotAllowed prevents an API credential or request body from reaching an origin other than the one configured by its owner.
Functions ¶
func New ¶
New copies the client value before applying origin restrictions, so SDK initialization and redirect policy changes cannot mutate the host's client. The host retains ownership of the shared transport and cookie jar. Its redirect policy runs before the final destination and authority checks.
Types ¶
type Config ¶
type Config struct {
// A nil Transport, including a typed nil, uses http.DefaultTransport.
HTTPClient *http.Client
BaseURL string
// RejectRedirects binds resource-scoped requests to the original URL, even
// when a same-origin server redirects to a different tenant or resource.
RejectRedirects bool
}
type Origin ¶
type Origin struct {
// contains filtered or unexported fields
}
Origin is an immutable HTTP origin. Only hierarchical URLs are admitted, so Opaque cannot replace the checked authority on the wire. Equality includes the scheme, host, and effective port; its zero value authorizes no requests.
type ResponseBodyLimit ¶ added in v0.61.0
type ResponseBodyLimit int64
ResponseBodyLimit admits bytes as they are read, before a decoder can allocate for an untrusted response. The HTTP client still owns retries and body closure.
func (ResponseBodyLimit) ApplyErrors ¶ added in v0.61.0
func (r ResponseBodyLimit) ApplyErrors(request *http.Request, next func(*http.Request) (*http.Response, error)) (*http.Response, error)
Successful streaming bodies have a per-event contract, so their error envelopes must be bounded without imposing a limit on the entire stream.
func (ResponseBodyLimit) ApplyEventStream ¶ added in v0.61.0
func (r ResponseBodyLimit) ApplyEventStream(request *http.Request, next func(*http.Request) (*http.Response, error)) (*http.Response, error)
For SDKs with LF/CRLF SSE framing, each wire event has its own budget, including comments, BOM, and delimiters. Empty lines reset admission, so long-lived streams retain backpressure without a total byte ceiling. This wrapper preserves bytes; the SDK remains responsible for interpreting them.
type ResponseError ¶ added in v0.60.0
type ResponseError struct {
// contains filtered or unexported fields
}
ResponseError exposes transport evidence without turning a remote response body into public diagnostics. It makes no claim about provider execution.
func NewResponseError ¶ added in v0.60.0
func NewResponseError(statusCode int, header http.Header) *ResponseError
func (*ResponseError) Error ¶ added in v0.60.0
func (r *ResponseError) Error() string
func (*ResponseError) HTTPStatus ¶ added in v0.60.0
func (r *ResponseError) HTTPStatus() int
func (*ResponseError) RequestID ¶ added in v0.60.0
func (r *ResponseError) RequestID() string
Source Files