Crate sipx_ua 

SIP user agent: registration, authentication, and answering what arrives.

This crate sits on sipx-transport and turns transactions into the things a phone or a service actually does. Digest authentication and registration leases live here because both are about state over time rather than about a single message, which is what separates a user agent from a transaction layer.

Dialogs and calls are the next layer up, in sipx-call.

Without a runtime

Digest is hashing and header text, and a caller whose decision logic touches no IO must be able to use it without linking one. default-features = false drops the runtime feature and with it the modules that drive a socket — agent, flows, and the error type that wraps a transport failure — leaving auth, challenge, gruu, identity, outbound, push and registrar. Identity signing and verification take caller-supplied time, authority policy, and credential acquisition, so they remain usable without a runtime as well. The alternative for such a caller is to write digest or identity processing a second time, and two implementations of one algorithm eventually disagree about who is authenticated.

Stability

sipx is pre-1.0, so neither word below means frozen. 1.0.0 is what freezes an API, and its predicates are in docs/roadmap.md. Until then:

• Supported — meant to be depended on. Breaking changes get a CHANGELOG.md entry saying what to do instead. New enum variants and new struct fields may still appear in a minor release, so a downstream match should carry a _ arm.
• Experimental — may change shape or be removed without a migration note. Depend on it only if you are prepared to follow it.

Supported: registration leases, digest authentication, authenticated caller identity, Path, Service-Route, registering as one Outbound flow, push, and the subscription store plus built-in dialog, registration and presence package documents selected by sipx-call::Notifier. S-34 gives identity its caller: outbound and inbound policies in sipx-call select the authentication and verification services. S-29 is what gives Outbound and push their callers — sipx register --outbound and --push-provider/--push-prid — and it is why X-37 had demoted their compliance rows in the first place.

Which application backs that claim, stated because the two are not the same (X-38). Every Registration, Outbound and push are called by sipx-cli, while authenticated identity is called by sipx-call, which is itself the call framework used by sipx-app. The host uses only this crate’s answering half directly: Host::agent_config builds a Config to answer OPTIONS with and names the listener’s own address as a registrar that nothing ever sends to, so register is never called. X-38 defines the call-reachable surface as what the host uses, and registration is not call-reachable in principle rather than by omission — it happens before and outside any call. So the registration claim rests on A-8’s other rule: the CLI’s promise is its command-line surface, documented in website/docs/reference/cli.md and asserted by tests/cli.rs. scripts/check-app-surface.py checks that citation rather than trusting it, so this paragraph cannot rot into a claim with no caller at all. Push is earned in full: the pn-* parameters, §8.2’s answer read back, and §4.1.3’s refresh through UserAgent::woken. Outbound is earned only as far as the registration goes, which is what the wording above says and no further.

Experimental: event_client and publication_client. They are public and tested. event_client is the bounded sans-I/O subscriber driven by sipx-call::EventSubscriptions, and sipx-call::Publications carries the publication core and exact compositor through live endpoints. The bounded reginfo consumer is reached by sipx peers --registrar; no CLI command publishes, and published presence is not automatically projected into later NOTIFY documents. Their pre-1.0 API shape is still soft.

By that same rule, and named here rather than left for a reader to discover: the rest of Outbound is experimental too. Flows and Attempt — one registration per outbound proxy, each flow failing independently under §4.5’s backoff — plus UserAgent::keepalive_after (§4.4) and UserAgent::dialog_contact’s ob parameter (§4.3) are exercised by this crate’s own tests and by nothing above them. sipx register places a single flow and does not hold it open, so those shapes have never been constrained by a caller either.

Re-exports

pub use agent::Config;

pub use agent::Flow;

pub use agent::UserAgent;

pub use challenge::Authenticator;

pub use challenge::Presented;

pub use challenge::Reason;

pub use challenge::Verdict;

pub use error::Error;

pub use error::Result;

pub use flows::Attempt;

pub use flows::Flows;

pub use gruu::Gruus;

pub use gruu::Kind as GruuKind;

pub use history::RetargetError;

pub use history::retarget;

pub use outbound::InstanceId;

pub use outbound::Keepalive;

pub use outbound::Power;

pub use outbound::RegId;

pub use push::Pending;

pub use push::PushService;

pub use push::Support;

pub use registrar::Lease;

pub use registrar::Outcome;

pub use registrar::PathSet;

pub use registrar::Registered;

pub use registrar::Registration;

pub use registrar::RegistrationObservation;

pub use registrar::RegistrationObservationError;

pub use registrar::ServiceRoute;

Modules

agent

The user agent: registering, keeping registered, and answering what arrives.

auth

Shared HTTP Digest authentication for SIP.

challenge

The server side of digest authentication (RFC 7616, RFC 8760).

error

User agent errors.

event_client

Sans-I/O subscriber state for SIP event packages (RFC 6665).

flows

Several registrations for one device, one per flow (RFC 5626 §4.2).

gruu

GRUUs: obtaining them from a registrar, and choosing which one to use (RFC 5627).

history

User-agent retargeting with RFC 7044 diversion history.

identity

RFC 8224 authentication and verification services.

outbound

Client-initiated connections — Outbound (RFC 5626).

packages

The two event packages that report state sipx already keeps (RFC 4235, RFC 3680).

presence

Presence, and publishing it (RFC 3856, RFC 3863, RFC 3903).

publication_client

Sans-I/O event-state publisher (RFC 3903).

push

Being reachable through a push notification (RFC 8599), from the user agent’s side.

reginfo

Bounded RFC 3680 registration-information consumer.

registrar

Registration (RFC 3261 §10): telling a registrar where to reach you, and keeping it told.

subscribe

The subscriptions a notifier is serving (RFC 6665).

Structs

Challenge

A challenge from a WWW-Authenticate or Proxy-Authenticate header.

Credentials

What a user knows.

Enums

Algorithm

Which digest algorithm a challenge asks for.