Documentation
¶
Overview ¶
Package httputil provides shared HTTP helper utilities used across multiple HTTP-facing packages (server, proxy, etc.).
Package httputil — generic HTTP helper utilities.
TLS helpers are split across two packages:
internal/httputil (this file): protocol-level helpers and file-loading helpers that apply to all TLS listeners and clients: MinTLSVersion, NewServerTLSConfig, NewClientTLSConfig, ConfigureTLSTrustEnvironment, LoadGatewayTLS.
internal/proxy: certificate *generation* (GenerateSelfSignedTLS) lives there because it is only needed when the proxy runs in self-signed mode. It calls httputil.NewServerTLSConfig to assemble the final *tls.Config.
Architectural rule: add TLS *protocol and file-loading* helpers here; add TLS *certificate generation* helpers to internal/proxy/tls.go.
Index ¶
- Constants
- func ConfigureTLSTrustEnvironment(caCertPath string) error
- func IsTransientHTTPError(statusCode int) bool
- func LoadGatewayTLS(certPath, keyPath, caPath string) (*tls.Config, error)
- func NewClientTLSConfig() *tls.Config
- func NewServerTLSConfig(cert tls.Certificate) *tls.Config
- func ReadResponseBody(resp *http.Response, context string) ([]byte, error)
- func ReadResponseBodyStrict(resp *http.Response, expectedStatus int, context string) ([]byte, error)
- func TLSTrustEnvKeys() []string
- func WriteErrorResponse(w http.ResponseWriter, statusCode int, code, message string)
- func WriteJSONResponse(w http.ResponseWriter, statusCode int, body interface{})
- type BaseResponseWriter
Constants ¶
const MinTLSVersion = tls.VersionTLS12
MinTLSVersion is the minimum TLS version enforced across all gateway listeners and clients. Centralizing this constant ensures a single point of change if the policy is tightened (e.g., to tls.VersionTLS13).
Variables ¶
This section is empty.
Functions ¶
func ConfigureTLSTrustEnvironment ¶ added in v0.4.2
ConfigureTLSTrustEnvironment sets all trust-environment variables to caCertPath so that child processes (Node.js, curl, git, Python) automatically trust the self-signed CA certificate generated by internal/proxy.GenerateSelfSignedTLS.
func IsTransientHTTPError ¶ added in v0.2.25
IsTransientHTTPError returns true for status codes that indicate a temporary server-side condition (rate-limiting or transient failure) worth retrying.
func LoadGatewayTLS ¶ added in v0.4.2
LoadGatewayTLS loads a TLS configuration for the gateway HTTP server from PEM certificate and key files. When caPath is non-empty the returned config requires client certificates signed by that CA (mutual TLS / mTLS). For self-signed certificate generation, see internal/proxy.GenerateSelfSignedTLS.
Pass an empty caPath to use one-way TLS (server-only authentication).
Example — one-way TLS (server cert only):
tlsCfg, err := LoadGatewayTLS("/path/server.crt", "/path/server.key", "")
Example — mutual TLS (client certs required):
tlsCfg, err := LoadGatewayTLS("/path/server.crt", "/path/server.key", "/path/ca.crt")
func NewClientTLSConfig ¶ added in v0.3.28
NewClientTLSConfig returns a *tls.Config suitable for outbound HTTP clients, enforcing the gateway-wide minimum TLS version.
func NewServerTLSConfig ¶ added in v0.3.28
func NewServerTLSConfig(cert tls.Certificate) *tls.Config
NewServerTLSConfig returns a *tls.Config for TLS server listeners carrying the provided certificate and the gateway-wide minimum TLS version.
func ReadResponseBody ¶ added in v0.3.33
ReadResponseBody reads the full body from an HTTP response, closes it, and checks the status code. If the status code is >= 400, it returns an error using the provided context string. The response body is always closed before returning.
This helper deduplicates the common pattern of defer Body.Close() + io.ReadAll + status-code check that appears in proxy, githubhttp, and similar call sites.
func ReadResponseBodyStrict ¶ added in v0.3.33
func ReadResponseBodyStrict(resp *http.Response, expectedStatus int, context string) ([]byte, error)
ReadResponseBodyStrict reads the full body from an HTTP response, closes it, and checks that the status code equals expectedStatus exactly. If the status code does not match, it returns an error that includes the response body for diagnostics. The response body is always closed before returning.
Use this variant when the caller needs an exact status match (e.g. 200 only) and wants the body included in the error message.
func TLSTrustEnvKeys ¶ added in v0.4.2
func TLSTrustEnvKeys() []string
TLSTrustEnvKeys returns the set of trust-environment variable names used by ConfigureTLSTrustEnvironment.
The returned slice is a defensive copy and can be safely modified by callers without affecting package behavior.
func WriteErrorResponse ¶ added in v0.3.2
func WriteErrorResponse(w http.ResponseWriter, statusCode int, code, message string)
WriteErrorResponse writes a JSON error response with a consistent {"error": code, "message": message} shape. Both the server and proxy packages should use this helper so that API consumers always receive the same error shape.
func WriteJSONResponse ¶
func WriteJSONResponse(w http.ResponseWriter, statusCode int, body interface{})
WriteJSONResponse sets the Content-Type header, writes the status code, and encodes body as JSON. It centralises the three-line pattern used across HTTP handlers.
Types ¶
type BaseResponseWriter ¶ added in v0.3.14
type BaseResponseWriter struct {
http.ResponseWriter
// StatusCode holds the captured HTTP status code. It is set by WriteHeader
// and, if still zero when Write is first called, defaults to http.StatusOK.
// Only the first call to WriteHeader or Write sets StatusCode, matching
// net/http semantics where only the first status sent is effective.
StatusCode int
// contains filtered or unexported fields
}
BaseResponseWriter wraps http.ResponseWriter and captures the HTTP response status code. It implements Write (with implicit-200 capture), WriteHeader, and Unwrap so that http.ResponseController callers can access optional interfaces (e.g. http.Flusher, http.Hijacker) on the underlying writer.
Embed BaseResponseWriter in package-specific types to avoid duplicating this status-capture boilerplate.
func (*BaseResponseWriter) Unwrap ¶ added in v0.3.14
func (w *BaseResponseWriter) Unwrap() http.ResponseWriter
Unwrap returns the underlying http.ResponseWriter so that callers using http.ResponseController can discover optional interfaces such as http.Flusher or http.Hijacker on the real writer.
func (*BaseResponseWriter) Write ¶ added in v0.3.14
func (w *BaseResponseWriter) Write(b []byte) (int, error)
Write captures an implicit 200 status on first call when no prior WriteHeader was issued, then delegates to the underlying writer.
func (*BaseResponseWriter) WriteHeader ¶ added in v0.3.14
func (w *BaseResponseWriter) WriteHeader(code int)
WriteHeader captures the status code on first call and forwards it to the underlying writer. Subsequent calls are forwarded but do not update StatusCode, matching net/http semantics where only the first WriteHeader is effective.
Source Files