Module Proxy

HTTP Proxy Configuration

Per RFC 9110 Section 3.7 and Section 7.3.2: A proxy is a message-forwarding agent chosen by the client, usually configured via local rules.

Usage

Create a proxy configuration:

  let proxy = Proxy.http ~port:8080 "proxy.example.com"

  (* With authentication *)
  let proxy = Proxy.http
    ~port:8080
    ~auth:(Auth.basic ~username:"user" ~password:"pass")
    "proxy.example.com"

  (* With bypass list *)
  let proxy = Proxy.http
    ~no_proxy:["localhost"; "*.internal.example.com"]
    "proxy.example.com"

Read from environment variables:

  match Proxy.from_env () with
  | Some proxy -> (* use proxy *)
  | None -> (* no proxy configured *)
val src : Logs.Src.t

Log source for proxy operations

Proxy Types

type proxy_type =
  1. | HTTP
    (*

    HTTP proxy (CONNECT for HTTPS, absolute-URI for HTTP)

    *)
  2. | SOCKS5
    (*

    SOCKS5 proxy (RFC 1928) - future extension

    *)

Proxy protocol type

type config = {
  1. host : string;
    (*

    Proxy server hostname

    *)
  2. port : int;
    (*

    Proxy server port (default: 8080)

    *)
  3. proxy_type : proxy_type;
  4. auth : Auth.t option;
    (*

    Proxy authentication (Proxy-Authorization)

    *)
  5. no_proxy : string list;
    (*

    Hosts/patterns to bypass proxy

    *)
}

Proxy configuration

Configuration Constructors

val http : ?port:int -> ?auth:Auth.t -> ?no_proxy:string list -> string -> config

http ?port ?auth ?no_proxy host creates an HTTP proxy configuration.

  • parameter port

    Proxy port (default: 8080)

  • parameter auth

    Proxy authentication credentials

  • parameter no_proxy

    List of hosts/patterns to bypass the proxy. Supports wildcards like *.example.com to match foo.example.com.

  • parameter host

    Proxy server hostname

val socks5 : ?port:int -> ?auth:Auth.t -> ?no_proxy:string list -> string -> config

socks5 ?port ?auth ?no_proxy host creates a SOCKS5 proxy configuration.

Note: SOCKS5 support is not yet implemented. This function creates the configuration type for future use.

  • parameter port

    Proxy port (default: 1080)

  • parameter auth

    Proxy authentication credentials

  • parameter no_proxy

    List of hosts/patterns to bypass the proxy

  • parameter host

    Proxy server hostname

Configuration Utilities

val should_bypass : config -> string -> bool

should_bypass config url returns true if url should bypass the proxy based on the no_proxy list.

Matching rules:

  • Exact hostname match (case-insensitive)
  • Wildcard prefix match: *.example.com matches foo.example.com
  • localhost and 127.0.0.1 match by default if in no_proxy list
val host_port : config -> string * int

host_port config returns the proxy host and port as a tuple.

val validate_supported : config -> unit

validate_supported config checks that the proxy type is currently supported.

Environment Variable Support

val from_env : unit -> config option

from_env () reads proxy configuration from environment variables.

Checks the following variables (in order of preference):

  • HTTP_PROXY / http_proxy
  • HTTPS_PROXY / https_proxy
  • ALL_PROXY / all_proxy
  • NO_PROXY / no_proxy (comma-separated list of bypass patterns)

Returns None if no proxy is configured.

URL format: http://[user:pass@]host[:port]

Example environment:

  HTTP_PROXY=http://user:pass@proxy.example.com:8080
  NO_PROXY=localhost,*.internal.example.com,.example.org
val from_env_for_url : string -> config option

from_env_for_url url reads proxy configuration appropriate for url.

  • Uses HTTPS_PROXY for HTTPS URLs
  • Uses HTTP_PROXY for HTTP URLs
  • Falls back to ALL_PROXY
  • Returns None if the URL matches NO_PROXY patterns

Pretty Printing

val pp_proxy_type : Format.formatter -> proxy_type -> unit

Pretty printer for proxy type

val pp_config : Format.formatter -> config -> unit

Pretty printer for proxy configuration. Note: Authentication credentials are redacted.