go_http library
go_http - Reliable HTTP client for Dart
Built for control, cancellation and consistency.
Classes
- Auth
-
Pluggable auth strategy (httpx
AuthStrategy, 1A.7). - AuthInterceptor
- Interceptor that applies a (pluggable) Auth strategy.
- BasicAuth
-
Basicauth:Authorization: Basic base64(user:pass). - BatchExecutor
- Runs many Requests concurrently, collecting a Result per request.
- BearerAuth
-
Bearerauth —Authorization: Bearer <token>. - BytesDecoder
- Bytes decoder for response data
- CachedDnsResolver
- Cached DNS resolver wrapping an inner DnsResolver.
- CancellationSource
- Source for creating and managing cancellation tokens
- CancellationToken
- Token for cancelling operations
- ClientConfig
- Low-level transport and HTTP behaviour configuration.
- ConsoleMetricsSink
- Console-based metrics sink for debugging and monitoring.
- ContentDecoder
- A single content-encoding decoder.
- CookieStore
- Abstract interface for cookie storage
- CsvSink
-
CSV sink with CSV-injection sanitization (prefix
=,+,-,@cells with a single quote). Columns are fixed for simplicity. -
Decoder<
T> - Abstract interface for response decoders
- DefaultRedirectPolicy
- Default redirect policy
- DefaultRetryPolicy
- Default retry policy using exponential backoff with equal jitter.
- Dialer
- Pluggable socket dialer.
- DigestAuth
-
Digestauth — RFC 2617 / 7616 (MD5 / SHA-256, qop, cnonce, nonce-count). The first request goes out without auth; the interceptor reads the401WWW-Authenticatechallenge and calls buildHeader. - DnsResolver
- Pluggable DNS resolver.
- EncodedBody
-
Result of encodeRequest: final headers (with
Content-Typeset when applicable) and the transport-ready body. - EventHooks
- Lightweight, multicast request/response callbacks — simpler than the interceptor chain for logging/tracing, and hot-swappable at runtime.
- ExecutorConfig
- High-level execution orchestration configuration.
- FileSecrets
- Load authentication secrets from a JSON file.
- FunctionAuth
- Auth from a plain function — the least-code way to attach a header.
- GoHttpClient
- Main HTTP client class.
- Headers
- Case-insensitive, multi-value HTTP headers collection.
- HostCircuitBreaker
- Per-host circuit breaker that trips after consecutive failures.
- Interceptor
- Base class for HTTP interceptors
- IoTransport
- Stub for IO transport on web platforms
- JsonDecoder
- JSON decoder for response data
- JsonlSink
- Newline-delimited JSON sink.
- LoggingInterceptor
- Interceptor for logging HTTP requests and responses.
- Match
- Composes multiple filters with short-circuit logic.
- MemoryCookieStore
- In-memory cookie store implementation.
- MetricsSink
- Abstract interface for metrics collection
- MockTransport
- A Transport backed by a caller-supplied handler function.
- Multipart
-
Standalone
multipart/form-dataencoder — no external dependencies. - MultipartField
-
A non-file field of a
multipart/form-datarequest. - MultipartFile
-
A file field of a
multipart/form-datarequest. - PortSpec
-
A parsed mapping of scheme → port number, e.g.
{"http": 8080, "https": 443}. - ProgressReporter
- Live batch progress: RPS, done/total, ETA.
- Proxy
- A proxy endpoint.
- ProxyMounts
-
Per-URL-pattern proxy routing. A
nullvalue = explicitly direct. - QueryParams
-
Immutable multi-value query string (httpx
QueryParams). - RateLimiter
- Token-bucket rate limiter.
- RateLimitPolicy
- Convenient rate-limit policy that wraps RateLimiter.
- RedirectPolicy
- Policy for handling HTTP redirects
- RegexFilter
- Matches responses whose body text contains the given regex.
- Request
- HTTP request representation
- RequestOptions
- Request options for customizing HTTP requests
- RequestTrace
- Per-request timing trace populated by the transport.
- ResizeableSemaphore
- A semaphore whose maximum permit count can be changed at runtime.
-
Response<
T> - HTTP response representation.
- ResponseEnricher
- SPI for enriching responses with custom data.
- ResponseEnrichment
- Optional enrichment data attached to a Response.
- ResponseFilter
- Matches a Response for inclusion or routing.
- ResponseTiming
- Per-phase timing for a single HTTP request.
-
Result<
T> -
Outcome of a single request in a batch — success carries a Response,
failure carries an error (never thrown). Mirrors httpx/runner
Result, where one bad target must not abort 100k good ones. - ResultSink
-
Pluggable output SPI — one writer owns its IOSink (single-writer
file I/O, no shared locks).
writeis called per result;closeflushes. - RetryPolicy
- Policy for retrying failed requests
- RetrySignal
- Sentinel returned by Interceptor.onError to signal that the error was resolved (e.g. credentials were refreshed) and the request should be sent again.
- SocketDialer
- Default Dialer using Socket.connect.
- StatusCodeFilter
- Matches responses whose status code falls in a given range.
- SystemDnsResolver
- System DNS resolver using InternetAddress.lookup.
- Timeout
- Structured timeout configuration for the four phases of an HTTP request.
- TlsInfo
- TLS handshake details.
- Transport
- Abstract transport interface for HTTP requests
- Url
- Immutable URL, thin wrapper over Uri with httpx-style ergonomics.
- URLPattern
-
A URL pattern for proxy routing.
all://matches any scheme;*in the host is a wildcard matching any subdomain labels. - UseClientDefault
-
Sentinel used on per-request options to mean "fall back to the client
default" — distinct from an explicit
null, which means "disable". - ValidationError
- A configuration validation issue.
- WebTransport
- Stub for web transport on non-web platforms
Enums
- BreakerState
- Circuit-breaker state for a single host.
- HttpMethod
- HTTP request method
- MatchMode
- Composition mode for Match.
- StatusCode
- Common HTTP status codes with their canonical reason phrases.
Constants
- useClientDefault → const UseClientDefault
-
Shared sentinel instance. Compare with
identical(option, useClientDefault).
Properties
-
contentDecoders
→ Map<
String, ContentDecoder Function()> -
Global registry of ContentDecoder factories.
final
Functions
-
buildSecurityContext(
Object? verify, bool trustEnv) → SecurityContext -
Build a SecurityContext from
verify:false→ no verification,String→ CA file path, SecurityContext → as-is,true/null→ system roots (honoringSSL_CERT_FILEenv whentrustEnv). -
decodeContentEncoding(
List< int> body, String? encoding) → List<int> -
Decodes a response body according to its
Content-Encoding. -
defaultLog(
Object? value) → void -
encodeRequest(
{Object? content, Object? data, Object? json, Headers? headers}) → EncodedBody -
Unified request-body dispatch ladder (httpx
_content.py). -
registerBrotli(
ContentDecoder factory()) → void -
registerZstd(
ContentDecoder factory()) → void -
stderrLog(
Object? value) → void -
Fallback log output to stdout (used on Web where
dart:iois unavailable).
Typedefs
- Logger = void Function(Object? value)
- ProgressCallback = void Function(int received, int total)
- Callback invoked as the response body is received.
- RequestHook = void Function(Request request)
- Fired synchronously right before a request is dispatched.
- ResponseHook = void Function(Response response)
- Fired synchronously after a response is received (and interceptors run).
- ResultCallback = void Function(Result)
- Callback invoked per Result in batch mode.
-
TokenProvider
= Future<
String?> Function() - Callback for getting authentication token.
-
TokenRefresher
= Future<
String?> Function() - Callback for refreshing authentication token.
Exceptions / Errors
- AggregateError
-
Collects multiple errors into one, analogous to Go's
multierr. Useful when closing multiple resources — one error should not mask others. ponytail: simple list wrapper. - CancellationError
- Request cancelled via a CancellationToken.
- CancellationException
- Exception thrown when an operation is cancelled
- CircuitOpenError
- Thrown when a circuit breaker rejects a request (fail-fast).
- ClientShutdownError
-
The client has been shut down (graceful or hard) and does not accept new
requests. Thrown by
sendwhenshutdownordisposewas called. - CloseError
- ConnectError
- ConnectTimeoutError
- CookieConflict
- Multiple cookies matched a lookup and disambiguation is required.
- DecodingError
- Failure while decoding a response body.
- DnsLookupError
- Error thrown when DNS lookup fails.
- FileSecretsError
- Error thrown by FileSecrets methods.
- HttpError
- Base class for all HTTP-related errors.
- HttpStatusError
- HTTP error responses (4xx, 5xx).
- InvalidUrl
- A URL could not be parsed / used.
- LocalProtocolError
- MaxBytesReadError
- Response body exceeded the maximum number of bytes allowed by RequestOptions.maxBytesToRead or RequestOptions.maxBytesToSave.
- NetworkError
- A network-level failure (DNS, refused, dropped connection...).
- PoolTimeoutError
- ProtocolError
- ProxyError
- ReadError
- ReadTimeoutError
- RemoteProtocolError
- RequestError
- Errors scoped to a particular Request — every failure except a plain status response or a client-config problem. Catch this to handle any request-scoped failure at once.
- RequestNotRead
- ResponseNotRead
- StreamClosed
- StreamConsumed
- StreamError
- Error involving the request/response byte stream.
- TimeoutError
- A timeout during one of the request phases.
- TooManyRedirects
- Too many redirects followed.
- TransportError
- Failure in the underlying transport (connect/read/write/protocol/proxy).
- UnsupportedProtocol
- WriteError
- WriteTimeoutError