API Reference

HTTPC provides 29 request-option functions, 5 configuration presets, 7 built-in middleware, and complete download support.

Core Architecture

HTTPC uses a two-layer design: the Layer 1 method API is a thin wrapper, while the real request-processing engine is the Layer 2 Handler pipeline.

HTTPC two-layer architecture
├── Layer 1  Method API (thin wrapper)
│     Package functions httpc.Get/Post/... + Client methods + request options → Result
│
└── Layer 2  Handler pipeline (request-processing engine)
      MiddlewareFunc(Handler) onion chain
      → assembles clientImpl.middlewareChain
      → executes (each request = assemble and run a Handler chain)

Module Navigation

Core

Module	Description
Package Functions & Client Methods	Package-level functions like Get/Post/Put/Patch/Delete, client methods, and helper functions
Configuration	Config struct, 5 configuration presets, validation functions, and cookie security
Interfaces	Core interfaces including Client, Doer, DomainClienter, and RetryPolicy
Result	Result, RequestInfo, ResponseInfo, RequestMeta types and all methods
Handler Pipeline	Handler pipeline, MiddlewareFunc onion chain, Chain combinator, and mutator contracts
Mutators	Read/write methods and type assertions of RequestMutator/ResponseMutator

Request and Response

Module	Description
Request Options	29 WithXxx request-option functions (headers, body, authentication, cookies, callbacks, etc.)
Built-in Middleware	Chain composition, 7 built-in middleware factories, and audit event types
Error Types	ClientError, 12 ErrorType enums, and 17 error variables

Advanced Features

Module	Description
Domain Client	DomainClient creation, HTTP methods, download methods, and URL concatenation rules
Session Management	SessionManager cookie/header management and security validation
File Download	Download functions, DownloadConfig, resumable downloads, and security protection
Constants and Types	BodyKind enum, FormData/FileData, and audit context keys

API Map

A complete index grouped by symbol type, mapping one-to-one to the exported surface of the github.com/cybergodev/httpc package — click any entry to jump to its detail page.

Client and Package-Level Functions

Symbol	Description
New / NewDefault	Create a client (custom / default configuration)
Get / Post / Put / Patch / Delete / Head / Options / Request	Package-level HTTP methods (share the internal default client)
Download	Unified file-download entry (same name and signature on the package function / Client / DomainClient)
SetDefaultClient / CloseDefaultClient	Replace and close the default client
NewDomain / NewDomainDefault	Domain-scoped clients
SetSecurityWarnOutput	Redirect security-warning output
FormatBytes / FormatSpeed	Format byte counts / speeds

Request Options (29)

Group	Options
Headers (3)	WithHeader, WithHeaderMap, WithUserAgent
Authentication (2)	WithBasicAuth, WithBearerToken
Body (7)	WithJSON, WithXML, WithForm, WithFormData, WithFile, WithBinary, WithBody
Query parameters (2)	WithQuery, WithQueryMap
Cookies (4)	WithCookies, WithCookieMap, WithCookieString, WithSecureCookie
Request control (9)	WithContext, WithTimeout, WithNoTimeout, WithMaxRetries, WithRetryNonIdempotent, WithFollowRedirects, WithMaxRedirects, WithAllowPrivateIPs, WithStreamBody
Callbacks (2)	WithOnRequest, WithOnResponse

For the signatures, validation rules, and Config defaults overridden by all options, see Request Options.

Result Family

Category	Symbols
Types	Result (17 nil-safe methods)
Status and protocol	StatusCode, Proto, IsSuccess, IsRedirect, IsClientError, IsServerError
Body access	Body, RawBody
Parsing and saving	Unmarshal, SaveToFile, String
Cookies	ResponseCookies, GetCookie, HasCookie, RequestCookies, GetRequestCookie, HasRequestCookie
Sub-types	RequestInfo, ResponseInfo, RequestMeta (with the ProxyURL proxy field)

See Result for details.

Configuration

Category	Symbols
Main type	Config (Timeouts / Connection / Security / Retry / Middleware / Defaults — six groups)
Sub-config types	TimeoutConfig, ConnectionConfig, SecurityConfig, RetryConfig, MiddlewareConfig, RequestDefaults
Presets (5)	DefaultConfig, SecureConfig, PerformanceConfig, TestingConfig, MinimalConfig
Validation and output	ValidateConfig, Config.String
Cookie security	CookieSecurityConfig, DefaultCookieSecurityConfig, StrictCookieSecurityConfig
Download config	DownloadConfig, DefaultDownloadConfig, DownloadResult, DownloadProgressCallback, ChecksumAlgorithm
Session config	SessionConfig, DefaultSessionConfig, NewSessionManager, NewSessionManagerDefault

See Configuration, File Download, and Session Management for details.

Handler, Middleware, and Mutators

Category	Symbols
Pipeline types	Handler, MiddlewareFunc, Chain
Middleware factories (7)	LoggingMiddleware, RecoveryMiddleware, RequestIDMiddleware, TimeoutMiddleware, HeaderMiddleware, MetricsMiddleware, AuditMiddleware
Middleware configs	LoggingConfig, RequestIDConfig, TimeoutMiddlewareConfig, HeaderConfig, MetricsConfig, AuditConfig (each with a Default*Config() constructor)
Mutators	RequestMutator, ResponseMutator (the contract through which middleware reads/writes requests and responses)

See Handler Pipeline, Built-in Middleware, and Mutators for details.

Interfaces and Types

Category	Symbols
Core interfaces	Client, Doer, DomainClienter, RetryPolicy
Type aliases	RequestOption, ClientError, ErrorType, CertificatePinner, ProxyStrategy
Certificate pinning	NewSPKIHashPinner, NewPublicKeyPinner, NewCertificatePinnerChain
Session and domain	SessionManager, DomainClient (recommended for use via the DomainClienter interface)
Data types	FormData, FileData, AuditEvent

See Interfaces, Domain Client, Session Management, and Constants and Types for details.

Errors and Constants

Category	Symbols
Error types	ClientError, ErrorType (enum of 12 error categories)
Sentinel errors (17)	ErrClientClosed, ErrNilConfig, ErrInvalidHeader, ErrInvalidTimeout, ErrInvalidRetry, ErrInvalidMaxRedirects, ErrInvalidCredentials, ErrInvalidConnection, ErrInvalidSecurity, ErrInvalidMiddleware, ErrEmptyFilePath, ErrFileExists, ErrResponseBodyEmpty, ErrResponseBodyTooLarge, ErrStreamBodyRequiresDownload, ErrDownloadInProgress, ErrProxyConnectionFailed
BodyKind (6 constants)	BodyAuto, BodyJSON, BodyXML, BodyForm, BodyBinary, BodyMultipart
Other constants	ProxyStrategyRoundRobin / ProxyStrategyRandom, ChecksumSHA256, audit context keys

See Error Types and Constants and Types for details.

Quick Reference

Creating a Client

client, err := httpc.NewDefault()             // Default configuration
client, err := httpc.New(httpc.SecureConfig()) // Secure preset
client, err := httpc.New(customConfig)         // Custom configuration

Sending Requests

// Package-level functions
result, err := httpc.Get(url, options...)

// Client methods
result, err := client.Get(url, options...)

// With context
result, err := client.Request(ctx, "GET", url, options...)

Handling Responses

result.StatusCode()           // Status code
result.Body()                 // Response body (string)
result.RawBody()              // Response body (bytes)
result.Unmarshal(&data)       // JSON parsing
result.IsSuccess()            // Is 2xx
result.Meta.Duration          // Request duration
result.Meta.Attempts          // Retry count

Version Compatibility

• Go version: requires Go 1.26 or later (go.mod declares go 1.26.0).
• Import path: github.com/cybergodev/httpc (package name httpc, no alias needed).
• Direct dependencies: only golang.org/x/sys (for per-platform system-proxy detection, covering Linux/macOS/Windows); no other third-party dependencies.
• API status: no exported symbol currently carries a Deprecated marker; the library is under active maintenance.