mctx-core

mctx-core is a runtime-agnostic multicast sender library for IPv4 and IPv6 ASM/SSM-style traffic.

The default API focuses on lightweight UDP multicast send with explicit socket ownership, deterministic source/interface control, and non-blocking operation. Optional features add Tokio integration, metrics, multicast raw-IP forwarding, generic raw-IP control transmit, and Python bindings without changing the default UDP send path.

Highlights

• IPv4 and IPv6 multicast send support
• Explicit separation between sender source address and outgoing interface
• Exact IPv4 or IPv6 local bind control for announce-style senders
• Predictable IPv6 destination scope handling for ff31 / ff32 vs ff35 / ff38 / ff3e
• Non-blocking send API with caller-owned context and socket extraction
• Caller-provided socket support
• Optional tokio, metrics, raw-packets, and raw-ip features
• Optional Python bindings in the sibling mctx-core-py crate

Install

cargo add mctx-core

The minimum supported Rust version is 1.88.

Optional feature examples:

cargo add mctx-core --features tokio
cargo add mctx-core --features metrics
cargo add mctx-core --features raw-packets
cargo add mctx-core --features raw-ip

Python bindings are covered in the Python Bindings guide; the binding crate lives in the repository's mctx-core-py workspace directory.

Quick Start

use mctx_core::{Context, PublicationConfig};
use std::net::Ipv4Addr;

let mut ctx = Context::new();
let id = ctx.add_publication(
    PublicationConfig::new(Ipv4Addr::new(239, 1, 2, 3), 5000)
        .with_source_addr(Ipv4Addr::new(192, 168, 1, 10))
        .with_ttl(8),
)?;

let report = ctx.send(id, b"hello multicast")?;
println!("sent {} bytes to {}", report.bytes_sent, report.destination);
println!("wire source {:?}", report.source_addr);

For IPv6 examples, source/interface rules, and CLI commands, see IPv6 Multicast and Demo Binaries.

Feature Map

• tokio: async send wrapper for extracted publications.
• metrics: snapshots, deltas, samplers, and Heimdall-style JSONL helpers.
• raw-packets: complete multicast IP datagram transmit for AMT-style use cases.
• raw-ip: complete unicast or multicast IP datagram transmit for caller-built control traffic such as ICMP Packet Too Big.
• mctx-core-py: sibling workspace crate with Python and asyncio bindings.

Documentation

• Usage Guide: core Rust sender API flow.
• IPv6 Multicast: source vs interface, scopes, and SSM group rules.
• Raw Packet Transmit: raw-packets API and platform limits.
• Raw IP Control Transmit: raw-ip API and platform limits.
• Demo Binaries: sender CLI commands and metrics examples.
• Metrics: snapshot, delta, and JSONL semantics.
• Python Bindings: Python API and asyncio helper.
• Architecture: main types and module layout.
• Design Decisions: why the API is shaped this way.

Platform Support

The default UDP send path supports IPv4 and IPv6 multicast on the same platforms.

Raw multicast IP datagram transmit is available behind the raw-packets feature. Linux and macOS support raw IPv4 and IPv6 transmit. Windows currently supports raw IPv4 transmit only. Linux uses packet-socket injection when an IPv6 datagram source differs from the configured local bind, preserving the complete header for AMT forwarding. Linux and macOS use the host raw-IPv6 path for matching local sources; that path preserves the source/group tuple and transport header while the kernel rebuilds the base IPv6 header. macOS returns an explicit unsupported error for remote-source IPv6 injection.

Generic raw-IP control transmit is available behind the independent raw-ip feature. It accepts a complete caller-supplied unicast or multicast datagram. Linux and macOS support IPv4 IP_HDRINCL-style transmit and an explicit kernel-built IPv6 base-header path. Windows supports IPv4 only; raw IPv6 returns an explicit unsupported error. See Raw IP Control Transmit for source-preservation and privilege requirements.

License

BSD 2-Clause