# Demo Binaries

## Overview

The repository provides receiver-focused demo binaries:

- `mcrx_recv`
- `mcrx_tokio_recv` (with `--features tokio`)
- `mcrx_recv_meta`
- `mcrx_raw_recv` (with `--features raw-packets`)

These are intended for real-network testing and API validation.

## Receiver

```bash
cargo run --bin mcrx_recv -- <group> <dst_port> [source] [interface]
```

Examples:

```bash
cargo run --bin mcrx_recv -- 239.1.2.3 5000
cargo run --bin mcrx_recv -- 232.1.2.3 5000 192.168.1.10
cargo run --bin mcrx_recv -- 232.1.2.3 5000 192.168.1.10 192.168.1.20
cargo run --bin mcrx_recv -- ff01::1234 5000
cargo run --bin mcrx_recv -- ff01::1234 5000 --interface ::1
cargo run --bin mcrx_recv -- ff31::8000:1234 5000 fd06:ba51:f296:0:1caf:6b66:e6f7:4b10 --interface fd06:ba51:f296:0:1caf:6b66:e6f7:4b10
```

Argument meaning:

- `group` → multicast group address
- `dst_port` → destination UDP port
- `source` → optional SSM source address
- `interface` → optional local interface address

## Tokio Receiver

```bash
cargo run --features tokio --bin mcrx_tokio_recv -- <group> <dst_port> [source] [interface]
```

This variant extracts the joined subscription from the `Context`, wraps it in
`TokioSubscription`, and awaits packets asynchronously.

Example:

```bash
cargo run --features tokio --bin mcrx_tokio_recv -- 239.1.2.3 5000
```

## Metadata-aware Receiver

```bash
cargo run --bin mcrx_recv_meta -- <group> <dst_port> [source] [interface]
```

This variant uses `try_recv_any_with_metadata()` and prints the optional
receive metadata alongside each packet.

Example:

```bash
cargo run --bin mcrx_recv_meta -- 239.1.2.3 5000
cargo run --bin mcrx_recv_meta -- ff01::1234 5000 --interface ::1
cargo run --bin mcrx_recv_meta -- ff3e::8000:1234 5000 <sender-ipv6> --interface <receiver-ipv6>
```

## IPv6 SSM Tips

Use [IPv6 Multicast](ipv6.md) for the full group scope and interface-selection
rules. The important receiver-side split is:

- `source` means the sender's IP address.
- `--interface` means the receiver's local join interface.

Cross-machine IPv6 SSM example:

```bash
cargo run --bin mcrx_recv_meta -- ff3e::8000:1234 5000 <sender-ipv6> --interface <receiver-ipv6>
```

## Raw Packet Receiver

```bash
cargo run --features raw-packets --bin mcrx_raw_recv -- <group> [source] [interface]
```

Examples:

```bash
cargo run --features raw-packets --bin mcrx_raw_recv -- 239.1.2.3 --interface 192.168.1.20
cargo run --features raw-packets --bin mcrx_raw_recv -- ff3e::8000:1234 --interface 7
```

Raw receive has platform-specific privilege and support boundaries. See
[Raw Packet Receive](raw-packets.md).

## Receiver Metrics

When built with `--features metrics`, `mcrx_recv` can emit periodic delta-based
metrics summaries.

### Environment variables

`MCRX_METRICS_SUMMARY_SECS`

```bash
MCRX_METRICS_SUMMARY_SECS=2
```

`MCRX_METRICS_SUMMARY_FILE`

```bash
MCRX_METRICS_SUMMARY_FILE=metrics.jsonl
```

`MCRX_METRICS_NODE_ID`

```bash
MCRX_METRICS_NODE_ID=client-0001
```

`MCRX_METRICS_FLAGS_JSON`

```bash
MCRX_METRICS_FLAGS_JSON='{"transport":"quic","experiment":"baseline-a"}'
```

### Example usage

Print summaries to the terminal:

```bash
MCRX_METRICS_SUMMARY_SECS=2 cargo run --features metrics --bin mcrx_recv -- 239.1.2.3 5000
```

Write summaries to a file:

```bash
MCRX_METRICS_SUMMARY_SECS=2 MCRX_METRICS_SUMMARY_FILE=metrics.jsonl cargo run --features metrics --bin mcrx_recv -- 239.1.2.3 5000
```

Write single-header JSONL with explicit node metadata:

```bash
MCRX_METRICS_SUMMARY_SECS=2 \
MCRX_METRICS_SUMMARY_FILE=results/client-0001/network.jsonl \
MCRX_METRICS_FLAGS_JSON='{"experiment":"baseline-a"}' \
cargo run --features metrics --bin mcrx_recv -- 239.1.2.3 5000
```

## Notes

- `mcrx_recv` uses a simple non-blocking polling loop
- `mcrx_tokio_recv` demonstrates the optional Tokio adapter and subscription handoff path
- `mcrx_recv_meta` is useful when validating interface-sensitive metadata wiring
