Struct TransactionKey

pub struct TransactionKey {
    pub branch: String,
    pub method: Method,
    pub is_server: bool,
}

Uniquely identifies a SIP transaction.

According to RFC 3261, Section 17, the transaction identifier is a combination of:

1. The branch parameter in the top-most Via header.
2. The Method of the request (e.g., INVITE, REGISTER).
3. Whether the transaction is a client or server transaction.

RFC 3261 Transaction Matching Rules

RFC 3261 Section 17.1.3 states that a response matches a client transaction if:

1. The response has the same value of the branch parameter in the top Via header field as the branch parameter in the top Via header field of the request that created the transaction.

2. The method parameter in the CSeq header field matches the method of the request that created the transaction. This is necessary because a CANCEL request constitutes a different transaction but shares the same value of the branch parameter.

RFC 3261 Section 17.2.3 states that a request matches a server transaction if:

1. The request has the same branch parameter in the top Via header field as the branch parameter in the top Via header field of the request that created the transaction.

2. The request method matches the method of the request that created the transaction, except for ACK, where the method of the request that created the transaction is INVITE.

Implementation Notes

This TransactionKey struct simplifies these rules by using the branch string, the method, and an is_server boolean flag to ensure uniqueness within a single transaction manager instance. It assumes the branch parameter is generated according to RFC 3261 to be sufficiently unique.

Fields

branch: String

The value of the branch parameter from the top-most Via header. This is a critical part of the transaction identifier.

method: Method

The SIP method of the request that initiated or is part of the transaction (e.g., INVITE, ACK, BYE). This is important because a request with the same branch but different method (e.g., an INVITE and a CANCEL for that INVITE) can belong to different transactions or be processed in context of the same INVITE transaction depending on rules. However, for keying, RFC3261 implies INVITE and non-INVITE transactions are distinct even with the same branch.

is_server: bool

Distinguishes between client and server transactions. true if this key represents a server transaction, false for a client transaction. This is necessary because a User Agent can be both a client and a server, and might (though unlikely with proper branch generation) encounter or generate messages that could lead to key collisions if this flag were not present.

Implementations

impl TransactionKey

pub fn new(branch: String, method: Method, is_server: bool) -> TransactionKey

Creates a new TransactionKey.

Arguments

• branch - The branch parameter string.
• method - The SIP method associated with the transaction.
• is_server - true if this is a server transaction, false otherwise.

pub fn from_request(request: &Request) -> Option<TransactionKey>

Attempts to create a TransactionKey for a server transaction from an incoming request.

Extracts the branch parameter from the top-most Via header and the request’s method. Sets is_server to true.

RFC 3261 Context

RFC 3261 Section 17.2.3 specifies that a server transaction is identified by the branch parameter in the top Via header field of the request. This method implements that rule by extracting the branch parameter and creating a server transaction key.

Returns

Some(TransactionKey) if the top Via header and its branch parameter are present. None otherwise (e.g., malformed request, no Via, or Via without a branch).

pub fn from_response(response: &Response) -> Option<TransactionKey>

Attempts to create a TransactionKey for a client transaction from an outgoing response.

Extracts the branch parameter from the top-most Via header (which was added by this client) and the method from the CSeq header of the response (which corresponds to the original request method). Sets is_server to false.

RFC 3261 Context

RFC 3261 Section 17.1.3 specifies that a response matches a client transaction if:

1. The branch parameter in the top Via header matches the transaction’s branch
2. The method in the CSeq header matches the transaction’s original request method

This method implements these rules by extracting both values from the response.

Returns

Some(TransactionKey) if the top Via (with branch) and CSeq (with method) headers are present. None otherwise.

pub fn branch(&self) -> &str

Returns the branch parameter of the transaction key.

pub fn method(&self) -> &Method

Returns the method associated with the transaction key.

pub fn is_server(&self) -> bool

Returns true if the key is for a server transaction, false otherwise.

pub fn with_method(&self, method: Method) -> TransactionKey

Returns a new TransactionKey with a different method but the same branch and is_server values.

RFC 3261 Context

This is useful for creating related transaction keys, such as when handling a CANCEL request for an INVITE transaction. According to RFC 3261 Section 9.1, a CANCEL request has the same branch parameter as the request it cancels, but constitutes a separate transaction.

Trait Implementations

impl Clone for TransactionKey

fn clone(&self) -> TransactionKey

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TransactionKey

Provides a human-readable debug representation of the TransactionKey. Format: “branch_value:METHOD:side” (e.g., “z9hG4bK123:INVITE:server”)

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for TransactionKey

Provides a human-readable display representation of the TransactionKey. Format: “branch_value:METHOD:side” (e.g., “z9hG4bK123:INVITE:server”)

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl FromStr for TransactionKey

Implements the FromStr trait for TransactionKey to allow parsing from strings. This handles both display and debug format strings.

Format

The accepted formats are:

• “branch:METHOD:side” (Debug format)
• “Key(branch:METHOD:side)” (Display format)

Where side is “server” or “client”

type Err = String

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<TransactionKey, <TransactionKey as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for TransactionKey

Implements hashing for TransactionKey. The hash is derived from the branch, method, and is_server fields. This allows TransactionKey to be used in hash-based collections like HashMap or HashSet.

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for TransactionKey

Implements equality for TransactionKey. Two keys are equal if their branch, method, and is_server fields are all equal.

fn eq(&self, other: &TransactionKey) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for TransactionKey

Marks TransactionKey as implementing full equality.