View Source Wayfarer.Router (wayfarer v0.6.1)

Wayfarer's routing is implemented on top of an ETS table to allow for fast querying and easy mutation.

This module provides a standardised interface to interact with a routing table.

Summary

Types

algorithm()

The algorithm used to select which target to forward requests to (when there is more than one matching target).

health()

The current health status of the target.

host_name()

A fully qualified hostname optionally with a leading wildcard.

host_pattern()

Host patterns are built by splitting hostnames into segments and storing them as tuples. Hosts with a leading wildcard (*) segment will have that segment replaced with a :_.

listener()

Uniquely identifies a listener.

route()

The row format for each route in the table.

scheme()

target()

Uniquely identifies a request target, either a remote http(s) server or a local Plug.

target_input()

Like target/0 except that it can contain user input for the address portion.

Functions

add_route(table, listener, target, host_names, algorithm)

Add new route to the routing table.

find_healthy_targets(table, listener, hostname)

Find healthy targets for a given listener and hostname.

import_routes(table, routes)

Add a number of routes into the routing table.

init(name)

Create a new, empty routing table.

remove_listener(table, listener)

Remove a listener from the routing table.

remove_target(table, target)

Remove a target from the routing table.

update_target_health_status(table, arg, status)

Change a target's health state.

Types

algorithm()

@type algorithm() :: Wayfarer.Target.Selector.algorithm()

The algorithm used to select which target to forward requests to (when there is more than one matching target).

health()

@type health() :: :initial | :healthy | :unhealthy | :draining

The current health status of the target.

host_name()

@type host_name() :: String.t()

A fully qualified hostname optionally with a leading wildcard.

host_pattern()

@type host_pattern() :: tuple()

Host patterns are built by splitting hostnames into segments and storing them as tuples. Hosts with a leading wildcard (*) segment will have that segment replaced with a :_.

Examples

www.example.com becomes {"com", "example", "www"}
*.example.com becomes {"com", "example", :_}

listener()

@type listener() :: {scheme(), :inet.ip_address(), :socket.port_number()}

Uniquely identifies a listener.

route()

@type route() :: {listener(), host_pattern(), target(), algorithm(), health()}

The row format for each route in the table.

scheme()

@type scheme() :: :http | :https

target()

@type target() ::
  {:http | :https | :ws | :wss, :inet.ip_address(), :socket.port_number(),
   :http1 | :http2 | :auto}
  | {:plug, module()}
  | {:plug, {module(), any()}}

Uniquely identifies a request target, either a remote http(s) server or a local Plug.

target_input()

@type target_input() ::
  {:http | :https | :ws | :wss, Wayfarer.Utils.address_input(),
   :socket.port_number(), :http1 | :http2 | :auto}
  | {:plug, module()}
  | {:plug, {module(), any()}}

Like target/0 except that it can contain user input for the address portion.

Functions

add_route(table, listener, target, host_names, algorithm)

@spec add_route(:ets.tid(), listener(), target_input(), [host_name()], algorithm()) ::
  :ok | {:error, any()}

Add new route to the routing table.

A route will be added for each host name with it's health state set to :initial.

This should only ever be called by Wayfarer.Server directly.

find_healthy_targets(table, listener, hostname)

@spec find_healthy_targets(:ets.tid(), listener(), String.t()) ::
  {:ok, [{target(), algorithm()}]} | {:error, any()}

Find healthy targets for a given listener and hostname.

import_routes(table, routes)

@spec import_routes(:ets.tid(), [
  {listener(), target_input(), [host_name()], algorithm()}
]) :: :ok

Add a number of routes into the routing table.

init(name)

@spec init(module()) :: {:ok, :ets.tid()} | {:error, any()}

Create a new, empty routing table.

This table is protected and owned by the calling process.

remove_listener(table, listener)

@spec remove_listener(:ets.tid(), listener()) :: :ok

Remove a listener from the routing table.

This should only ever be done by Wayfarer.Server after it has finished draining connections.

remove_target(table, target)

@spec remove_target(:ets.tid(), target()) :: :ok

Remove a target from the routing table.

This should only ever be done by Wayfarer.Server after it has finished draining connections.

update_target_health_status(table, arg, status)

@spec update_target_health_status(:ets.tid(), target(), health()) :: :ok

Change a target's health state.