Parrot.Sip.Branch (Parrot Platform v0.0.1-alpha.2)

Module for generating and working with SIP branch parameters for Via headers.

The branch parameter is a unique identifier used in the Via header of SIP messages to identify transactions. As specified in RFC 3261, the branch parameter in SIP requests must start with the magic cookie "z9hG4bK" to be compliant with RFC 3261.

The branch parameter is crucial for:

  • Transaction identification and matching
  • Loop detection in SIP networks
  • Stateless processing of SIP messages

References:

  • RFC 3261 Section 8.1.1.7: Via
  • RFC 3261 Section 17.2.3: Matching Requests to Server Transactions
  • RFC 3261 Section 20.40: Via Header Field

Summary

Types

t()

Functions

ensure_rfc3261_compliance(branch)

Ensures a branch parameter is RFC 3261 compliant by adding the magic cookie if it's missing.

generate()

Generates a unique branch parameter for a Via header. The branch parameter will start with the RFC 3261 magic cookie "z9hG4bK".

generate_for_message(method, request_uri, from_tag, to_tag, call_id)

Generates a unique branch parameter for a Via header based on the given SIP message properties for loop detection.

is_rfc3261_compliant?(branch)

Checks if a branch parameter is RFC 3261 compliant.

same_transaction?(branch1, branch2)

Checks if two branch parameters refer to the same transaction.

transaction_id(branch)

Extracts the transaction identifier part from a branch parameter. This is the part after the magic cookie.

Types

t()

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

Functions

ensure_rfc3261_compliance(branch)

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

Ensures a branch parameter is RFC 3261 compliant by adding the magic cookie if it's missing.

Examples

iex> Parrot.Sip.Branch.ensure_rfc3261_compliance("abc123")
"z9hG4bKabc123"

iex> Parrot.Sip.Branch.ensure_rfc3261_compliance("z9hG4bKabc123")
"z9hG4bKabc123"

generate()

@spec generate() :: t()

Generates a unique branch parameter for a Via header. The branch parameter will start with the RFC 3261 magic cookie "z9hG4bK".

Examples

iex> branch = Parrot.Sip.Branch.generate()
iex> String.starts_with?(branch, "z9hG4bK")
true

generate_for_message(method, request_uri, from_tag, to_tag, call_id)

@spec generate_for_message(
  atom(),
  String.t(),
  String.t(),
  String.t() | nil,
  String.t()
) :: t()

Generates a unique branch parameter for a Via header based on the given SIP message properties for loop detection.

This function creates a deterministic branch parameter based on key message properties, which helps with loop detection as described in RFC 3261 Section 16.6.

Parameters

  • method: The SIP method (atom) of the request
  • request_uri: The request URI as a string
  • from_tag: The tag parameter from the From header
  • to_tag: The tag parameter from the To header (may be nil)
  • call_id: The Call-ID header value

Examples

iex> Parrot.Sip.Branch.generate_for_message(:invite, "sip:alice@example.com", "123", nil, "abc@example.com")
"z9hG4bK" <> _rest

is_rfc3261_compliant?(branch)

@spec is_rfc3261_compliant?(String.t()) :: boolean()

Checks if a branch parameter is RFC 3261 compliant.

Examples

iex> Parrot.Sip.Branch.is_rfc3261_compliant?("z9hG4bKabc123")
true

iex> Parrot.Sip.Branch.is_rfc3261_compliant?("123456")
false

same_transaction?(branch1, branch2)

@spec same_transaction?(String.t(), String.t()) :: boolean()

Checks if two branch parameters refer to the same transaction.

Examples

iex> Parrot.Sip.Branch.same_transaction?("z9hG4bKabc123", "z9hG4bKabc123")
true

iex> Parrot.Sip.Branch.same_transaction?("z9hG4bKabc123", "abc123")
true

iex> Parrot.Sip.Branch.same_transaction?("z9hG4bKabc123", "z9hG4bKdef456")
false

transaction_id(branch)

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

Extracts the transaction identifier part from a branch parameter. This is the part after the magic cookie.

Examples

iex> Parrot.Sip.Branch.transaction_id("z9hG4bKabc123")
"abc123"

iex> Parrot.Sip.Branch.transaction_id("abc123")
"abc123"