tokio-multicast 0.7.2

Small Tokio helpers for UDP multicast send/receive.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# tokio-multicast

Tokio-native helpers for UDP multicast.

## Status

Implemented now:

- builder-based socket construction
- IPv4 ASM join, send, receive, and dynamic leave
- basic packet metadata via `recv_datagram()`
- platform split under `src/sys/`

Not implemented yet:

- source-specific multicast data path
- rich destination/interface receive metadata
- full stream integration with `tokio-stream`

## Crate layout

This crate follows the structure proposed in `internal-impl.MD`:

- `builder.rs` for high-level construction
- `config.rs` for configuration state
- `error.rs` for multicast-specific errors
- `interface.rs` and `membership.rs` for multicast intent types
- `packet.rs` for received datagram metadata
- `socket.rs` for the async multicast socket
- `stream.rs` for stream-style consumption helpers
- `raw.rs` and `sys/*` for socket setup and platform adaptation

## Quick start

```rust
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use tokio_multicast::MulticastSocket;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let socket = MulticastSocket::builder()
        .bind(SocketAddr::from((Ipv4Addr::UNSPECIFIED, 46053)))
        .join(IpAddr::V4(Ipv4Addr::new(239, 1, 1, 10)))
        .build()
        .await?;

    socket.send_to_group(b"hello multicast").await?;
    Ok(())
}
```

## Examples

- `cargo run --example simple_receiver`
- `cargo run --example simple_sender`
- `cargo run --example send_and_receive`
- `cargo run --example diagnostics`
- `cargo run --example multi_group`
- `cargo run --example ssm`

`simple_receiver` blocks waiting for multicast traffic. `send_and_receive` demonstrates the full path in one process. `diagnostics` prints a quick environment support report. `ssm` is intentionally a placeholder example that currently demonstrates the not-yet-implemented path.

## Diagnostics

Use `tokio_multicast::diagnose_multicast()` when you want a quick environment check before debugging higher-level multicast behavior.
If you need to control groups, interface index, or timeout, use `diagnose_multicast_with_config(...)`.

```rust
let report = tokio_multicast::diagnose_multicast();
println!("overall supported: {}", report.supported());
println!("ipv4: {:?}", report.ipv4.stages);
println!("ipv4 details: {:?}", report.ipv4.details);
println!("ipv6: {:?}", report.ipv6.stages);
println!("ipv6 details: {:?}", report.ipv6.details);
```

Example commands:

- `cargo run --example diagnostics`
- `cargo run --example diagnostics -- --json`
- `cargo run --example diagnostics -- --ipv4-only`
- `cargo run --example diagnostics -- --ipv6-only`
- `cargo run --example diagnostics -- --timeout-ms 1000`
- `cargo run --example diagnostics -- --ipv4-group 239.1.1.250 --ipv6-group ff02::114`

Exit codes:

- `0`: selected probes succeeded
- `2`: selected probes did not succeed

## Testing

- `cargo test`
- `cargo test --examples`
- `cargo test --doc`