Proxy¶

The main feature of HARP Proxy is the HTTP Proxy, enabling to define pools of upstream servers, and route requests to them based on various criteria.

Basics¶

The application’s basic behavior is to define named ports (which HARP will listen to locally) for forwarding all HTTP requests to remote servers (unless intercepted by the caching system or a custom rule).

proxy:
  endpoints:
    - name: httpbin
      port: 4000
      url: "https://httpbin.org/"

This is the simplest working configuration, but there are many options to define more complex behaviors.

Multiple ports¶

You can define multiple ports to listen to, each with its own target configuration.

Typically, you’ll define one port per external (or semi-external) API you want to use.

proxy:
  endpoints:
    - name: geo
      port: 4000
      url: "https://geo.api.gouv.fr/"
    - name: adresse
      port: 4001
      url: "https://api-adresse.data.gouv.fr/"

Remote pools¶

Added in version 0.7.

You can define a pool of remote URLs instead of a single remote URL. These URLs will be used in a round-robin manner.

proxy:
  endpoints:
    - name: examples
      port: 4000
      remote:
        endpoints:
          - { url: "https://api1.example.com/" }
          - { url: "https://api2.example.com/" }

Fallback pools¶

Added in version 0.7.

A fallback pool can be defined to be used when the main pool is unavailable or insufficient.

The default minimum pool size is 1. If the pool size falls below this threshold, the fallback pool will be used. This setting can be modified.

proxy:
  endpoints:
    - name: httpbins
      port: 4001
      remote:
        min_pool_size: 2
        endpoints:
          - { url: "https://api1.example.com/" }
          - { url: "https://api2.example.com/" }
          - { url: "https://api3.example.com/", pools: [fallback] }
          - { url: "https://api4.example.com/", pools: [fallback] }

Healthchecks probes¶

Added in version 0.7.

The health of the remote servers will be assessed based on the responses received. If the error rate is too high, the server will be marked as unhealthy and removed from the pool. If the pool lacks sufficient remotes, fallback servers will be added to the active pool.

To customize this default behavior, you can add a healthcheck probe to regularly request a specific URL to evaluate the remote service’s health.

proxy:
  endpoints:
    - name: httpbins
      port: 4001
      remote:
        endpoints:
          - { url: "https://api1.example.com/" }
          - { url: "https://api2.example.com/" }
          - { url: "https://api3.example.com/", pools: [fallback] }
          - { url: "https://api4.example.com/", pools: [fallback] }
        probe:
          method: GET
          path: /health
          headers: { x-probe: "true" }
          timeout: 10

Client¶

Added in version 0.5.

The HTTP client allows the definition of global settings for outgoing HTTP requests, such as timeouts, caching logic, headers, and more.

http_client:
  # Timeout error will occur if the HTTP client does not receive a response within 10
  # seconds (default is 30 seconds).
  timeout: 10.0

  # Transport configuration (optional)
  transport:
    # You can customize the default transport implementation. The values shown are the
    # defaults, and you only need to set them if you want to provide different values.
    "@type": "httpx:AsyncHTTPTransport"
    retries: 0
    verify: true
    http1: true
    http2: false

Caching¶

Added in version 0.5.

A default cache is provided to store responses and reduce redundant network calls. The cache can be disabled or fine-tuned.

The default implementation is based on a conservative RFC-9111 compliant cache, but you can set it to be more aggressive or even switch it entirely to your own implementation.

http_client:
  # Cache configuration (optional)
  cache:
    enabled: true # Set to false to disable cache entirely (optional)

    controller: # Override the cache controller definition (optional)
      cacheable_methods: [GET, HEAD] # Which HTTP methods should be cacheable? (default: [GET, HEAD])
      force_cache: true # or any other hishel.Controller option ....

Reference¶

Proxy & Endpoints: Configuration for endpoints, names, ports, and routing.
Http Client: Configuration for timeouts, caching, and other HTTP client behaviors.