Proxy¶

Added in version 0.5.

The harp_apps.proxy application provides the core proxy features for HARP and includes the configuration logic for endpoints (the mapping between local ports and remote urls, including how to handle them).

Setup¶

The proxy application is enabled by default when using the harp start … or harp server … commands. You can disable it with the –disable proxy option, although this will most probably result in an useless system.

Configuration¶

Minimal example¶

proxy:
  endpoints:
    - name: httpbin # a unique name for the endpoint, used to reference it in code, rules and dashboard
      description: An informative description of the endpoint (optional)
      port: 4000 # the local listening port for this endpoint
      url: "https://api1.example.com/"

Note

The url provided can be either a base url like https://api1.example.com/ or a full url like https://api1.example.com/foo/bar/.

Full example¶

proxy:
  endpoints:
    - # An identifier for this local endpoint, used to reference it in code, rules and
      # dashboard. Must be unique for a given harp instance.
      name: httpbins

      # a human-readable description of the endpoint (optional)
      description: A very informative description

      # the local listening port for this endpoint, if not set the proxy will not listen on
      # any port for this endpoint.
      port: 4000

      # the controller to use for this endpoint, "null" means default but you can specify
      # a custom controller. Most of the time you will want to use the default controller
      # and thus do not include this line.
      controller: null

      # the remote to proxy to, which can be anything from a single url to a complex
      # multipool configuration with # defaults and fallbacks, healthcheck probes, etc.
      remote:
        # the minimum number of endpoints to try to keep in the active pool. If the number
        # of active endpoints falls below this number, the proxy will attempt to bring them
        # back up to this number by including endpoints from the fallback pool.
        min_pool_size: 2

        # Endpoints
        endpoints:
          - url: "https://api1.example.com/"
          - url: "https://api2.example.com/"
          - url: "https://fallback.example.com/"
            pools: [fallback]
            liveness:
              type: ignore

        # Liveness settings for all endpoints, if not overriden by a specific endpoint's
        # liveness.
        liveness:
          type: naive
          failure_threshold: 2
          success_threshold: 2

        # A periodic probe to try to close the circuit breaker even if it's not actively
        # queried by the end user.
        probe:
          method: GET
          path: /healthz
          timeout: 10.0

Custom Controller¶

You can also provide a custom controller to handle the proxy logic. This is useful if you want to add custom logic to the proxy. A custom controller must be defined as a Service.

proxy:
  endpoints:
    - name: httpbin # a unique name for the endpoint, used to reference it in code, rules and dashboard
      description: An informative description of the endpoint (optional)
      port: 4000 # the local listening port for this endpoint
      url: "https://api1.example.com/"
      controller:
        type: harp_apps.proxy.controllers.HttpProxyController
        name: httpbin_controller
        logging: false

Command line¶

It is also possible to add endpoints using the command line. This is available for quick tests but should not be used as a permanent solution.

harp start --endpoint starwars=1234:https://swapi.dev/

Warning

The current CLI syntax is hackish and limited, the syntax will most probably change in the future.

You can use multiple --endpoint ... arguments and the option is available for all server-like commands (harp start ..., harp server ..., …).

Warning

For now, endpoints does not support subpaths on remote side. For exemple: http://example.com/ is supported as an endpoint base url but not http://example.com/foo/bar. Proxy will still forward requests to sub paths but no rewriting will be done on the request path.