Merge pull request #78 from ZHANGTIANYAO1/feat/shuffle-bag-random-modes

feat(queue): 随机循环改为洗牌袋,每首歌播完一轮再重复 (优化随机循环逻辑)

src/audio/queue.test.ts

@@ -484,4 +484,84 @@ describe("PlayQueue", () => {
       expect(promoted?.id).toBe("x");
     });
   });
+
+  // Issue #70: 随机循环 (rloop) used true random-with-replacement, so some
+  // songs repeated often while others were starved. It should behave like a
+  // shuffle bag (NetEase/QQ style): play every song once per cycle in random
+  // order, then reshuffle and continue, avoiding an immediate cross-cycle repeat.
+  describe("random-loop shuffle bag (issue #70)", () => {
+    it("plays every song exactly once per cycle before repeating", () => {
+      queue.setMode(PlayMode.RandomLoop);
+      const N = 12;
+      for (let i = 0; i < N; i++) queue.add(makeSong(`s${i}`));
+      queue.play();
+
+      const cycle1 = [queue.current()!.id];
+      for (let i = 0; i < N - 1; i++) cycle1.push(queue.next()!.id);
+      const cycle2: string[] = [];
+      for (let i = 0; i < N; i++) cycle2.push(queue.next()!.id);
+
+      // Each cycle is a full permutation of all N songs — zero repeats within
+      // a cycle, and both cycles cover the same complete set.
+      expect(new Set(cycle1).size).toBe(N);
+      expect(new Set(cycle2).size).toBe(N);
+      expect(new Set(cycle1)).toEqual(new Set(cycle2));
+    });
+
+    it("distributes plays evenly across songs over many cycles (no starvation)", () => {
+      queue.setMode(PlayMode.RandomLoop);
+      const N = 6;
+      const CYCLES = 20;
+      for (let i = 0; i < N; i++) queue.add(makeSong(`s${i}`));
+      queue.play();
+
+      const counts = new Map<string, number>();
+      counts.set(queue.current()!.id, 1);
+      for (let i = 0; i < CYCLES * N - 1; i++) {
+        const id = queue.next()!.id;
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+      }
+
+      // Shuffle bag => each song plays exactly CYCLES times. True random
+      // would skew heavily.
+      for (let i = 0; i < N; i++) {
+        expect(counts.get(`s${i}`)).toBe(CYCLES);
+      }
+    });
+
+    it("does not replay the same song across a cycle boundary", () => {
+      queue.setMode(PlayMode.RandomLoop);
+      const N = 5;
+      for (let i = 0; i < N; i++) queue.add(makeSong(`s${i}`));
+      queue.play();
+
+      // Walk to the last song of cycle 1, then cross into cycle 2.
+      for (let i = 0; i < N - 1; i++) queue.next();
+      const lastOfCycle1 = queue.current()!.id;
+      const firstOfCycle2 = queue.next()!.id;
+      expect(firstOfCycle2).not.toBe(lastOfCycle1);
+    });
+
+    it("includes a song added mid-cycle within the current cycle", () => {
+      queue.setMode(PlayMode.RandomLoop);
+      queue.add(makeSong("A"));
+      queue.add(makeSong("B"));
+      queue.play(); // A
+      queue.next(); // B — both originals now played this cycle
+      queue.add(makeSong("C")); // added mid-cycle, still unplayed
+      // C is the only unplayed song, so it must come next (not a reshuffle).
+      expect(queue.next()?.id).toBe("C");
+    });
+
+    it("keeps looping forever with multiple songs (never returns null)", () => {
+      queue.setMode(PlayMode.RandomLoop);
+      queue.add(makeSong("A"));
+      queue.add(makeSong("B"));
+      queue.add(makeSong("C"));
+      queue.play();
+      for (let i = 0; i < 30; i++) {
+        expect(queue.next()).not.toBeNull();
+      }
+    });
+  });
 });

src/audio/queue.ts

@@ -155,33 +155,42 @@ export class PlayQueue {
             return this.songs[target];
           }
         }
-        // 前进栈为空，走纯随机逻辑
-        if (this.mode === PlayMode.Random) {
-          const unplayed: number[] = [];
-          for (let i = 0; i < this.songs.length; i++) {
-            if (!this.playedIndices.has(i)) unplayed.push(i);
-          }
-          if (unplayed.length === 0) return null;
-          const nextIndex =
-            unplayed[Math.floor(Math.random() * unplayed.length)];
-          this.pushHistory(this.currentIndex);
-          this.currentIndex = nextIndex;
-          this.playedIndices.add(nextIndex);
-          return this.songs[nextIndex];
-        } else {
+
+        // Shuffle bag: pick uniformly from the songs not yet played this
+        // cycle, so every song plays once before any repeats (NetEase/QQ
+        // style). Songs added mid-cycle aren't in playedIndices, so they're
+        // naturally eligible within the current cycle.
+        const unplayed: number[] = [];
+        for (let i = 0; i < this.songs.length; i++) {
+          if (!this.playedIndices.has(i)) unplayed.push(i);
+        }
+
+        if (unplayed.length === 0) {
+          // Cycle complete.
+          if (this.mode === PlayMode.Random) return null; // 随机：播完即停
+          // 随机循环：reshuffle and keep going forever.
           if (this.songs.length === 1) {
             this.pushHistory(this.currentIndex);
             this.currentIndex = 0;
+            this.playedIndices = new Set([0]);
             return this.songs[0];
           }
-          let idx: number;
-          do {
-            idx = Math.floor(Math.random() * this.songs.length);
-          } while (idx === this.currentIndex);
-          this.pushHistory(this.currentIndex);
-          this.currentIndex = idx;
-          return this.songs[idx];
+          // Start a fresh cycle: every song is eligible again, but exclude
+          // the song that just played from THIS pick only, so it doesn't
+          // repeat back-to-back across the boundary. It stays eligible for
+          // the rest of the new cycle, so every song still plays exactly once.
+          this.playedIndices = new Set();
+          for (let i = 0; i < this.songs.length; i++) {
+            if (i !== this.currentIndex) unplayed.push(i);
+          }
         }
+
+        const nextIndex =
+          unplayed[Math.floor(Math.random() * unplayed.length)];
+        this.pushHistory(this.currentIndex);
+        this.currentIndex = nextIndex;
+        this.playedIndices.add(nextIndex);
+        return this.songs[nextIndex];
       }
     }
   }

src/web/middleware/csrf.test.ts

@@ -55,4 +55,19 @@ describe("csrfOriginCheck middleware", () => {
       .set("Referer", "https://evil.com/some/path");
     expect(res.status).toBe(403);
   });
+
+  // Documents the server side of the QR-login outage: a `no-referrer` document
+  // policy makes the browser send the literal `Origin: null` on same-origin
+  // POSTs, which this guard cannot parse a host from and therefore rejects.
+  // The fix lives in the frontend (referrer policy -> same-origin); this test
+  // pins the gate behavior so the interaction stays understood. See
+  // src/web/referrer-policy.test.ts.
+  it('rejects POST with the literal Origin: "null" (no-referrer downgrade)', async () => {
+    const res = await request(app)
+      .post("/")
+      .set("Host", "example.com")
+      .set("Origin", "null");
+    expect(res.status).toBe(403);
+    expect(res.body).toEqual({ error: "bad origin" });
+  });
 });

src/web/referrer-policy.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Regression guard for the QR-login / cookie-save outage (and in fact every
+ * mutating WebUI action). On 2026-05-27 the WebUI-auth feature added the
+ * same-origin CSRF gate `app.use("/api", csrfOriginCheck)` in server.ts, and
+ * the same day a `<meta name="referrer" content="no-referrer">` was added to
+ * web/index.html so cross-origin CDN cover thumbnails would load.
+ *
+ * Those two changes conflict: per the WHATWG Fetch "Append a request Origin
+ * header" algorithm, the `no-referrer` policy sets the Origin header to the
+ * literal string "null" on same-origin non-GET requests. csrfOriginCheck then
+ * fails to parse a host (`new URL("null")` throws) and returns 403 "bad
+ * origin", so POST /api/auth/qrcode (and every other POST/PUT/DELETE under
+ * /api/* except /api/session/*) never reaches its handler.
+ *
+ * `same-origin` is the correct policy: it keeps the real Origin on same-origin
+ * requests (CSRF passes) while still sending no Referer cross-origin (CDN
+ * thumbnails keep loading). Never switch this back to `no-referrer`.
+ */
+describe("frontend referrer policy (CSRF / Origin-header regression)", () => {
+  const indexHtmlPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "../../web/index.html"
+  );
+  const html = fs.readFileSync(indexHtmlPath, "utf-8");
+
+  const referrerMeta = html.match(
+    /<meta\s+name=["']referrer["']\s+content=["']([^"']+)["']\s*\/?>/i
+  );
+
+  it("declares a referrer policy meta tag", () => {
+    expect(referrerMeta).not.toBeNull();
+  });
+
+  it("uses same-origin (NOT no-referrer, which sends Origin: null and 403s every POST)", () => {
+    expect(referrerMeta?.[1]).toBe("same-origin");
+  });
+
+  it("does not contain no-referrer anywhere in the document head", () => {
+    expect(html).not.toMatch(/content=["']no-referrer["']/i);
+  });
+});

web/index.html

@@ -3,10 +3,18 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <!-- Bilibili / NetEase / QQ image CDNs reject requests whose Referer is not on their whitelist.
-       Setting no-referrer at the document level covers <img> tags AND CSS background-image fetches.
-       Our own /api/* CSRF check uses Origin (not Referer), so this doesn't break auth. -->
-  <meta name="referrer" content="no-referrer">
+  <!-- Bilibili / NetEase / QQ image CDNs reject requests whose Referer is not on
+       their whitelist, so we must not leak a Referer cross-origin. "same-origin"
+       does exactly that: full Referer for our own requests, none for cross-origin
+       ones — so cover thumbnails (<img> AND CSS background-image) still load.
+       Do NOT switch this back to "no-referrer": per the WHATWG Fetch spec
+       ("Append a request Origin header") no-referrer downgrades the Origin header
+       to the literal string "null" on same-origin non-GET requests. The /api/*
+       CSRF guard (src/web/middleware/csrf.ts) then can't parse a host from it and
+       responds 403 "bad origin", silently breaking EVERY POST/PUT/DELETE — QR
+       login, cookie save, playback controls, bot management, user admin, etc.
+       "same-origin" keeps the real Origin on same-origin requests, so CSRF passes. -->
+  <meta name="referrer" content="same-origin">
   <title>TSMusicBot</title>
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link href="https://fonts.googleapis.com/css2?family=Barlow:wght@400;500;600;700;800&display=swap" rel="stylesheet">