Parrot.Sip.Headers.Route (Parrot Platform v0.0.1-alpha.3)

Module for working with SIP Route headers as defined in RFC 3261 Section 20.34.

The Route header field is used to force routing for a request through a list of proxies. Each proxy extracts the first Route header field value from a request and uses it to route to the next hop.

Route headers serve crucial functions in SIP routing:

  • Implementing loose routing (lr parameter) as defined in RFC 3261
  • Forcing requests through specific proxy paths
  • Enabling pre-loaded routes in initial requests
  • Supporting record-route-based dialog routing

Route headers are typically populated from Record-Route headers received in responses, but in reverse order. The presence of the 'lr' (loose routing) parameter indicates RFC 3261 compliance, distinguishing from RFC 2543 strict routing.

References:

  • RFC 3261 Section 8.1.2: Contact and Route Header Fields
  • RFC 3261 Section 12.2.1.1: UAC Behavior - Generating the Request
  • RFC 3261 Section 16.6: Request Forwarding (proxy processing)
  • RFC 3261 Section 19.1.1: Loose Routing
  • RFC 3261 Section 20.34: Route Header Field

Summary

Types

t()

Functions

format(route)

Formats a Route header as a string.

format_list(routes)

Formats a list of Route headers as a string.

new(uri, display_name \\ nil, parameters \\ %{})

Creates a new Route header.

parse(string)

Parses a Route header string into a Route struct.

parse_list(string)

Parses a list of Route headers.

Types

t()

@type t() :: %Parrot.Sip.Headers.Route{
  display_name: String.t() | nil,
  parameters: map(),
  uri: String.t() | Parrot.Sip.Uri.t()
}

Functions

format(route)

@spec format(t()) :: String.t()

Formats a Route header as a string.

Examples

iex> route = %Parrot.Sip.Headers.Route{display_name: nil, uri: "sip:proxy.example.com;lr", parameters: %{}}
iex> Parrot.Sip.Headers.Route.format(route)
"<sip:proxy.example.com;lr>"

iex> route = %Parrot.Sip.Headers.Route{display_name: "Example Proxy", uri: "sip:proxy.example.com;lr", parameters: %{}}
iex> Parrot.Sip.Headers.Route.format(route)
"Example Proxy <sip:proxy.example.com;lr>"

iex> route = %Parrot.Sip.Headers.Route{display_name: "Complex Name", uri: "sip:proxy.example.com;lr", parameters: %{"param" => "value"}}
iex> Parrot.Sip.Headers.Route.format(route)
""Complex Name" <sip:proxy.example.com;lr>;param=value"

format_list(routes)

@spec format_list([t()]) :: String.t()

Formats a list of Route headers as a string.

Examples

iex> routes = [
...>   %Parrot.Sip.Headers.Route{display_name: nil, uri: "sip:proxy1.example.com;lr", parameters: %{}},
...>   %Parrot.Sip.Headers.Route{display_name: nil, uri: "sip:proxy2.example.com;lr", parameters: %{}}
...> ]
iex> Parrot.Sip.Headers.Route.format_list(routes)
"<sip:proxy1.example.com;lr>, <sip:proxy2.example.com;lr>"

new(uri, display_name \\ nil, parameters \\ %{})

@spec new(String.t() | Parrot.Sip.Uri.t(), String.t() | nil, map()) :: t()

Creates a new Route header.

Examples

iex> Parrot.Sip.Headers.Route.new("sip:proxy.example.com;lr")
%Parrot.Sip.Headers.Route{display_name: nil, uri: "sip:proxy.example.com;lr", parameters: %{}}

iex> Parrot.Sip.Headers.Route.new("sip:proxy.example.com;lr", "Example Proxy")
%Parrot.Sip.Headers.Route{display_name: "Example Proxy", uri: "sip:proxy.example.com;lr", parameters: %{}}

parse(string)

@spec parse(String.t()) :: t()

Parses a Route header string into a Route struct.

Examples

iex> Parrot.Sip.Headers.Route.parse("<sip:proxy.example.com;lr>")
%Parrot.Sip.Headers.Route{display_name: nil, uri: "sip:proxy.example.com;lr", parameters: %{}}

iex> Parrot.Sip.Headers.Route.parse("Example Proxy <sip:proxy.example.com;lr>")
%Parrot.Sip.Headers.Route{display_name: "Example Proxy", uri: "sip:proxy.example.com;lr", parameters: %{}}

iex> Parrot.Sip.Headers.Route.parse(""Complex Name" <sip:proxy.example.com;lr>;param=value")
%Parrot.Sip.Headers.Route{display_name: "Complex Name", uri: "sip:proxy.example.com;lr", parameters: %{"param" => "value"}}

parse_list(string)

@spec parse_list(String.t()) :: [t()]

Parses a list of Route headers.

Examples

iex> Parrot.Sip.Headers.Route.parse_list("<sip:proxy1.example.com;lr>, <sip:proxy2.example.com;lr>")
[
  %Parrot.Sip.Headers.Route{display_name: nil, uri: "sip:proxy1.example.com;lr", parameters: %{}},
  %Parrot.Sip.Headers.Route{display_name: nil, uri: "sip:proxy2.example.com;lr", parameters: %{}}
]