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])
endroute/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 inroute/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,:weightedor:hash.
:probe- health checks,falseto 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
@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.
@type strategy() :: :priority | :round_robin | :weighted | :hash
How a group chooses a destination.
Functions
@spec destinations(module(), atom()) :: [destination()]
The destinations of a group, with their weight and status.
@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.
@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:hashstrategy.:max- maximum number of destinations.
@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.