prolink 0.5.0

Pioneer Pro DJ Link: browse and play from CDJs on the network, and serve a rekordbox medium to them
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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
// SPDX-License-Identifier: GPL-3.0-only

//! Our servers against our clients, over loopback.
//!
//! Every other test in this workspace checks one side of one protocol. This one
//! checks that the halves fit: a real `export.pdb` goes into a `Medium`, the
//! server serves it, the client browses it, and what comes back out is what went
//! in.
//!
//! It is not a substitute for hardware — two implementations agreeing is weaker
//! evidence than one implementation agreeing with a CDJ, and the codecs are
//! separately pinned against 37 captures of real traffic for exactly that
//! reason. What this proves is the wiring: that the server answers the requests
//! the client actually sends, in the shapes it expects, in the order a browse
//! goes in.
//!
//! Nothing here binds a privileged port. The portmapper lives on an ephemeral
//! one, which is why `NfsConfig::portmap_port` is configurable at all — against
//! real hardware it must be 111 or a deck never looks (F46).

// An assertion *is* the failure mode of a test; propagating errors carefully
// would report them as passes.
#![allow(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::panic,
    clippy::indexing_slicing,
    clippy::as_conversions,
    clippy::cast_possible_truncation
)]

use std::net::Ipv4Addr;
use std::path::{Path, PathBuf};
use std::sync::{Arc, RwLock};

use prolink::consume::{DbClient, DbConfig, NfsClient};
use prolink::serve::dbserver::{DbServer, DbServerConfig};
use prolink::serve::nfs::{NfsConfig as ServerNfsConfig, NfsServer};
use prolink::serve::{Medium, ServedSlot, Vfs};
use prolink::{BrowsableDeviceNumber, Slot};
use prolink_proto::dbserver::{
    CamelotKey, Drill, ItemType, MediaInfo, MenuTarget, MessageKind, SortOrder, TrackType,
};
use prolink_rekordbox::Library;

const LOOPBACK: Ipv4Addr = Ipv4Addr::LOCALHOST;

fn export_pdb() -> Vec<u8> {
    let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("../../testdata/export.pdb");
    std::fs::read(path).expect("the committed rekordbox export")
}

fn library() -> Library {
    Library::parse(&export_pdb()).expect("it parses")
}

fn device(number: u8) -> BrowsableDeviceNumber {
    BrowsableDeviceNumber::new(number).expect("a browsable device number")
}

/// A dbserver on an ephemeral port with the real library in the USB slot.
async fn serve_usb() -> (DbServer, u16) {
    let medium = Arc::new(Medium::synthetic(ServedSlot::USB, library(), "TEST STICK"));
    let server = DbServer::start(
        DbServerConfig {
            device: device(4),
            address: LOOPBACK,
            port: 0,
            // 12523 is fixed on the wire and a second test would collide with
            // it; the client is told the port directly instead.
            query_port: None,
        },
        [medium],
    )
    .await
    .expect("the dbserver starts");
    let port = server.port();
    (server, port)
}

async fn client(port: u16) -> DbClient {
    DbClient::connect_at(LOOPBACK, port, device(2), DbConfig::default())
        .await
        .expect("the client connects and introduces itself")
}

#[tokio::test]
async fn a_client_sees_the_root_menu_a_deck_would_see() {
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let root = client.root_menu(Slot::USB).await.expect("the root menu");
    let labels: Vec<&str> = root
        .iter()
        .filter_map(|item| prolink_proto::dbserver::unwrap_menu_label(&item.label1))
        .collect();

    // A deck renders these and nothing else. An unimplemented category and an
    // empty one look identical on its screen, so the set served is a
    // user-visible surface rather than an internal detail.
    for expected in ["ARTIST", "ALBUM", "TRACK", "GENRE", "KEY", "PLAYLIST"] {
        assert!(labels.contains(&expected), "no {expected} in {labels:?}");
    }
    // Category items carry no flags, unlike a track row.
    assert!(
        root.iter().all(|item| item.flags == 0),
        "a category is not openable as a track"
    );
    assert!(
        root.iter().all(|item| item.label1.starts_with('\u{fffa}')),
        "labels must be wrapped, or a deck renders them and then declines to open them (F26)",
    );
}

#[tokio::test]
async fn a_client_can_list_every_track() {
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let tracks = client
        .tracks(Slot::USB, SortOrder::DEFAULT)
        .await
        .expect("the track list");
    assert_eq!(
        tracks.len(),
        library().tracks.len(),
        "every track, paged 64 at a time"
    );
    assert!(
        tracks.iter().all(|item| !item.label1.is_empty()),
        "every row has a title"
    );
}

#[tokio::test]
async fn the_sort_order_selects_the_second_column() {
    // The feature that makes sorting useful rather than cosmetic: an item's type
    // is `(column field type << 8) | 0x04`, so 0x0704 is not "title and artist"
    // but "a track whose second column is the ARTIST field" (F43).
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let by_artist = client
        .tracks(Slot::USB, SortOrder::ARTIST)
        .await
        .expect("sorted by artist");
    let first = by_artist.first().expect("a first row");
    assert_eq!(first.item_type.0 & 0xff, 0x04);
    assert_eq!(
        first.item_type.0 >> 8,
        ItemType::ARTIST.0,
        "column 2 is the artist"
    );

    let by_bpm = client
        .tracks(Slot::USB, SortOrder::BPM)
        .await
        .expect("sorted by BPM");
    let first = by_bpm.first().expect("a first row");
    assert_eq!(
        first.item_type.0 >> 8,
        ItemType::TEMPO.0,
        "column 2 is the tempo"
    );
    assert!(
        first.label2.is_empty(),
        "a numeric column sends an empty label and the raw number in argument 0; the deck \
         formats it",
    );

    let tempos: Vec<u32> = by_bpm.iter().map(|item| item.argument0).collect();
    assert!(
        tempos.windows(2).all(|pair| pair[0] <= pair[1]),
        "and it really is sorted"
    );
}

#[tokio::test]
async fn a_client_can_drill_from_a_category_to_tracks() {
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let artists = client
        .category(Slot::USB, MessageKind::MENU_ARTIST, SortOrder::DEFAULT)
        .await
        .expect("the artists");
    assert!(!artists.is_empty());

    // Drilling one level into an artist gives its albums, not its tracks.
    let artist = artists
        .iter()
        .find(|item| item.id != prolink_proto::dbserver::FILTER_ALL);
    let artist = artist.expect("a real artist, not the ALL row");
    let one_level_into_artist = Drill {
        depth: 1,
        category: u8::try_from(MessageKind::MENU_ARTIST.0 & 0xff).expect("a category byte"),
    };
    let albums = client
        .drill(
            Slot::USB,
            one_level_into_artist,
            SortOrder::DEFAULT,
            &[artist.id],
        )
        .await
        .expect("that artist's albums");
    assert!(
        !albums.is_empty(),
        "an artist with no albums would not be listed"
    );
}

#[tokio::test]
async fn searching_finds_a_track_that_is_there_and_none_that_is_not() {
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let library = library();
    let sample = library
        .tracks
        .values()
        .find(|track| track.title.len() > 4)
        .expect("a track");
    let term: String = sample.title.chars().take(4).collect();

    let found = client
        .search(Slot::USB, &term, SortOrder::DEFAULT)
        .await
        .expect("a search");
    assert!(!found.is_empty(), "searching for {term:?} found nothing");

    let missing = client
        .search(Slot::USB, "zzzzz no such track zzzzz", SortOrder::DEFAULT)
        .await
        .expect("a search that matches nothing is still an answer");
    assert!(missing.is_empty());
}

#[tokio::test]
async fn metadata_and_track_info_describe_the_same_track() {
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let library = library();
    let track = library
        .tracks
        .values()
        .find(|track| !track.title.is_empty() && !track.file_path.is_empty())
        .expect("a track with a title and a path");

    let metadata = client
        .metadata(Slot::USB, track.id)
        .await
        .expect("its metadata");
    assert_eq!(metadata.title, track.title);
    assert_eq!(metadata.artist, track.artist);
    assert_eq!(metadata.album, track.album);
    assert_eq!(metadata.tempo_centibpm, track.tempo);

    let info = client
        .track_info(Slot::USB, track.id)
        .await
        .expect("its track info");
    assert_eq!(info.path, track.file_path);
    // The one field a load needs that browsing does not (F31).
    assert_eq!(
        info.size,
        u64::from(track.file_size),
        "argument 0 of the path item is the size"
    );
    // Item 1 is the container, from pdb row offset 0x5a. The wrong value makes a
    // deck fetch the whole file and then refuse to decode it (F34, F35).
    assert_eq!(info.container, u32::from(track.container.0));
}

#[tokio::test]
async fn a_dip_into_metadata_does_not_lose_the_list_being_scrolled() {
    // A deck does not browse one menu at a time: it dips into metadata and then
    // resumes the list at the next offset *without re-issuing the menu request*.
    // Keying result sets on the item count alone worked until a metadata reply
    // became 13 items and collided with a 13-track album (F27, then F41).
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let all = client
        .tracks(Slot::USB, SortOrder::DEFAULT)
        .await
        .expect("the track list");
    let victim = all.get(5).expect("a sixth row").id;

    let _ = client
        .metadata(Slot::USB, victim)
        .await
        .expect("a dip into metadata");

    let again = client
        .tracks(Slot::USB, SortOrder::DEFAULT)
        .await
        .expect("the list again");
    assert_eq!(again.len(), all.len(), "the list survived the dip");
}

#[tokio::test]
async fn a_list_being_scrolled_survives_a_minute_of_metadata_polling() {
    // What hardware did: while a track played, the deck polled its metadata
    // every couple of seconds, and every poll minted a fresh result set. The
    // menu table evicted by *insertion* order, so after 32 polls it threw away
    // the long-lived list the DJ was scrolling — the one set certainly still
    // wanted. On the deck that looked like every menu going blank about a
    // minute into any track, independently of which track, and staying blank
    // until the DJ left LINK and came back (which opens a new connection and so
    // a new table).
    //
    // One connection in that capture minted 44 sets against a bound of 32.
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let all = client
        .tracks(Slot::USB, SortOrder::DEFAULT)
        .await
        .expect("the track list");
    let ids: Vec<u32> = all.iter().take(40).map(|item| item.id).collect();
    assert!(ids.len() >= 40, "need enough tracks to overflow the table");

    // Well past MAX_PENDING_MENUS, interleaved with paging the list the way a
    // deck interleaves them.
    for (polls, id) in ids.iter().enumerate() {
        let _ = client
            .metadata(Slot::USB, *id)
            .await
            .expect("a metadata dip");
        if polls % 4 == 0 {
            let again = client
                .tracks(Slot::USB, SortOrder::DEFAULT)
                .await
                .expect("the list must still be there");
            assert_eq!(
                again.len(),
                all.len(),
                "the list vanished after {polls} metadata polls",
            );
        }
    }

    let after = client
        .tracks(Slot::USB, SortOrder::DEFAULT)
        .await
        .expect("the list must still be there");
    assert_eq!(
        after.len(),
        all.len(),
        "the list did not survive the polling"
    );
    assert_eq!(
        after.first().map(|item| item.id),
        all.first().map(|item| item.id),
        "and it is the same list, not another menu served in its place",
    );
}

#[tokio::test]
async fn a_deck_asking_to_describe_the_medium_gets_a_description() {
    // `0x3903` is not an unknown request and must not be answered as one. A
    // deck sends it during a load and expects `0x4902` with a 148-byte body;
    // a bare SUCCESS costs it the whole browse session — menus blank, the track
    // title falls back to the medium's own name, the scrolling waveform stops —
    // until the DJ leaves LINK and comes back. Observed on hardware.
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let descriptor = client.descriptor(Slot::USB, MenuTarget::BINARY, TrackType::REKORDBOX);
    let request = prolink_proto::dbserver::Message::new(
        0x0380_0001,
        MessageKind::GET_MEDIA_INFO,
        [prolink_proto::dbserver::Field::U32(descriptor.to_raw())],
    );
    let reply = client.request(request).await.expect("a reply");

    assert_eq!(
        reply.kind,
        MessageKind::MEDIA_INFO,
        "a bare SUCCESS here is what broke a real deck",
    );
    let body = reply.blob(3).expect("the 148-byte body");
    assert_eq!(body.len(), MediaInfo::LEN);

    let info = MediaInfo::parse(body).expect("it parses");
    assert_eq!(info.volume_name, "TEST STICK");
    assert_eq!(
        info.track_count, 651,
        "the true count, the same one the UDP media query is answered with",
    );
}

#[tokio::test]
async fn every_track_row_carries_its_key_for_the_matching_indicator() {
    // The twelfth argument is the row's key as a Camelot index, and the deck
    // draws its key-matching indicator from it. We sent zero there, which
    // leaves the indicator dark beside every track. Decoded by correlating all
    // 1265 track rows a real deck served against those tracks' keys.
    let (_server, port) = serve_usb().await;
    let mut client = client(port).await;

    let rows = client
        .tracks(Slot::USB, SortOrder::DEFAULT)
        .await
        .expect("the track list");
    let library = library();

    let mut checked = 0;
    for row in &rows {
        let Some(track) = library.tracks.get(&row.id) else {
            continue;
        };
        let expected = CamelotKey::parse(&track.key).map_or(0, CamelotKey::index);
        assert_eq!(
            row.key_index, expected,
            "track {} in key {:?}",
            row.id, track.key
        );
        if expected != 0 {
            checked += 1;
        }
    }
    assert!(
        checked > 100,
        "only {checked} rows carried a key; the fixture should have plenty"
    );

    // And the indices really are the wheel: 1A is 1, 12B is 24.
    let indices: std::collections::BTreeSet<u32> = rows
        .iter()
        .map(|row| row.key_index)
        .filter(|index| *index != 0)
        .collect();
    assert!(
        indices.iter().all(|index| (1..=24).contains(index)),
        "off the wheel: {indices:?}"
    );
}

#[tokio::test]
async fn two_media_are_told_apart_by_the_descriptor_alone() {
    // A player browsing two media on one peer opens a *single* connection and
    // distinguishes them purely by the slot byte in each request (F37).
    let usb = Arc::new(Medium::synthetic(ServedSlot::USB, library(), "USB"));
    let mut sd_library = library();
    sd_library.tracks.retain(|id, _| *id % 2 == 0);
    let sd = Arc::new(Medium::synthetic(ServedSlot::SD, sd_library, "SD"));

    let server = DbServer::start(
        DbServerConfig {
            device: device(4),
            address: LOOPBACK,
            port: 0,
            query_port: None,
        },
        [usb, sd],
    )
    .await
    .expect("a two-slot dbserver");

    let mut client = client(server.port()).await;
    let from_usb = client
        .tracks(Slot::USB, SortOrder::DEFAULT)
        .await
        .expect("the USB");
    let from_sd = client
        .tracks(Slot::SD, SortOrder::DEFAULT)
        .await
        .expect("the SD");

    assert_eq!(from_usb.len(), library().tracks.len());
    assert!(
        from_sd.len() < from_usb.len(),
        "the two slots really are different libraries"
    );
    assert!(!from_sd.is_empty());
}

/// A directory shaped like a rekordbox medium, with the real database on it.
///
/// Named per test, not per process: `cargo test` runs these concurrently, and a
/// shared directory means one test's cleanup deletes another's medium mid-read.
/// Which the client reports correctly — it refuses to return a short file rather
/// than truncate one silently — but as a test failure it is noise.
fn fake_medium(test: &str) -> PathBuf {
    let root = std::env::temp_dir().join(format!("prolink-loopback-{test}"));
    let _ = std::fs::remove_dir_all(&root);
    std::fs::create_dir_all(root.join("PIONEER/rekordbox")).expect("a temp medium");
    std::fs::create_dir_all(root.join("Contents/GESAFFELSTEIN")).expect("a contents directory");
    std::fs::write(root.join("PIONEER/rekordbox/export.pdb"), export_pdb()).expect("the database");
    // Not audio, but the server does not care and the client reads it the same
    // way: 40 KB is five 8192-byte reads, which is what a deck does.
    let audio: Vec<u8> = (0..40_960u32).map(|byte| byte as u8).collect();
    std::fs::write(root.join("Contents/GESAFFELSTEIN/track.mp3"), &audio).expect("a track");
    root
}

async fn serve_files(root: &Path) -> (NfsServer, u16) {
    let mut tree = Vfs::new();
    tree.mount(ServedSlot::USB.vfs_prefix(), root)
        .expect("mounting the medium");
    let server = NfsServer::start(
        Arc::new(RwLock::new(tree)),
        ServerNfsConfig {
            interface: None,
            // Ephemeral throughout: nothing here needs root. Against hardware
            // the portmapper must be on 111 or a deck never looks (F46).
            portmap_port: 0,
            mount_port: 0,
            nfs_port: 0,
        },
    )
    .await
    .expect("the file servers start");
    let portmap = server.ports().portmap;
    (server, portmap)
}

#[tokio::test]
async fn a_client_pulls_the_database_back_byte_for_byte() {
    let root = fake_medium("pull");
    let (_server, portmap) = serve_files(&root).await;

    let mut client = NfsClient::connect_with(
        LOOPBACK,
        None,
        prolink::consume::NfsConfig {
            portmap_port: portmap,
            ..Default::default()
        },
    )
    .await
    .expect("portmap discovery finds mountd and nfsd");

    let mounted = client.mount_slot(Slot::USB).await.expect("mounting /C/");
    let file = client
        .open(&mounted, prolink::consume::nfs::EXPORT_PDB)
        .await
        .expect("walking to export.pdb");

    let expected = export_pdb();
    assert_eq!(file.size(), expected.len() as u64);
    let pulled = client.read_file(&file).await.expect("the whole file");
    assert_eq!(
        pulled, expected,
        "an export.pdb that differs by a byte is a different library"
    );

    // And it is still a library after the round trip.
    let parsed = Library::parse(&pulled).expect("the pulled database parses");
    assert_eq!(parsed.tracks.len(), library().tracks.len());

    client
        .unmount(&mounted)
        .await
        .expect("a real player unmounts, once per slot");
    std::fs::remove_dir_all(&root).ok();
}

#[tokio::test]
async fn a_client_reads_a_track_in_ranges_the_way_a_deck_streams_one() {
    let root = fake_medium("stream");
    let (_server, portmap) = serve_files(&root).await;

    let mut client = NfsClient::connect_with(
        LOOPBACK,
        None,
        prolink::consume::NfsConfig {
            portmap_port: portmap,
            ..Default::default()
        },
    )
    .await
    .expect("connecting");

    let mounted = client.mount_slot(Slot::USB).await.expect("mounting");
    // The case-and-normalisation fallback matters here: `export.pdb` records
    // `Gesaffelstein` where the directory is `GESAFFELSTEIN` (O6).
    let file = client
        .open(&mounted, "/Contents/Gesaffelstein/track.mp3")
        .await
        .expect("a path whose case does not match the directory's");
    assert_eq!(file.size(), 40_960);

    // A deck seeks; it does not read front to back.
    let tail = client
        .read_range(&file, 40_000, 960)
        .await
        .expect("a read near the end");
    assert_eq!(tail.len(), 960);
    assert_eq!(tail[0], 40_000_u32 as u8);

    let middle = client
        .read_range(&file, 16_384, 8_192)
        .await
        .expect("a read in the middle");
    assert_eq!(middle.len(), 8_192);
    assert_eq!(middle[0], 16_384_u32 as u8);

    // Past the end is short, not an error.
    let past = client
        .read_range(&file, 40_960, 4_096)
        .await
        .expect("a read past the end");
    assert!(past.is_empty());

    std::fs::remove_dir_all(&root).ok();
}

#[tokio::test]
async fn a_handle_whose_tail_a_cdj_rewrote_still_resolves() {
    // RFC 1094 says a filehandle is 32 opaque bytes echoed back verbatim. A
    // CDJ-2000NXS keeps the leading twelve and overwrites the rest with its own
    // file reference (F28). A server that trusts the spec browses perfectly and
    // fails at the moment a DJ loads a track, so this is the case worth proving
    // end to end rather than only in the VFS's unit tests.
    let root = fake_medium("handle");
    let (_server, portmap) = serve_files(&root).await;

    let mut client = NfsClient::connect_with(
        LOOPBACK,
        None,
        prolink::consume::NfsConfig {
            portmap_port: portmap,
            ..Default::default()
        },
    )
    .await
    .expect("connecting");

    let mounted = client.mount_slot(Slot::USB).await.expect("mounting");
    let file = client
        .open(&mounted, prolink::consume::nfs::EXPORT_PDB)
        .await
        .expect("walking to the database");

    let mut rewritten = file.handle();
    rewritten.0[12..].copy_from_slice(&[
        0x03, 0x01, 0x2d, 0x00, 0x00, 0x00, 0x1b, 0x58, 0x00, 0x00, 0x00, 0x00, 0x03, 0x03, 0x01,
        0x00, 0x00, 0x00, 0x01, 0x62,
    ]);
    assert_ne!(rewritten, file.handle(), "the bytes really did change");

    let attributes = client
        .attributes(rewritten)
        .await
        .expect("the server must still know it");
    assert_eq!(u64::from(attributes.size), file.size());

    std::fs::remove_dir_all(&root).ok();
}

// ---------------------------------------------------------------------------
// Partial fetching, against the real server.
//
// `progressive.rs` pins the ORDER without a network. These pin the READS: that
// a range asked for is the range that comes back, and that executing a plan
// reconstructs the file byte for byte. Between them, the thing that makes a
// track playable before it has arrived is covered on both sides.
// ---------------------------------------------------------------------------

/// The 40 KB pattern `fake_medium` writes, so a test can say what it expects.
fn track_bytes() -> Vec<u8> {
    (0..40_960u32).map(|byte| byte as u8).collect()
}

async fn open_track(root: &Path, portmap: u16) -> (NfsClient, prolink::consume::nfs::RemoteFile) {
    let mut client = NfsClient::connect_with(
        LOOPBACK,
        None,
        prolink::consume::NfsConfig {
            portmap_port: portmap,
            ..Default::default()
        },
    )
    .await
    .expect("portmap discovery");
    let _ = root;
    let mounted = client.mount_slot(Slot::USB).await.expect("mounting");
    let file = client
        .open(&mounted, "/Contents/GESAFFELSTEIN/track.mp3")
        .await
        .expect("walking to the track");
    (client, file)
}

#[tokio::test]
async fn a_range_read_returns_exactly_that_range() {
    let root = fake_medium("range-exact");
    let (_server, portmap) = serve_files(&root).await;
    let (mut client, file) = open_track(&root, portmap).await;
    let expected = track_bytes();

    // Including offsets that are not multiples of the read size, because a
    // playhead does not land on one.
    for (offset, len) in [
        (0u64, 1u64),
        (0, 8192),
        (1, 8191),
        (8191, 2),
        (12_345, 1_000),
    ] {
        let got = client
            .read_range(&file, offset, len)
            .await
            .expect("a range read");
        let want =
            &expected[usize::try_from(offset).unwrap()..usize::try_from(offset + len).unwrap()];
        assert_eq!(
            got,
            want,
            "range {offset}..{} came back wrong",
            offset + len
        );
    }
}

#[tokio::test]
async fn a_range_read_past_the_end_is_clamped_rather_than_failing() {
    // The tail of a plan is computed from a size the deck reported; if that is
    // stale by a byte the fetch must not fall over.
    let root = fake_medium("range-clamp");
    let (_server, portmap) = serve_files(&root).await;
    let (mut client, file) = open_track(&root, portmap).await;

    let got = client
        .read_range(&file, 40_000, 10_000)
        .await
        .expect("a read that overruns the end");
    assert_eq!(got.len(), 960, "clamped to what is actually there");
    assert_eq!(got, &track_bytes()[40_000..]);
}

#[tokio::test]
async fn a_range_read_entirely_past_the_end_is_empty() {
    let root = fake_medium("range-past");
    let (_server, portmap) = serve_files(&root).await;
    let (mut client, file) = open_track(&root, portmap).await;

    let got = client
        .read_range(&file, 40_960, 1_000)
        .await
        .expect("a read starting at the end");
    assert!(got.is_empty());
}

#[tokio::test]
async fn the_tail_is_readable_before_the_middle_has_been_touched() {
    // The AAC case, made concrete: fetch the head and then jump straight to the
    // last bytes, exactly as a plan does, and check the end of the file is
    // right without anything between them having been read.
    let root = fake_medium("range-tail-first");
    let (_server, portmap) = serve_files(&root).await;
    let (mut client, file) = open_track(&root, portmap).await;
    let expected = track_bytes();

    let head = client.read_range(&file, 0, 4_096).await.expect("the head");
    assert_eq!(head, &expected[..4_096]);

    let tail = client
        .read_range(&file, 40_960 - 256, 256)
        .await
        .expect("the tail, out of order");
    assert_eq!(tail, &expected[40_960 - 256..]);
}

#[tokio::test]
async fn executing_a_plan_reconstructs_the_file_byte_for_byte() {
    // The whole thing, end to end: plan the ranges, fetch them in the order the
    // plan gives, write each at its own offset, and compare with the source.
    // This is what a track being playable before it has arrived actually means.
    let root = fake_medium("range-plan");
    let (_server, portmap) = serve_files(&root).await;
    let (mut client, file) = open_track(&root, portmap).await;
    let expected = track_bytes();

    let plan = prolink::consume::nfs::progressive_plan(file.size(), 4_096, 256, 8_192);
    assert!(plan.len() > 3, "a 40 KB file should take several steps");

    let mut assembled = vec![0u8; usize::try_from(file.size()).unwrap()];
    for step in &plan {
        let bytes = client
            .read_range(&file, step.offset, step.len)
            .await
            .unwrap_or_else(|error| panic!("fetching {step:?}: {error}"));
        assert_eq!(
            bytes.len() as u64,
            step.len,
            "{step:?} came back short, which would leave a hole"
        );
        let start = usize::try_from(step.offset).unwrap();
        assembled[start..start + bytes.len()].copy_from_slice(&bytes);
    }
    assert_eq!(assembled, expected);
}

#[tokio::test]
async fn a_plan_over_a_tiny_file_still_reconstructs_it() {
    // The degenerate end: a file smaller than the head, where the plan collapses
    // to a single read and the tail must not double back into it.
    let root = fake_medium("range-tiny");
    std::fs::write(root.join("Contents/GESAFFELSTEIN/track.mp3"), b"short").expect("a tiny track");
    let (_server, portmap) = serve_files(&root).await;
    let (mut client, file) = open_track(&root, portmap).await;

    assert_eq!(file.size(), 5);
    let plan = prolink::consume::nfs::progressive_plan(file.size(), 4_096, 256, 8_192);
    let mut assembled = Vec::new();
    for step in &plan {
        assembled.extend(
            client
                .read_range(&file, step.offset, step.len)
                .await
                .expect("a step"),
        );
    }
    assert_eq!(assembled, b"short");
}

// -- a plain stick ----------------------------------------------------------

/// A WAV that says what it is: two seconds of CD-quality silence, with a
/// title, an artist, a genre and a comment in its `LIST`/`INFO` chunk.
fn tagged_wav() -> Vec<u8> {
    fn chunk(id: [u8; 4], body: &[u8]) -> Vec<u8> {
        let mut out = id.to_vec();
        out.extend_from_slice(&(body.len() as u32).to_le_bytes());
        out.extend_from_slice(body);
        if body.len() % 2 == 1 {
            out.push(0);
        }
        out
    }
    let mut format = Vec::new();
    for word in [1u16, 2] {
        format.extend_from_slice(&word.to_le_bytes());
    }
    format.extend_from_slice(&44_100u32.to_le_bytes());
    format.extend_from_slice(&(44_100u32 * 4).to_le_bytes());
    format.extend_from_slice(&4u16.to_le_bytes());
    format.extend_from_slice(&16u16.to_le_bytes());
    let mut info = b"INFO".to_vec();
    for (id, text) in [
        (b"INAM", "Title Tag"),
        (b"IART", "Artist Tag"),
        (b"IGNR", "Techno"),
        (b"ICMT", "A comment"),
    ] {
        let mut value = text.as_bytes().to_vec();
        value.push(0);
        info.extend(chunk(*id, &value));
    }
    let mut body = b"WAVE".to_vec();
    body.extend(chunk(*b"fmt ", &format));
    body.extend(chunk(*b"LIST", &info));
    body.extend(chunk(*b"data", &vec![0u8; 44_100 * 4 * 2]));
    chunk(*b"RIFF", &body)
}

/// A stick with no rekordbox library: a tagged WAV and its folder's cover in
/// `Music/`, and an untagged file at the top.
fn plain_stick(test: &str) -> PathBuf {
    let root = std::env::temp_dir().join(format!("prolink-loopback-plain-{test}"));
    let _ = std::fs::remove_dir_all(&root);
    std::fs::create_dir_all(root.join("Music")).expect("a folder");
    std::fs::write(root.join("Music/Tagged.wav"), tagged_wav()).expect("a WAV");
    std::fs::write(
        root.join("Music/cover.jpg"),
        [0xff, 0xd8, 0xff, 0xe0, 1, 2, 3],
    )
    .expect("a cover");
    std::fs::write(root.join("Untagged.mp3"), [0x55u8; 4096]).expect("an untagged file");
    root
}

#[tokio::test]
async fn a_plain_stick_is_browsed_and_read_the_way_a_cdj_reads_one() {
    let root = plain_stick("browse");
    let medium = Arc::new(Medium::from_folders(&root, ServedSlot::USB).expect("a plain medium"));
    assert!(medium.is_plain());

    let server = DbServer::start(
        DbServerConfig {
            device: device(4),
            address: LOOPBACK,
            port: 0,
            query_port: None,
        },
        [Arc::clone(&medium)],
    )
    .await
    .expect("the dbserver starts");
    let mut db = client(server.port()).await;

    // The root menu is FOLDER alone (PLAIN-STICKS.md §4.1).
    let root_menu = db.root_menu(Slot::USB).await.expect("the root menu");
    assert_eq!(root_menu.len(), 1);
    assert_eq!(root_menu[0].item_type, ItemType::MENU_FOLDER);

    // Folders, then files (§4.2).
    let top = db
        .folder(Slot::USB, prolink_proto::dbserver::FILTER_ALL)
        .await
        .expect("the top of the stick");
    let labels: Vec<&str> = top.iter().map(|row| row.label1.as_str()).collect();
    assert_eq!(labels, ["Music", "Untagged.mp3"]);
    assert_eq!(top[0].item_type, ItemType::FOLDER);
    let music = db.folder(Slot::USB, top[0].id).await.expect("Music");
    assert_eq!(music.len(), 1);
    let wav = music[0].id;
    assert_eq!(
        music[0].label1, "Tagged.wav",
        "a file row shows its file name"
    );

    // Its tags, asked as a player asks a plain file (§5).
    let metadata = db
        .generic_metadata(Slot::USB, wav)
        .await
        .expect("its metadata");
    assert_eq!(metadata.title, "Title Tag");
    assert_eq!(metadata.artist, "Artist Tag");
    assert_eq!(metadata.genre, "Techno");
    assert_eq!(metadata.comment, "A comment");
    assert_eq!(metadata.duration_seconds, 2);
    assert_eq!(metadata.bitrate, 1411);
    assert_eq!(metadata.artwork_id, wav);
    let untagged = db
        .generic_metadata(Slot::USB, top[1].id)
        .await
        .expect("an untagged file's");
    assert_eq!(untagged.title, "Untagged.mp3", "named by its file name");

    // The folder's picture, by the file's own id (§6).
    let cover = db.plain_artwork(Slot::USB, wav).await.expect("its cover");
    assert_eq!(cover, [0xff, 0xd8, 0xff, 0xe0, 1, 2, 3]);

    // Its track info carries no path, and the numbers it is opened by (§7.2).
    let info = db
        .plain_track_info(Slot::USB, wav)
        .await
        .expect("its track info");
    assert!(info.path.is_empty());
    assert_eq!(info.container, 11, "WAV");
    let (folder, entry) = info.plain_lookup.expect("the numbers");
    assert_eq!(info.size, tagged_wav().len() as u64);

    // One LOOKUP of `?\0D <folder> <entry>` on the export's root, and READs
    // (§7.3).
    let mut tree = Vfs::new();
    tree.mount_medium(&medium).expect("mounting the stick");
    let files = NfsServer::start(
        Arc::new(RwLock::new(tree)),
        ServerNfsConfig {
            interface: None,
            portmap_port: 0,
            mount_port: 0,
            nfs_port: 0,
        },
    )
    .await
    .expect("the file servers start");
    let mut nfs = NfsClient::connect_with(
        LOOPBACK,
        None,
        prolink::consume::NfsConfig {
            portmap_port: files.ports().portmap,
            ..Default::default()
        },
    )
    .await
    .expect("connecting");
    let mounted = nfs.mount_slot(Slot::USB).await.expect("mounting /C/");
    let file = nfs
        .open_plain(&mounted, folder, entry)
        .await
        .expect("the file, by its two numbers");
    assert_eq!(file.size(), info.size);
    let head = nfs.read_range(&file, 0, 12).await.expect("its head");
    assert_eq!(&head[..4], b"RIFF");
    assert_eq!(&head[8..12], b"WAVE");
    assert!(
        nfs.open_plain(&mounted, folder, entry + 1).await.is_err(),
        "another entry of that folder is no file"
    );

    std::fs::remove_dir_all(&root).ok();
}