feat(clipboard): out-of-band blob endpoints for large payloads

Adds POST /api/v1/clipboard/blob and GET /api/v1/clipboard/blob/<id>

to escape the 65500-byte single-frame limit on the encrypted control

stream. Lets clients (and the GUI agent) exchange clipboard items larger

than the wire frame can carry: images, files, etc.

Architecture (preserved):

  The C++ service stays a dumb facility — just like clipboard_bridge is

  a dumb byte forwarder, clipboard_blob_store is a dumb byte+mime store.

  Neither parses protocol kinds, decodes PNG, or knows what KIND_REF is.

  All semantic work (when to upload, when to send a REF frame, when to

  fetch) stays in the Rust GUI agent and the streaming clients.

New module clipboard_blob_store:

  * Per-blob TTL (60 s), no read-extend, retries are safe.

  * Per-blob size cap 50 MiB; total store cap 200 MiB.

  * FIFO eviction when the store cap would be exceeded.

  * UUID-v4 ids generated locally; thread-safe public API.

  * No persistence — process restart drops everything.

New endpoints (clipboard_http.cpp):

  * POST /api/v1/clipboard/blob

      Body: raw bytes. Required header: X-Clipboard-Mime.

      200 -> {id, size, expires_in}.

      400 missing_mime / bad_mime / bad_content_length / empty_body.

      413 payload_too_large (vs kMaxBlobBytes).

      403 clipboard_sync_disabled.

  * GET /api/v1/clipboard/blob/<id>

      Body: raw bytes. Content-Type echoes the stored mime.

      404 not_found (missing or TTL-expired).

      Read does not consume — clients can retry on transient errors.

Auth: delegated through the existing register_routes auth_fn so the new

endpoints inherit confighttp's basic-auth gating exactly like the existing

C:/Program Files/Git/clipboard/{capability,item,events}.

Build: ninja sunshine clean on UCRT64 (sunshine.exe 67 MiB).

Out of scope (separate PRs):

  * Rust GUI agent — detect large outbound items, upload, build KIND_REF.

  * Moonlight clients (Qt/Android) — detect inbound KIND_REF, fetch blob.

  * moonlight-common-c — publish LI_CLIPBOARD_KIND_REF=3 constant.

Author: qiin2333

cmake/compile_definitions/common.cmake

@@ -110,6 +110,8 @@ set(SUNSHINE_TARGET_FILES
         "${CMAKE_SOURCE_DIR}/src/stream.h"
         "${CMAKE_SOURCE_DIR}/src/clipboard_bridge.cpp"
         "${CMAKE_SOURCE_DIR}/src/clipboard_bridge.h"
+        "${CMAKE_SOURCE_DIR}/src/clipboard_blob_store.cpp"
+        "${CMAKE_SOURCE_DIR}/src/clipboard_blob_store.h"
         "${CMAKE_SOURCE_DIR}/src/clipboard_http.cpp"
         "${CMAKE_SOURCE_DIR}/src/clipboard_http.h"
         "${CMAKE_SOURCE_DIR}/src/video.cpp"

src/clipboard_blob_store.cpp

@@ -0,0 +1,173 @@
+/**
+ * @file src/clipboard_blob_store.cpp
+ * @brief See clipboard_blob_store.h.
+ */
+#include "clipboard_blob_store.h"
+
+#include <chrono>
+#include <deque>
+#include <mutex>
+#include <random>
+#include <sstream>
+#include <unordered_map>
+#include <utility>
+
+namespace clipboard_blob_store {
+  namespace {
+    using clock_t = std::chrono::steady_clock;
+
+    struct entry_t {
+      payload_t bytes;
+      std::string mime;
+      clock_t::time_point expires_at;
+    };
+
+    std::mutex g_mu;
+    // Map keyed by blob_id; insertion order tracked separately for FIFO eviction.
+    std::unordered_map<blob_id, entry_t> g_entries;
+    std::deque<blob_id> g_fifo;
+    std::size_t g_total_bytes = 0;
+
+    /// Generate a UUID-v4-shaped 36-char hex id without pulling in boost::uuid
+    /// here. Cryptographic strength is not required — these ids are scoped to
+    /// a live HTTPS-authenticated session and expire in 60 s.
+    std::string
+    make_id() {
+      thread_local std::mt19937_64 rng { std::random_device {}() };
+      std::uniform_int_distribution<std::uint64_t> dist;
+
+      std::uint64_t hi = dist(rng);
+      std::uint64_t lo = dist(rng);
+
+      // Force version=4 nibble and variant bits per RFC 4122.
+      hi = (hi & 0xFFFFFFFFFFFF0FFFULL) | 0x0000000000004000ULL;
+      lo = (lo & 0x3FFFFFFFFFFFFFFFULL) | 0x8000000000000000ULL;
+
+      static constexpr char kHex[] = "0123456789abcdef";
+      std::string s(36, '-');
+      auto write_byte = [&](std::size_t pos, std::uint8_t b) {
+        s[pos] = kHex[b >> 4];
+        s[pos + 1] = kHex[b & 0xF];
+      };
+
+      // 8-4-4-4-12 layout. Bytes 0..7 = hi, bytes 8..15 = lo.
+      auto byte_at = [&](int i) -> std::uint8_t {
+        std::uint64_t v = (i < 8) ? hi : lo;
+        int shift = (7 - (i & 7)) * 8;
+        return static_cast<std::uint8_t>((v >> shift) & 0xFF);
+      };
+
+      static constexpr int kSlots[] = { 0, 2, 4, 6, 9, 11, 14, 16, 19, 21, 24, 26, 28, 30, 32, 34 };
+      for (int i = 0; i < 16; ++i) {
+        write_byte(static_cast<std::size_t>(kSlots[i]), byte_at(i));
+      }
+      return s;
+    }
+
+    /// Caller must hold g_mu. Drops everything past TTL.
+    void
+    sweep_locked(clock_t::time_point now) {
+      // FIFO is roughly in insertion order, but TTLs are uniform so it's
+      // also roughly expiry order. Walk from front and stop at first live one.
+      while (!g_fifo.empty()) {
+        auto it = g_entries.find(g_fifo.front());
+        if (it == g_entries.end()) {
+          g_fifo.pop_front();
+          continue;
+        }
+        if (it->second.expires_at > now) {
+          break;
+        }
+        g_total_bytes -= it->second.bytes.size();
+        g_entries.erase(it);
+        g_fifo.pop_front();
+      }
+    }
+
+    /// Caller must hold g_mu. Force-evict oldest entries until total bytes
+    /// + `incoming` fits under `kMaxStoreBytes`.
+    void
+    evict_for_locked(std::size_t incoming) {
+      while (!g_fifo.empty() && g_total_bytes + incoming > kMaxStoreBytes) {
+        auto it = g_entries.find(g_fifo.front());
+        g_fifo.pop_front();
+        if (it != g_entries.end()) {
+          g_total_bytes -= it->second.bytes.size();
+          g_entries.erase(it);
+        }
+      }
+    }
+  }  // namespace
+
+  put_result_t
+  put(payload_t bytes, std::string mime) {
+    if (bytes.size() > kMaxBlobBytes) {
+      return { {}, false, "too_large" };
+    }
+    if (bytes.size() > kMaxStoreBytes) {
+      // Even after a full FIFO purge it wouldn't fit.
+      return { {}, false, "too_large" };
+    }
+
+    auto now = clock_t::now();
+    const std::size_t incoming = bytes.size();
+
+    std::lock_guard<std::mutex> lk(g_mu);
+    sweep_locked(now);
+    evict_for_locked(incoming);
+
+    blob_id id = make_id();
+    // Defensive: ensure no collision (vanishingly unlikely).
+    while (g_entries.find(id) != g_entries.end()) {
+      id = make_id();
+    }
+
+    entry_t e;
+    e.bytes = std::move(bytes);
+    e.mime = std::move(mime);
+    e.expires_at = now + std::chrono::seconds(kBlobTtlSeconds);
+
+    g_total_bytes += incoming;
+    g_fifo.push_back(id);
+    g_entries.emplace(id, std::move(e));
+
+    return { id, true, {} };
+  }
+
+  get_result_t
+  get(const blob_id &id, bool consume) {
+    auto now = clock_t::now();
+
+    std::lock_guard<std::mutex> lk(g_mu);
+    sweep_locked(now);
+
+    auto it = g_entries.find(id);
+    if (it == g_entries.end()) {
+      return { false, {}, {} };
+    }
+
+    if (consume) {
+      get_result_t r { true, std::move(it->second.bytes), std::move(it->second.mime) };
+      g_total_bytes -= r.bytes.size();
+      g_entries.erase(it);
+      // Lazy: leave the dead id in g_fifo; sweep_locked drops it on next pass.
+      return r;
+    }
+
+    // Copy out without mutating storage so retries work.
+    return { true, it->second.bytes, it->second.mime };
+  }
+
+  void
+  sweep_expired() {
+    auto now = clock_t::now();
+    std::lock_guard<std::mutex> lk(g_mu);
+    sweep_locked(now);
+  }
+
+  stats_t
+  stats() {
+    std::lock_guard<std::mutex> lk(g_mu);
+    return { g_entries.size(), g_total_bytes };
+  }
+}  // namespace clipboard_blob_store

src/clipboard_blob_store.h

@@ -0,0 +1,82 @@
+/**
+ * @file src/clipboard_blob_store.h
+ * @brief In-memory TTL-bounded blob storage for out-of-band clipboard payloads
+ *        (large images, files) that exceed the encrypted control-stream's
+ *        single-frame limit (`clipboard_bridge::kMaxPayloadBytes`).
+ *
+ * Design:
+ *   * Producer (GUI agent or HTTP upload from a client) puts opaque bytes +
+ *     a MIME hint and gets back a freshly-minted UUID.
+ *   * Consumers (other clients via HTTP, or the GUI agent dispatching an
+ *     inbound large object) GET by id. Reads do NOT remove by default; the
+ *     TTL sweeper reclaims memory eventually so a client may retry on
+ *     transient network failures.
+ *   * No cross-process persistence — restarting Sunshine drops everything.
+ *     Acceptable: clipboard items are short-lived by nature, and the wire
+ *     KIND_REF that points here is also delivered over a live session.
+ *
+ * Eviction policy:
+ *   * Per-blob TTL (see `kBlobTtlSeconds`).
+ *   * Hard cap on total resident bytes (`kMaxStoreBytes`); when a put would
+ *     exceed it, oldest blobs are evicted FIFO until it fits, even if their
+ *     TTL hasn't expired.
+ *
+ * Threading: all public functions are thread-safe.
+ */
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "clipboard_bridge.h"  // for payload_t
+
+namespace clipboard_blob_store {
+  using payload_t = clipboard_bridge::payload_t;
+  using blob_id = std::string;  ///< UUID v4 (canonical 36-char hex form).
+
+  /// Per-blob hard size cap. Bigger uploads are rejected outright.
+  constexpr std::size_t kMaxBlobBytes = 50ULL * 1024 * 1024;  // 50 MiB
+
+  /// Total resident bytes cap across all blobs. FIFO eviction kicks in when
+  /// a put would exceed this, regardless of TTL.
+  constexpr std::size_t kMaxStoreBytes = 200ULL * 1024 * 1024;  // 200 MiB
+
+  /// Per-blob TTL after the most recent put. Reads do NOT extend the TTL.
+  constexpr int kBlobTtlSeconds = 60;
+
+  struct put_result_t {
+    blob_id id;       ///< Empty iff ok == false.
+    bool ok;
+    /// Reason for failure when !ok: "too_large" or "internal".
+    std::string err;
+  };
+
+  /// Store bytes + MIME and return a freshly-minted id. The caller's vector
+  /// is consumed. Triggers an opportunistic sweep + FIFO eviction.
+  put_result_t put(payload_t bytes, std::string mime);
+
+  struct get_result_t {
+    bool found;
+    payload_t bytes;
+    std::string mime;
+  };
+
+  /// Look up by id. `found == false` for missing or expired entries.
+  /// When `consume == true` the blob is removed on a successful read; useful
+  /// for one-shot semantics where the consumer is sole.
+  get_result_t get(const blob_id &id, bool consume = false);
+
+  /// Force expiry of stale entries. Called opportunistically by put(); tests
+  /// can also invoke it directly.
+  void sweep_expired();
+
+  /// Diagnostics — count and bytes of currently-resident entries.
+  struct stats_t {
+    std::size_t entries;
+    std::size_t bytes;
+  };
+
+  stats_t stats();
+}  // namespace clipboard_blob_store