rvoip-sip

rvoip-sip is the application-facing SIP session layer for RVoIP. It coordinates dialog state, registration, media setup, call control, transfer, DTMF, hold/resume, custom SIP headers, and app-visible events so Rust applications can behave like programmable SIP endpoints without owning SIP transaction or RTP details directly.

This crate is currently a beta candidate for bounded SIP client, server, PBX, gateway, and B2BUA scenarios. It is intended for developers who want a Rust-native SIP control surface with runnable examples and explicit interop evidence.

At a glance

Start with Endpoint unless you already know you need event-stream ownership, callback dispatch, or custom multi-leg orchestration. The higher-level surfaces are thin wrappers over UnifiedCoordinator, so applications can move down a level without switching protocol stacks.

Install

rvoip-sip uses the workspace minimum supported Rust version. The current MSRV is Rust 1.88.

[dependencies]
rvoip-sip = "0.2"
tokio = { version = "1", features = ["full"] }

For repository development:

git clone https://github.com/eisenzopf/rvoip.git
cd rvoip
RUSTUP_TOOLCHAIN=1.88 cargo check -p rvoip-sip --all-targets

Quick start

Run a local two-endpoint call first:

cargo run -p rvoip-sip --example endpoint_local_call

For a registered PBX account, the Endpoint facade keeps the application code focused on account setup and call control:

use std::time::Duration;

use rvoip_sip::{Endpoint, EndpointProfile, Result};

# async fn example() -> Result<()> {
let mut endpoint = Endpoint::builder()
    .name("alice")
    .account("1001")
    .password("secret")
    .registrar("sips:pbx.example.com:5061")
    .profile(EndpointProfile::AsteriskTlsSrtpRegisteredFlow)
    .build()
    .await?;

endpoint.register().await?;

let call = endpoint
    .call_and_wait("1002", Some(Duration::from_secs(30)))
    .await?;

call.send_dtmf('1').await?;
call.hangup_and_wait(Some(Duration::from_secs(5))).await?;
endpoint.shutdown().await?;
# Ok(())
# }

See examples/endpoint/03_registered_account/main.rs for the env-driven PBX account runner.

Choose an API surface

SessionHandle is the per-call control object shared by the peer surfaces. It currently exposes deterministic teardown, answered/progress waits, RFC 4733 DTMF, hold/resume, blind transfer, REFER/NOTIFY lifecycle events, SDES-SRTP state, typed per-call events, and decoded/encoded audio frames.

Examples

The examples are organized by developer surface in examples/README.md.

PBX interop setup, environment variables, and scenario coverage are documented in examples/pbx/README.md. The terminal softphone is documented in examples/sip_client/README.md.

Capabilities

• SIP call setup and teardown with registration lifecycle support.
• INVITE, REGISTER, BYE, CANCEL, REFER, NOTIFY, INFO, PRACK, session timer, redirect, provisional response, and glare-retry paths covered by examples or regression fixtures.
• UDP and TLS SIP paths in the beta-candidate evidence set.
• RTP media sessions, bidirectional audio frames, RFC 4733 DTMF, and SDES-SRTP negotiation state.
• Hold/resume, blind transfer, REFER/NOTIFY progress, attended-transfer primitives, and transfer outcome events.
• Builder-shaped outbound requests with custom headers, carry-through reports, header policy enforcement, body helpers, and SIP trace redaction hooks.
• B2BUA and gateway helpers under server::*, including bridge strategy, contact resolution, and transfer orchestration helpers.
• Performance recipes and tuning hooks for local labs, PBX media server profiles, and signaling-heavy test profiles.

Beta-candidate evidence

The beta-candidate gate completed with 0 failures and 0 skips from a clean tree with Rust/Cargo 1.88.0. The full evidence bundle is generated locally under beta-report/ by the gate script (an untracked artifact directory, not part of the repository); the committed performance summary lives in docs/BETA_PERFORMANCE_REPORT.md.

The 24-hour soak is explicitly waived for the beta candidate; the archived 30-minute soak is the accepted beta-candidate bar. For the exact claim boundaries, see:

• docs/BETA_RELEASE_CHECKLIST.md
• docs/COMPATIBILITY_MATRIX.md
• docs/RFC_COMPLIANCE_MATRIX.md
• docs/SECURITY_POSTURE.md
• docs/BETA_PERFORMANCE_REPORT.md
• docs/TOPOLOGY_PROFILES.md
• docs/INTEROP_CI_PLAN.md

Validation and operations

Local development checks:

RUSTUP_TOOLCHAIN=1.88 cargo check -p rvoip-sip --all-targets
crates/sip/rvoip-sip/scripts/beta_gate.sh --local
crates/sip/rvoip-sip/scripts/beta_gate.sh --security

Full external evidence requires the local PBX, SIPp, strict-UA, and performance dependencies used by the gate script:

BETA_RUN_LOCAL_PBX=1 RUSTUP_TOOLCHAIN=1.88 \
  crates/sip/rvoip-sip/scripts/beta_gate.sh --full --require-external

Operational references:

• docs/BENCHMARKING.md for reproducible performance test shapes and artifact conventions.
• docs/TUNING.md for runtime profile and deployment tuning guidance.
• docs/INTEROP_CI_PLAN.md for PBX, SIPp, and strict-UA runner expectations.

Feature flags

Known limits

• This is a beta candidate, not a broad production-readiness claim.
• Carrier SBC readiness is partial and not certified.
• Kamailio/OpenSIPS plus RTPengine are de-scoped from beta-candidate claims.
• WebRTC/browser interop, ICE, TURN, DTLS-SRTP, and WSS outbound are outside the beta-candidate claim unless separately completed and tested.
• The default full-media performance claim is bounded to the documented beta-candidate profiles and artifacts. Higher tuned-profile results need their own topology, hardware, configuration, and caveats.
• Blind transfer is validated; attended transfer is exposed as primitives rather than a full consultation-call workflow.

Contributing

Use the public issue tracker for bugs, interop gaps, and documentation problems: github.com/eisenzopf/rvoip/issues. When reporting SIP interop behavior, include the peer, transport, media security mode, relevant SIP trace, and the smallest command or example that reproduces the behavior.

License

Licensed under the MIT license, See the repository LICENSE.