prolink_capture/lib.rs
1// SPDX-License-Identifier: GPL-3.0-only
2
3//! Reading Pro DJ Link traffic out of pcap and pcapng captures.
4//!
5//! Every codec in this workspace can be exercised against **real Pioneer
6//! traffic** with no hardware attached, and this crate is what makes that
7//! possible. The distinction matters: a round-trip test between our encoder
8//! and our decoder proves they agree with each other, which is not the same as
9//! agreeing with a CDJ. A capture is the only thing that can tell the two
10//! apart, and the reference implementation this project replaces had an
11//! encoder and a decoder that agreed perfectly on a bug.
12//!
13//! Nothing here knows what a Pro DJ Link message is. This is link and
14//! transport only — Ethernet, IPv4, UDP, TCP — and the magic check belongs to
15//! whoever asked for the bytes.
16//!
17//! # The trap: filter on the destination port
18//!
19//! The Pro DJ Link type byte at offset `0x0a` is **shared across UDP ports and
20//! the layouts behind it are not**. `0x06` is a keep-alive on 50000 and a
21//! media response on 50002; `0x0a` is a hello on 50000 and a player status on
22//! 50002. So a corpus filter of "either endpoint is 50002" is wrong: a tool
23//! that binds one socket and sends its keep-alives *from* 50002 contributes
24//! packets that the filter accepts and the 50002 decoder reads as confident
25//! nonsense — the right number of bytes, plausible values, no error anywhere.
26//!
27//! Filter on where a packet was **going**, which is the only thing that says
28//! which protocol wrote it. [`Capture::udp_to`] is the whole of the intended
29//! API for this, and there is deliberately no source-port equivalent.
30//!
31//! Real hardware hides the mistake well. Of the 35 103 datagrams in this
32//! project's corpus addressed to 50002, only 24 were sent *from* 50002,
33//! because a CDJ sends each status packet from a different, incrementing
34//! source port. A source-port filter therefore finds nothing at all, and an
35//! either-endpoint filter looks correct right up until a second tool joins the
36//! network.
37//!
38//! **TCP is the other way round.** A UDP datagram is a thing with a
39//! destination; a TCP connection is a thing with two ends, and both directions
40//! of a dbserver conversation belong to the server's port. So
41//! [`tcp::Reassembler::on_ports`] matches either endpoint, and says so.
42//!
43//! # Reading a capture
44//!
45//! ```no_run
46//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
47//! use prolink_capture::Capture;
48//!
49//! for packet in Capture::open("run.pcap")?.udp_to(50000) {
50//! let packet = packet?;
51//! println!("{} sent {} bytes", packet.source, packet.payload.len());
52//! }
53//! # Ok(())
54//! # }
55//! ```
56//!
57//! Reassembling the dbserver conversations in one:
58//!
59//! ```no_run
60//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
61//! use prolink_capture::{Capture, tcp::Reassembler};
62//!
63//! let mut reassembler = Reassembler::new();
64//! for packet in Capture::open("run.pcap")? {
65//! reassembler.push(&packet?);
66//! }
67//! for stream in reassembler.finish() {
68//! // `None` means a segment is missing: the dbserver protocol has no
69//! // framing, so concatenating across the hole would silently desynchronise
70//! // every message after it.
71//! if let Some(bytes) = stream.contiguous() {
72//! println!("{:?}: {} bytes", stream.flow(), bytes.len());
73//! }
74//! }
75//! # Ok(())
76//! # }
77//! ```
78//!
79//! # Scope
80//!
81//! Ethernet over IPv4, UDP and TCP, and IP fragment reassembly, which is not
82//! optional: a CDJ's NFS reads come back as five or six fragments each and a
83//! reader that ignored them would under-report every transfer without saying
84//! so. Frames from a link layer this crate does not dissect are an error and
85//! not an empty result, because an empty result is indistinguishable from a
86//! capture of a quiet network.
87
88// Tests are allowed to panic: an assertion *is* the failure mode, and a test
89// that carefully propagated errors would report them as passes.
90#![cfg_attr(
91 test,
92 allow(
93 clippy::unwrap_used,
94 clippy::expect_used,
95 clippy::panic,
96 clippy::indexing_slicing,
97 clippy::as_conversions
98 )
99)]
100
101mod capture;
102mod corpus;
103mod error;
104mod packet;
105mod sparse;
106pub mod tcp;
107
108pub use capture::{Capture, Format, UdpTo};
109pub use corpus::{CORPUS_ENV, Corpus};
110pub use error::{Error, Result};
111pub use packet::{Flow, Packet, Transport};
112pub use sparse::{Gap, Run};
113
114/// The port a Pioneer device announces itself on, broadcast.
115///
116/// Named here so a caller filtering a corpus does not have to write the number
117/// out, and so that the name sits next to the warning about which end of the
118/// packet to match it against. See [`Capture::udp_to`].
119pub const DISCOVERY_PORT: u16 = 50000;
120
121/// The port beat packets are broadcast to.
122pub const BEAT_PORT: u16 = 50001;
123
124/// The port player status, media queries and settings queries are unicast to.
125pub const STATUS_PORT: u16 = 50002;