From 715c5a5fb9379330b5c84cb71fc6877b86db056e Mon Sep 17 00:00:00 2001
From: anthorob <tony@bobert.me>
Date: Sat, 3 Oct 2026 12:02:14 -0400
Subject: [PATCH] Add `search_id_ttl_seconds` to pending music responses

Enhanced pending response bodies in `MusicRoutes` to include `search_id_ttl_seconds`, indicating the time-to-live for `search_id`. Updated `QueueResponse` DTO and comments to support the new field. Introduced `ttlSeconds` method in `PendingSearchResults` for consistent TTL retrieval across components.
---
 .../me/bobert/netneutrality/http/server/MusicRoutes.java  | 3 +++
 .../netneutrality/http/server/dto/QueueResponse.java      | 8 +++++---
 .../bobert/netneutrality/music/PendingSearchResults.java  | 7 +++++++
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/src/main/java/me/bobert/netneutrality/http/server/MusicRoutes.java b/src/main/java/me/bobert/netneutrality/http/server/MusicRoutes.java
index e50e72b..b62d6d0 100644
--- a/src/main/java/me/bobert/netneutrality/http/server/MusicRoutes.java
+++ b/src/main/java/me/bobert/netneutrality/http/server/MusicRoutes.java
@@ -405,6 +405,7 @@ public final class MusicRoutes {
                 Map<String, Object> body = new LinkedHashMap<>();
                 body.put("status", "pending_track");
                 body.put("search_id", pendingTrack.searchId());
+                body.put("search_id_ttl_seconds", PendingSearchResults.ttlSeconds());
                 body.put("track", trackSummary(pendingTrack.track()));
                 yield body;
             }
@@ -412,6 +413,7 @@ public final class MusicRoutes {
                 Map<String, Object> body = new LinkedHashMap<>();
                 body.put("status", "pending_playlist");
                 body.put("search_id", pendingPlaylist.searchId());
+                body.put("search_id_ttl_seconds", PendingSearchResults.ttlSeconds());
                 body.put("tracks", pendingPlaylist.tracks().stream().map(MusicRoutes::trackSummary).toList());
                 body.put("truncated", pendingPlaylist.truncated());
                 yield body;
@@ -420,6 +422,7 @@ public final class MusicRoutes {
                 Map<String, Object> body = new LinkedHashMap<>();
                 body.put("status", "pending_search");
                 body.put("search_id", pendingSearch.searchId());
+                body.put("search_id_ttl_seconds", PendingSearchResults.ttlSeconds());
                 body.put("candidates", pendingSearch.candidates().stream().map(MusicRoutes::trackSummary).toList());
                 yield body;
             }
diff --git a/src/main/java/me/bobert/netneutrality/http/server/dto/QueueResponse.java b/src/main/java/me/bobert/netneutrality/http/server/dto/QueueResponse.java
index 257d9c6..96efed6 100644
--- a/src/main/java/me/bobert/netneutrality/http/server/dto/QueueResponse.java
+++ b/src/main/java/me/bobert/netneutrality/http/server/dto/QueueResponse.java
@@ -16,15 +16,17 @@ import java.util.List;
  * stashed as a pending candidate, to be confirmed via a follow-up {@code /music/{guildId}/queue}
  * call carrying {@code searchId}/{@code index}. Fields are nullable since only a subset is populated depending
  * on {@code status}: {@code queued} fills {@code track}/{@code queue_position} (confirmed
- * selection), {@code pending_track} fills {@code search_id}/{@code track}, {@code
- * pending_playlist} fills {@code search_id}/{@code tracks}/{@code truncated}, and {@code
- * pending_search} fills {@code search_id}/{@code candidates}.
+ * selection), {@code pending_track} fills {@code search_id}/{@code search_id_ttl_seconds}/{@code track}, {@code
+ * pending_playlist} fills {@code search_id}/{@code search_id_ttl_seconds}/{@code tracks}/{@code truncated}, and
+ * {@code pending_search} fills {@code search_id}/{@code search_id_ttl_seconds}/{@code candidates}.
+ * {@code search_id_ttl_seconds} indicates how many seconds remain before the {@code search_id} expires.
  */
 public record QueueResponse(
     String status,
     TrackSummaryResponse track,
     Integer queue_position,
     String search_id,
+    Long search_id_ttl_seconds,
     List<TrackSummaryResponse> tracks,
     Boolean truncated,
     List<TrackSummaryResponse> candidates
diff --git a/src/main/java/me/bobert/netneutrality/music/PendingSearchResults.java b/src/main/java/me/bobert/netneutrality/music/PendingSearchResults.java
index f933b10..2edfd5f 100644
--- a/src/main/java/me/bobert/netneutrality/music/PendingSearchResults.java
+++ b/src/main/java/me/bobert/netneutrality/music/PendingSearchResults.java
@@ -31,6 +31,13 @@ public final class PendingSearchResults {
     private PendingSearchResults() {
     }
 
+    /**
+     * Returns the TTL applied to newly stored entries, in seconds.
+     */
+    public static long ttlSeconds() {
+        return TTL.toSeconds();
+    }
+
     /**
      * Stores the given candidates under a newly generated search id, scoped to {@code guildId}.
      *