<h1 align="center">
 <a href="https://webrtc.rs"><img src="https://raw.githubusercontent.com/webrtc-rs/sansio/master/sansio-black.png" alt="sansio"></a>
 <br>
</h1>
<p align="center">
 <a href="https://github.com/webrtc-rs/sansio/actions">
  <img src="https://github.com/webrtc-rs/sansio/workflows/cargo/badge.svg">
 </a>
 <a href="https://crates.io/crates/sansio">
  <img src="https://img.shields.io/crates/v/sansio.svg">
 </a>
 <a href="https://docs.rs/sansio">
  <img src="https://docs.rs/sansio/badge.svg">
 </a>
 <a href="https://doc.rust-lang.org/1.6.0/complement-project-faq.html#why-dual-mitasl2-license">
  <img src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue" alt="License: MIT/Apache 2.0">
 </a>
</p>
<p align="center">
 Rust in Sans-IO
</p>

# What is Sans-IO?

**Sans-IO** (French for "without I/O") is an architectural pattern for writing protocol implementations that are
completely decoupled from I/O operations. This makes protocols:

- **Testable**: Test protocol logic without mocking sockets or async runtimes
- **Portable**: Run the same protocol code in sync, async, embedded, or WASM environments
- **Composable**: Stack and combine protocol layers easily
- **Debuggable**: Step through protocol state machines without I/O side effects

## Features

- Clean push-pull API for message handling
- Zero-cost abstractions with generic type parameters
- Support for custom events and timeout handling
- Works with any I/O backend (sync, async, embedded)
- No dependencies, minimal footprint
- Fully documented with examples
- **`no_std` by default** - works in any environment

## no_std Support

This crate is `no_std` by default and works seamlessly in any environment - embedded systems,
bare-metal applications, WASM, or standard applications.

### Time Handling

The `Time` associated type is fully generic, so you can use any time representation that fits
your environment:

**Using `std::time::Instant`:**

```rust
impl Protocol<Vec<u8>, Vec<u8>, ()> for MyProtocol {
    type Time = std::time::Instant;
    // ...
}
```

**Using tick counts (embedded):**

```rust
impl Protocol<Vec<u8>, Vec<u8>, ()> for MyProtocol {
    type Time = u64;  // System ticks
    // ...
}
```

**Using milliseconds:**

```rust
impl Protocol<Vec<u8>, Vec<u8>, ()> for MyProtocol {
    type Time = i64;  // Milliseconds since epoch
    // ...
}
```

**No timeout needed:**

```rust
impl Protocol<Vec<u8>, Vec<u8>, ()> for MyProtocol {
    type Time = ();  // Unit type when timeouts aren't used
    // ...
}
```

## The Protocol Trait

The `Protocol` trait provides a simplified Sans-IO interface for building network protocols:

```rust
pub trait Protocol<Rin, Win, Ein> {
    type Rout;  // Output read type
    type Wout;  // Output write type
    type Eout;  // Output event type
    type Error; // Error type
    type Time;  // Time type (u64, Instant, i64, (), etc.)

    // Push data into protocol
    fn handle_read(&mut self, msg: Rin) -> Result<(), Self::Error>;
    fn handle_write(&mut self, msg: Win) -> Result<(), Self::Error>;
    fn handle_event(&mut self, evt: Ein) -> Result<(), Self::Error>;
    fn handle_timeout(&mut self, now: Self::Time) -> Result<(), Self::Error>;

    // Pull results from protocol
    fn poll_read(&mut self) -> Option<Self::Rout>;
    fn poll_write(&mut self) -> Option<Self::Wout>;
    fn poll_event(&mut self) -> Option<Self::Eout>;
    fn poll_timeout(&mut self) -> Option<Self::Time>;

    // Lifecycle
    fn close(&mut self) -> Result<(), Self::Error>;
}
```

## Quick Start

Add `sansio` to your `Cargo.toml`:

```toml
[dependencies]
sansio = "1"
```

## Example: Uppercase Protocol

A simple protocol that converts incoming strings to uppercase:

```rust
use sansio::Protocol;
use std::collections::VecDeque;

#[derive(Debug)]
struct MyError;
impl std::fmt::Display for MyError {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "MyError")
    }
}
impl std::error::Error for MyError {}

/// A simple uppercase protocol: converts incoming strings to uppercase
struct UppercaseProtocol {
    routs: VecDeque<String>,
    wouts: VecDeque<String>,
}

impl UppercaseProtocol {
    fn new() -> Self {
        Self {
            routs: VecDeque::new(),
            wouts: VecDeque::new(),
        }
    }
}

impl Protocol<String, String, ()> for UppercaseProtocol {
    type Rout = String;
    type Wout = String;
    type Eout = ();
    type Error = MyError;
    type Time = ();  // No timeout handling needed

    fn handle_read(&mut self, msg: String) -> Result<(), Self::Error> {
        // Process incoming message
        self.routs.push_back(msg.to_uppercase());
        Ok(())
    }

    fn poll_read(&mut self) -> Option<Self::Rout> {
        // Return processed message
        self.routs.pop_front()
    }

    fn handle_write(&mut self, msg: String) -> Result<(), Self::Error> {
        // For this simple protocol, just pass through
        self.wouts.push_back(msg);
        Ok(())
    }

    fn poll_write(&mut self) -> Option<Self::Wout> {
        self.wouts.pop_front()
    }
}

// Usage example
fn main() {
    let mut protocol = UppercaseProtocol::new();

    // Push data in
    protocol.handle_read("hello world".to_string()).unwrap();

    // Pull results out
    assert_eq!(protocol.poll_read(), Some("HELLO WORLD".to_string()));
}
```

## Testing Made Easy

Sans-IO protocols are trivial to test because they don't involve any I/O:

```rust
#[test]
fn test_uppercase_protocol() {
    let mut protocol = UppercaseProtocol::new();

    // Test single message
    protocol.handle_read("test".to_string()).unwrap();
    assert_eq!(protocol.poll_read(), Some("TEST".to_string()));

    // Test multiple messages
    protocol.handle_read("hello".to_string()).unwrap();
    protocol.handle_read("world".to_string()).unwrap();
    assert_eq!(protocol.poll_read(), Some("HELLO".to_string()));
    assert_eq!(protocol.poll_read(), Some("WORLD".to_string()));
    assert_eq!(protocol.poll_read(), None);
}
```

## Use Cases

- **Network Protocols**: HTTP, WebSocket, custom TCP/UDP protocols
- **Message Parsers**: Protocol buffers, JSON-RPC, custom formats
- **State Machines**: Connection handling, handshakes, negotiations
- **Protocol Testing**: Unit test protocol logic without network I/O
- **Embedded Systems**: Protocols that need to work with both blocking and non-blocking I/O
- **WASM**: Browser-based protocol implementations

## Why Sans-IO?

Traditional protocol implementations mix I/O and protocol logic:

```rust
// Traditional approach - tightly coupled to async I/O
async fn handle_connection(mut stream: TcpStream) {
    let mut buf = [0u8; 1024];
    while let Ok(n) = stream.read(&mut buf).await {
        // Protocol logic mixed with I/O
        let response = process(&buf[..n]);
        stream.write_all(&response).await.unwrap();
    }
}
```

Sans-IO separates concerns:

```rust
// Sans-IO approach - protocol logic is independent
struct MyProtocol {
    /* ... */
}
impl Protocol<Vec<u8>, Vec<u8>, ()> for MyProtocol { /* ... */ }

// I/O layer is separate and can be swapped
async fn handle_connection(mut stream: TcpStream, mut protocol: MyProtocol) {
    let mut buf = [0u8; 1024];
    while let Ok(n) = stream.read(&mut buf).await {
        protocol.handle_read(buf[..n].to_vec()).unwrap();
        while let Some(response) = protocol.poll_write() {
            stream.write_all(&response).await.unwrap();
        }
    }
}
```

Benefits:

- Protocol logic can be tested without async runtime
- Same protocol works with sync, async, or embedded I/O
- Easier to debug and reason about
- Protocol layers can be composed and reused

## Documentation

Full API documentation is available at [docs.rs/sansio](https://docs.rs/sansio)

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](../LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.
