# enigma-rtc

Lightweight Rust crate providing deterministic signaling, a guarded call session state machine, and a pluggable WebRTC engine wrapper for Enigma Messenger and other applications.

## Scope and Non-Goals

- Handles SDP offer/answer creation, ICE candidate validation, and state tracking for incoming/outgoing calls.
- Emits events through an async queue so app code can forward ICE candidates or react to lifecycle changes.
- Supplies a mockable `RtcEngine` trait plus a default `WebRtcEngine` implementation built on webrtc-rs.
- Does **not** include media encryption, signaling transport, or persistence of call logs.
- Does **not** handle messaging payloads; it focuses purely on media session orchestration.

## Quickstart

```rust
use enigma_rtc::{CallSession, RtcConfig, SignalingMessage};
use tokio::task;

let session = CallSession::new(RtcConfig::default()).unwrap();
let offer = session.create_offer().unwrap();
let payload = match offer { SignalingMessage::Offer { sdp } => sdp, _ => unreachable!() };
send_to_remote(payload); // signaling transport defined by the host app

// in parallel, forward local events over signaling
let forwarder = task::spawn(async move {
    loop {
        let event = session.next_event().await?;
        handle_local_event(event);
    }
});

// when an answer arrives from the remote peer
session.accept_answer(remote_answer_sdp).unwrap();
```

## State Machine Overview

1. `Idle` – no call in progress.
2. `CreatingOffer` – generating an SDP offer locally.
3. `WaitingAnswer` – outbound call waiting for remote answer.
4. `IncomingOffer` – inbound call accepted locally, awaiting confirmation.
5. `Connected` – both peers share negotiated media parameters.
6. `Ending` – hangup initiated locally or remotely.
7. `Ended` – resources released; further actions require a new session.

State transitions are validated at every API boundary to ensure deterministic behavior even when the signaling layer retries messages or receives out-of-order events.

## More Information

- [Design](docs/design.md)
- [Signaling](docs/signaling.md)
- [API](docs/api.md)
- [Testing](docs/testing.md)
