Caracola.Dispatcher (Caracola v0.1.0-rc.1)

Copy Markdown View Source

Groups of destinations (gateways, media servers, other proxies) for a proxy, with load balancing, health checks and failover.

defmodule MyProxy do
  use Malla.Service,
    plugins: [Caracola.Dispatcher],
    sip: [listen: "sip:all:5060"],
    dispatcher: [
      groups: [
        gateways: [
          destinations: ["sip:10.0.0.1", {"sip:10.0.0.2;transport=tcp", 2}],
          strategy: :weighted
        ]
      ]
    ]

  defcb sip_route(_scheme, _user, _domain, req, call),
    do: Caracola.Dispatcher.route(:gateways, req, call, [:record_route])
end

route/4 proxies a request to the destinations of a group, in the order given by its strategy, one after another (serial forking, see Proxies): if a destination fails, the next one is tried. select/3 returns that order, to build other routes.

Strategies

  • :priority (default) - in the configured order: the first destination gets all the requests while it is up.
  • :round_robin - each request starts with the next destination.
  • :weighted - random, each destination proportionally to its weight (1 by default).
  • :hash - by a key (the Call-ID in route/4): requests with the same key go to the same destination while it is up, and the requests of a destination that goes down are spread among the others (rendezvous hashing).

Health checks

Every destination is sent an OPTIONS request periodically. Any response but a 408 or 503 means it is up; after a number of failures in a row it is marked as down, and not used until a check succeeds again. Destinations start as up. Changes emit the [:caracola, :dispatcher, :status] telemetry event, with the :service, :uri (a string) and :status (:up or :down) as metadata. set_status/3 changes the status by hand, for example after a failure seen by the application, until the next check.

Configuration

Under the :dispatcher key:

  • :groups - keyword list of groups, each with:
    • :destinations - list of URIs, or {uri, weight}.
    • :strategy - :priority, :round_robin, :weighted or :hash.
  • :probe - health checks, false to disable them:
    • :interval - milliseconds between checks (default 30000).
    • :timeout - milliseconds to wait for the response (default 5000).
    • :failures - failures in a row to mark a destination as down (default 2).

Summary

Types

A destination of a group: its URI, its weight and whether it is up or down.

How a group chooses a destination.

Functions

The destinations of a group, with their weight and status.

A sip_route/5 result proxying a request to the destinations of a group (with proxy_opts, see Proxies), tried one after another, or a 503 if none is up.

The destinations of a group that are up, in the order of its strategy.

Changes the status of a destination (in all its groups), until the next health check.

Types

destination()

@type destination() :: %{
  uri: Caracola.URI.t(),
  weight: pos_integer(),
  status: :up | :down
}

A destination of a group: its URI, its weight and whether it is up or down.

strategy()

@type strategy() :: :priority | :round_robin | :weighted | :hash

How a group chooses a destination.

Functions

destinations(service, group)

@spec destinations(module(), atom()) :: [destination()]

The destinations of a group, with their weight and status.

route(group, req, call, proxy_opts \\ [])

@spec route(atom(), Caracola.Message.t(), Caracola.Call.t(), list()) ::
  {:proxy, [[Caracola.URI.t()]], list()} | {:reply, :service_unavailable}

A sip_route/5 result proxying a request to the destinations of a group (with proxy_opts, see Proxies), tried one after another, or a 503 if none is up.

The Request-URI is sent to each destination with its user, if the destination URI has none.

select(service, group, opts \\ [])

@spec select(module(), atom(), keyword()) :: [Caracola.URI.t()]

The destinations of a group that are up, in the order of its strategy.

Options:

  • :key - the key for the :hash strategy.
  • :max - maximum number of destinations.

set_status(service, uri, status)

@spec set_status(module(), String.t() | Caracola.URI.t(), :up | :down) :: :ok

Changes the status of a destination (in all its groups), until the next health check.