http

func BuildRequest ¶

func BuildRequest(
	ctx context.Context,
	method string,
	urlString string,
	parameters url.Values,
	body io.Reader,
	header http.Header,
) (*http.Request, error)

BuildRequest creates an HTTP request with the specified parameters. It constructs a request with the given method, URL, query parameters, body, and headers. The parameters argument contains URL query parameters that are properly encoded and appended to the URL query string. Any existing query parameters in the URL are replaced.

func CheckResponseIsSuccessful ¶

func CheckResponseIsSuccessful(req *http.Request, resp *http.Response) error

CheckResponseIsSuccessful validates that an HTTP response indicates success. It returns ErrNotFound error for 404 responses, and RequestFailedError for other non-success status codes. Success is defined as 2xx or 3xx status codes. The response body is preserved for further reading.

func CreateDefaultHTTPClient ¶ added in v1.19.0

func CreateDefaultHTTPClient() *http.Client

CreateDefaultHTTPClient creates an HTTP client with default configuration. It uses a 30-second timeout and the default RoundTripper with retry logic and logging. The client disables automatic redirects by returning ErrUseLastResponse.

func CreateHTTPClient ¶ added in v1.19.0

func CreateHTTPClient(
	timeout time.Duration,
) *http.Client

CreateHTTPClient creates an HTTP client with the specified timeout. It uses the default RoundTripper with retry logic and logging, and disables automatic redirects. The timeout applies to the entire request including connection, redirects, and reading the response.

func CreateHTTPServer ¶ added in v1.19.0

func CreateHTTPServer(
	addr string,
	router http.Handler,
	serverOptions ServerOptions,
) *http.Server

CreateHTTPServer creates an HTTP server with the specified address, handler, and options.

func CreateTLSClientConfig ¶ added in v1.19.0

func CreateTLSClientConfig(
	ctx context.Context,
	caCertPath string,
	clientCertPath string,
	clientKeyPath string,
) (*tls.Config, error)

CreateTLSClientConfig creates a TLS configuration for mutual TLS authentication. It loads the CA certificate for server verification and the client certificate for client authentication. The configuration enforces server certificate verification (InsecureSkipVerify is false).

func FileServer ¶

func FileServer(
	root string,
	prefix string,
) http.Handler

FileServer creates an HTTP handler that serves files from the specified root directory. It serves files with the given path prefix and automatically serves index.html for missing files. This is useful for serving single-page applications where all routes should serve the main HTML file.

func IsIgnoredSentryError ¶

func IsIgnoredSentryError(err error) bool

IsIgnoredSentryError determines whether an error should be ignored when reporting to Sentry. It returns true for common transient errors like context cancellation, timeouts, and other retryable errors. This helps reduce noise in Sentry by filtering out expected operational errors.

func IsRetryError ¶

func IsRetryError(err error) bool

IsRetryError determines whether an error should trigger a retry attempt. It checks for common transient errors like EOF, connection refused, timeouts, and handler timeouts. Returns true if the error is considered retryable, false otherwise.

func NewBackgroundRunHandler ¶

func NewBackgroundRunHandler(ctx context.Context, runFunc run.Func) http.Handler

NewBackgroundRunHandler creates an HTTP handler that executes a run.Func in the background. When the endpoint is called, it triggers the runFunc asynchronously and immediately returns a response. The handler uses a ParallelSkipper to prevent multiple concurrent executions of the same function.

func NewBackgroundRunRequestHandler ¶ added in v1.14.0

func NewBackgroundRunRequestHandler(
	ctx context.Context,
	runFunc BackgroundRunRequestFunc,
) http.Handler

NewBackgroundRunRequestHandler creates an HTTP handler that executes the given function in the background. When the endpoint is called, it triggers the runFunc asynchronously with access to the HTTP request. The handler uses a ParallelSkipper to prevent multiple concurrent executions and returns immediately.

func NewDangerousHandlerWrapper ¶ added in v1.20.0

func NewDangerousHandlerWrapper(handler http.Handler) http.Handler

NewDangerousHandlerWrapper wraps dangerous HTTP handlers with passphrase protection. Each instance generates a unique passphrase that expires after 5 minutes. The passphrase is logged to stdout/stderr, requiring operators to have log access in addition to HTTP access to execute dangerous operations.

func NewDangerousHandlerWrapperWithCurrentDateTime ¶ added in v1.20.0

func NewDangerousHandlerWrapperWithCurrentDateTime(
	handler http.Handler,
	currentDateTime libtime.CurrentDateTime,
) http.Handler

NewDangerousHandlerWrapperWithCurrentDateTime wraps dangerous HTTP handlers with passphrase protection using the provided CurrentDateTime interface for testability.

func NewErrorHandler ¶

func NewErrorHandler(withError WithError) http.Handler

NewErrorHandler wraps a WithError handler to provide centralized error handling. It converts errors to HTTP responses with appropriate status codes and logs the results. If the error implements ErrorWithStatusCode, it uses that status code; otherwise defaults to 500.

func NewGarbageCollectorHandler ¶ added in v1.12.0

func NewGarbageCollectorHandler() http.Handler

func NewJSONErrorHandler ¶ added in v1.24.0

func NewJSONErrorHandler(withError WithError) http.Handler

NewJSONErrorHandler wraps a WithError handler to provide centralized JSON error handling. It converts errors to JSON responses with appropriate status codes and logs the results. If the error implements ErrorWithStatusCode, it uses that status code; otherwise defaults to 500. If the error implements ErrorWithCode, it uses that error code; otherwise defaults to INTERNAL_ERROR.

Example usage:

handler := libhttp.NewJSONErrorHandler(
    libhttp.WithErrorFunc(func(ctx context.Context, resp http.ResponseWriter, req *http.Request) error {
        return libhttp.WrapWithCode(
            errors.New(ctx, "validation failed"),
            libhttp.ErrorCodeValidation,
            http.StatusBadRequest,
        )
    }),
)

func NewJSONUpdateErrorHandler ¶ added in v1.24.0

func NewJSONUpdateErrorHandler(db libkv.DB, withErrorTx WithErrorTx) http.Handler

NewJSONUpdateErrorHandler wraps a WithErrorTx handler for update transactions, returning JSON error responses instead of plain text.

Example usage:

handler := libhttp.NewJSONUpdateErrorHandler(
    db,
    libhttp.WithErrorTxFunc(func(ctx context.Context, tx libkv.Tx, resp http.ResponseWriter, req *http.Request) error {
        // Handle update logic with transaction
        return nil
    }),
)

func NewJSONViewErrorHandler ¶ added in v1.24.0

func NewJSONViewErrorHandler(db libkv.DB, withErrorTx WithErrorTx) http.Handler

NewJSONViewErrorHandler wraps a WithErrorTx handler for view (read-only) transactions, returning JSON error responses instead of plain text.

Example usage:

handler := libhttp.NewJSONViewErrorHandler(
    db,
    libhttp.WithErrorTxFunc(func(ctx context.Context, tx libkv.Tx, resp http.ResponseWriter, req *http.Request) error {
        // Handle read-only logic with transaction
        return nil
    }),
)

func NewMetricsRoundTripper ¶ added in v1.13.0

func NewMetricsRoundTripper(
	roundTripper http.RoundTripper,
	metrics RoundTripperMetrics,
) http.RoundTripper

NewMetricsRoundTripper wraps a given RoundTripper and adds Prometheus metrics.

func NewPrintHandler ¶

func NewPrintHandler(format string, a ...any) http.Handler

func NewProxy ¶

func NewProxy(
	transport http.RoundTripper,
	apiURL *url.URL,
	proxyErrorHandler ProxyErrorHandler,
) http.Handler

NewProxy creates a reverse proxy that forwards requests to the specified URL. It uses the provided transport for making upstream requests and handles errors with the given error handler. The proxy automatically sets the Host header to match the target URL.

func NewRoundTripperBasicAuth ¶

func NewRoundTripperBasicAuth(
	roundTripper RoundTripper,
	username string,
	password string,
) http.RoundTripper

NewRoundTripperBasicAuth wraps a RoundTripper with HTTP Basic Authentication. It automatically adds Basic Auth headers to all requests using the provided username and password. If either username or password is empty, no authentication header is added.

func NewRoundTripperHeader ¶

func NewRoundTripperHeader(
	roundTripper http.RoundTripper,
	header http.Header,
) http.RoundTripper

NewRoundTripperHeader wraps a RoundTripper to add custom headers to all requests. The provided headers are added to every request, replacing any existing headers with the same keys. This is useful for adding authentication headers, API keys, or other standard headers.

func NewRoundTripperLog ¶

func NewRoundTripperLog(tripper http.RoundTripper) http.RoundTripper

NewRoundTripperLog wraps a RoundTripper with request/response logging. It logs the HTTP method, URL, status code, duration, and any errors at verbose level 2. This is useful for debugging and monitoring HTTP client behavior.

func NewRoundTripperRateLimit ¶

func NewRoundTripperRateLimit(
	ctx context.Context,
	tripper http.RoundTripper,
	maxRequestPerInterval int64,
	intervalDurarion time.Duration,
	logSamplerFactory log.SamplerFactory,
) http.RoundTripper

NewRoundTripperRateLimit wraps a RoundTripper with rate limiting functionality. It limits the number of requests to maxRequestPerInterval within each intervalDuration window. When the limit is exceeded, requests are delayed rather than rejected. The logSamplerFactory is used to sample rate limit messages to reduce log noise.

func NewRoundTripperRemovePathPrefix ¶

func NewRoundTripperRemovePathPrefix(
	roundTripper http.RoundTripper,
	prefix string,
) http.RoundTripper

NewRoundTripperRemovePathPrefix wraps a RoundTripper to remove a path prefix from request URLs. If the request URL path starts with the specified prefix, it removes that prefix before forwarding the request. This is useful for proxying requests where the upstream service expects different path structures.

func NewRoundTripperRetry ¶

func NewRoundTripperRetry(
	roundTripper http.RoundTripper,
	retryLimit int,
	retryDelay time.Duration,
) http.RoundTripper

NewRoundTripperRetry wraps a RoundTripper with retry logic using default skip status codes. It will retry failed requests up to retryLimit times with retryDelay between attempts. Requests with 400, 401, and 404 status codes are not retried as they indicate client errors.

func NewRoundTripperRetryWithSkipStatus ¶ added in v1.8.1

func NewRoundTripperRetryWithSkipStatus(
	roundTripper http.RoundTripper,
	retryLimit int,
	retryDelay time.Duration,
	skipStatusCodes []int,
) http.RoundTripper

NewRoundTripperRetryWithSkipStatus wraps a RoundTripper with retry logic and custom skip status codes. It allows specifying which HTTP status codes should not trigger retries. This is useful when you want to customize which responses are considered permanent failures.

func NewServer ¶

func NewServer(
	addr string,
	router http.Handler,
	optionFns ...func(serverOptions *ServerOptions),
) run.Func

NewServer creates an HTTP server that listens on the specified address. It returns a run.Func that handles graceful shutdown when the context is cancelled. The addr parameter should be in the format ":port" or "host:port".

func NewServerTLS ¶

func NewServerTLS(
	addr string,
	router http.Handler,
	serverCertPath string,
	serverKeyPath string,
	optionFns ...func(serverOptions *ServerOptions),
) run.Func

NewServerTLS creates an HTTPS server with TLS support. It listens on the specified address using the provided certificate and key files. The server includes error log filtering to skip common TLS handshake errors. Returns a run.Func for graceful shutdown management.

func NewServerWithPort ¶

func NewServerWithPort(
	port int,
	router http.Handler,
	optionFns ...func(serverOptions *ServerOptions),
) run.Func

NewServerWithPort creates an HTTP server that listens on the specified port. It returns a run.Func that can be used with the run package for graceful shutdown. The server will bind to all interfaces on the given port (e.g., port 8080 becomes ":8080").

func NewSkipErrorWriter ¶

func NewSkipErrorWriter(writer io.Writer) io.Writer

NewSkipErrorWriter creates a writer that filters out TLS handshake error messages. It wraps the given writer and skips writing messages containing "http: TLS handshake error from". This is useful for reducing noise in server logs when dealing with automated scanners or bots.

func NewUpdateErrorHandler ¶ added in v1.8.0

func NewUpdateErrorHandler(db libkv.DB, withErrorTx WithErrorTx) http.Handler

func NewViewErrorHandler ¶ added in v1.8.0

func NewViewErrorHandler(db libkv.DB, withErrorTx WithErrorTx) http.Handler

func RegisterPprof ¶

func RegisterPprof(router *mux.Router)

RegisterPprof register pprof http endpoint to gorilla mux https://www.codereliant.io/memory-leaks-with-pprof/ kubectl -n erpnext port-forward service/hubspot-resource-exporter 9090:9090 go tool pprof -alloc_space http://localhost:9090/debug/pprof/heap > web or go tool pprof -http=127.0.0.1:16666 -alloc_space http://localhost:9090/debug/pprof/heap

func SendJSONFileResponse ¶ added in v1.17.0

func SendJSONFileResponse(
	ctx context.Context,
	resp http.ResponseWriter,
	data interface{},
	fileName string,
	statusCode int,
) error

SendJSONFileResponse writes a JSON-encoded response configured for file download. It sets Content-Type to application/json, adds a Content-Disposition header with the specified filename, and includes Content-Length for the response.

The filename must be a valid, safe filename (not a path). It will be validated and an error returned if it contains:

• Path separators or traversal sequences (/, \, ..)
• Control characters that could enable HTTP header injection
• Quotes that could break the header format

If you have a path and want to use just the filename, call filepath.Base() first.

Note: This function uses json.Marshal to buffer the entire response in memory, which is necessary to calculate and set the Content-Length header. For very large responses (>100MB), consider using streaming alternatives without Content-Length.

Example:

data := map[string]interface{}{"users": users}
err := http.SendJSONFileResponse(ctx, w, data, "users.json", http.StatusOK)

func SendJSONResponse ¶ added in v1.16.0

func SendJSONResponse(
	ctx context.Context,
	resp http.ResponseWriter,
	data interface{},
	statusCode int,
) error

SendJSONResponse writes a JSON-encoded response with the specified status code. It sets the Content-Type header to application/json and returns any encoding errors.

func ValidateFilename ¶ added in v1.17.0

func ValidateFilename(ctx context.Context, name string) error

ValidateFilename checks if a filename is safe for use in Content-Disposition header. It returns an error if the filename:

• Is empty
• Contains path separators (/, \) or path traversal (..)
• Starts with a slash
• Contains control characters (ASCII 0-31, 127) that could enable header injection
• Contains quotes that could break the header format
• Is not clean according to filepath.Clean (catches sneaky path tricks)

This function expects a bare filename, not a path. If you have a path and want to extract the filename, use filepath.Base() first.

func WrapWithCode ¶ added in v1.24.0

func WrapWithCode(err error, code string, statusCode int) error

WrapWithCode wraps an error with both an error code and HTTP status code. This allows the error to be used with JSON error handlers that return structured error responses.

Example:

err := WrapWithCode(
    errors.New(ctx, "columnGroup '' is unknown"),
    ErrorCodeValidation,
    http.StatusBadRequest,
)

func WrapWithDetails ¶ added in v1.24.0

func WrapWithDetails(err error, code string, statusCode int, details map[string]any) error

WrapWithDetails wraps an error with code, status, and structured details. This is a convenience helper that combines WrapWithCode with adding data to the error. Details can include any JSON-serializable values including arrays and nested objects.

Example:

err := WrapWithDetails(
    errors.New(ctx, "columnGroup '' is unknown"),
    ErrorCodeValidation,
    http.StatusBadRequest,
    map[string]any{
        "field":    "columnGroup",
        "expected": []string{"day", "week", "month", "year"},
    },
)

func WriteAndGlog ¶

func WriteAndGlog(w io.Writer, format string, a ...any) (n int, err error)

WriteAndGlog writes formatted text to both a writer and the glog at verbose level 2. It formats the message using fmt.Printf-style formatting and writes it to the writer with a newline. The same message is also logged using glog.V(2).InfoDepthf for debugging purposes.