debug: add prints to syncPlaylistDetail()

fix: rename playlist tracks -> items
feat: fetching playlists without their tracks (untested)
2026-05-14 12:27:08 +02:00 · 2026-05-14 12:26:49 +02:00 · 2026-05-14 03:02:13 +02:00 · 2026-05-14 02:42:39 +02:00 · 2026-05-14 00:43:27 +02:00
17 changed files with 402 additions and 177 deletions
--- a/build.gradle
+++ b/build.gradle
@@ -1,3 +1,3 @@
 plugins {
-    id 'com.android.library' version '8.7.2' apply false
+    id 'com.android.library' version '8.6.0' apply false
 }
--- a/jukebox/src/main/java/at/lockstep/jukebox/DefaultPlaylistRepository.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/DefaultPlaylistRepository.java
@@ -9,6 +9,7 @@ import androidx.lifecycle.Transformations;
 import at.lockstep.jukebox.api.LockstepApiException;
 import at.lockstep.jukebox.api.PlaylistRemoteClient;
 import at.lockstep.jukebox.api.PlaylistRetrofitApi;
+import at.lockstep.jukebox.api.RetryOnRateLimitInterceptor;
 import at.lockstep.jukebox.db.JukeboxDatabase;
 import at.lockstep.jukebox.db.PlaylistDao;
 import at.lockstep.jukebox.db.PlaylistImageEntity;
@@ -65,6 +66,11 @@ public final class DefaultPlaylistRepository implements PlaylistRepository {
        syncCoordinator.syncDelta(retainRemovedPlaylists);
    }

+    @Override
+    public void syncPlaylistDetail(@NonNull String playlistId) throws IOException, LockstepApiException {
+        syncCoordinator.syncPlaylistDetail(playlistId);
+    }
+
    @Override
    @NonNull
    public LiveData<List<PlaylistSummary>> observePlaylists() {
@@ -124,7 +130,7 @@ public final class DefaultPlaylistRepository implements PlaylistRepository {
                row.getPlaylist().getDescription(),
                row.getPlaylist().getPrimaryColor(),
                row.getPlaylist().getSnapshotId(),
-                row.getPlaylist().getTracksTotal(),
+                row.getPlaylist().getItemsTotal(),
                urls
        );
    }
@@ -161,6 +167,7 @@ public final class DefaultPlaylistRepository implements PlaylistRepository {
                .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES)
                .create();
        okhttp3.OkHttpClient okHttp = new okhttp3.OkHttpClient.Builder()
+                .addInterceptor(new RetryOnRateLimitInterceptor())
                .addInterceptor(authInterceptor)
                .build();
        Retrofit retrofit = new Retrofit.Builder()
--- a/jukebox/src/main/java/at/lockstep/jukebox/PlaylistRepository.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/PlaylistRepository.java
@@ -16,6 +16,11 @@ public interface PlaylistRepository {

    void syncDelta(boolean retainRemovedPlaylists) throws IOException, LockstepApiException;

+    /**
+     * Fetches full playlist JSON for one id and replaces cached rows for that playlist only.
+     */
+    void syncPlaylistDetail(@NonNull String playlistId) throws IOException, LockstepApiException;
+
    @NonNull
    LiveData<List<PlaylistSummary>> observePlaylists();

--- a/jukebox/src/main/java/at/lockstep/jukebox/PlaylistSummary.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/PlaylistSummary.java
@@ -2,8 +2,6 @@ package at.lockstep.jukebox;

 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
-
-import java.util.Collections;
 import java.util.List;

 public final class PlaylistSummary {
@@ -18,8 +16,9 @@ public final class PlaylistSummary {
    public final String primaryColor;
    @NonNull
    public final String snapshotId;
+    /** Spotify simplified {@code tracks.total}, or full playlist {@code items.total} when synced. */
    @Nullable
-    public final Integer tracksTotal;
+    public final Integer itemsTotal;
    @NonNull
    public final List<String> imageUrls;

@@ -29,7 +28,7 @@ public final class PlaylistSummary {
            @Nullable String description,
            @Nullable String primaryColor,
            @NonNull String snapshotId,
-            @Nullable Integer tracksTotal,
+            @Nullable Integer itemsTotal,
            @NonNull List<String> imageUrls
    ) {
        this.id = id;
@@ -37,7 +36,7 @@ public final class PlaylistSummary {
        this.description = description;
        this.primaryColor = primaryColor;
        this.snapshotId = snapshotId;
-        this.tracksTotal = tracksTotal;
+        this.itemsTotal = itemsTotal;
        this.imageUrls = imageUrls;
    }

--- a/jukebox/src/main/java/at/lockstep/jukebox/api/RetryOnRateLimitInterceptor.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/api/RetryOnRateLimitInterceptor.java
@@ -0,0 +1,99 @@
+package at.lockstep.jukebox.api;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import java.io.IOException;
+import java.util.concurrent.ThreadLocalRandom;
+
+import okhttp3.Interceptor;
+import okhttp3.Request;
+import okhttp3.Response;
+
+/**
+ * Retries idempotent GET requests on HTTP 429 and 503 with exponential backoff, optional jitter,
+ * and {@code Retry-After} (seconds) when the server sends it. Helps when Lockstep proxies Spotify
+ * and inherits rate limits.
+ */
+public final class RetryOnRateLimitInterceptor implements Interceptor {
+
+    private final int maxRetries;
+    private final long initialBackoffMs;
+    private final double backoffMultiplier;
+    private final long maxBackoffMs;
+
+    public RetryOnRateLimitInterceptor() {
+        // Spotify / Lockstep can stay hot after bulk sync; extra attempts + longer cap help pairing-on-demand.
+        this(8, 1000L, 2.0, 120_000L);
+    }
+
+    public RetryOnRateLimitInterceptor(
+            int maxRetries,
+            long initialBackoffMs,
+            double backoffMultiplier,
+            long maxBackoffMs
+    ) {
+        this.maxRetries = maxRetries;
+        this.initialBackoffMs = initialBackoffMs;
+        this.backoffMultiplier = backoffMultiplier;
+        this.maxBackoffMs = maxBackoffMs;
+    }
+
+    @NonNull
+    @Override
+    public Response intercept(@NonNull Chain chain) throws IOException {
+        Request request = chain.request();
+        if (!"GET".equalsIgnoreCase(request.method())) {
+            return chain.proceed(request);
+        }
+
+        long backoffMs = initialBackoffMs;
+        Response response = chain.proceed(request);
+        for (int retry = 0; retry <= maxRetries; retry++) {
+            if (response.code() != 429 && response.code() != 503) {
+                return response;
+            }
+            if (retry == maxRetries) {
+                return response;
+            }
+            long retryAfterMs = parseRetryAfterMs(response.header("Retry-After"));
+            long waitMs = Math.max(backoffMs, retryAfterMs);
+            response.close();
+            sleepWithJitter(waitMs);
+            backoffMs = Math.min((long) (backoffMs * backoffMultiplier), maxBackoffMs);
+            response = chain.proceed(request);
+        }
+        return response;
+    }
+
+    private void sleepWithJitter(long baseMs) throws IOException {
+        if (baseMs <= 0) {
+            return;
+        }
+        long jitter = baseMs > 4 ? ThreadLocalRandom.current().nextLong(0, baseMs / 4) : 0L;
+        try {
+            Thread.sleep(baseMs + jitter);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new IOException("interrupted during rate-limit backoff", e);
+        }
+    }
+
+    /**
+     * Parses {@code Retry-After} as a delay in seconds (Spotify / many proxies use this form).
+     * HTTP-date form is not parsed; returns 0 so exponential backoff applies alone.
+     */
+    private static long parseRetryAfterMs(@Nullable String header) {
+        if (header == null || header.isEmpty()) {
+            return 0L;
+        }
+        try {
+            long seconds = Long.parseLong(header.trim());
+            if (seconds > 0) {
+                return Math.min(seconds * 1000L, 300_000L);
+            }
+        } catch (NumberFormatException ignored) {
+        }
+        return 0L;
+    }
+}
--- a/jukebox/src/main/java/at/lockstep/jukebox/api/dto/FullPlaylistDto.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/api/dto/FullPlaylistDto.java
@@ -10,7 +10,8 @@ public class FullPlaylistDto {
    public List<ImageDto> images;
    public String primaryColor;
    public String snapshotId;
-    public TracksPageDto tracks;
+    /** Paging object for playlist entries; Spotify key {@code items}. */
+    public PlaylistItemsPageDto items;

    public List<ImageDto> imagesOrEmpty() {
        return images != null ? images : Collections.emptyList();
--- a/jukebox/src/main/java/at/lockstep/jukebox/api/dto/PlaylistItemDto.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/api/dto/PlaylistItemDto.java
@@ -0,0 +1,10 @@
+package at.lockstep.jukebox.api.dto;
+
+/**
+ * One element of {@link PlaylistItemsPageDto#items}. Spotify nests the track under {@code item}
+ * (not {@code track}).
+ */
+public class PlaylistItemDto {
+    /** Nested playable (track) from Spotify; {@code null} when removed or unsupported. */
+    public TrackDto item;
+}
--- a/jukebox/src/main/java/at/lockstep/jukebox/api/dto/PlaylistItemsPageDto.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/api/dto/PlaylistItemsPageDto.java
@@ -0,0 +1,19 @@
+package at.lockstep.jukebox.api.dto;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Spotify full-playlist paging object keyed {@code items} at the playlist root:
+ * {@code playlist.items.href}, {@code playlist.items.total}, {@code playlist.items.items[]}.
+ */
+public class PlaylistItemsPageDto {
+    public String href;
+    public Integer total;
+    /** Playlist entries ({@link PlaylistItemDto}) in API order. */
+    public List<PlaylistItemDto> items;
+
+    public List<PlaylistItemDto> itemsOrEmpty() {
+        return items != null ? items : Collections.emptyList();
+    }
+}
--- a/jukebox/src/main/java/at/lockstep/jukebox/api/dto/PlaylistTrackItemDto.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/api/dto/PlaylistTrackItemDto.java
@@ -1,5 +0,0 @@
-package at.lockstep.jukebox.api.dto;
-
-public class PlaylistTrackItemDto {
-    public TrackDto track;
-}
--- a/jukebox/src/main/java/at/lockstep/jukebox/api/dto/TracksPageDto.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/api/dto/TracksPageDto.java
@@ -1,14 +0,0 @@
-package at.lockstep.jukebox.api.dto;
-
-import java.util.Collections;
-import java.util.List;
-
-public class TracksPageDto {
-    public String href;
-    public Integer total;
-    public List<PlaylistTrackItemDto> items;
-
-    public List<PlaylistTrackItemDto> itemsOrEmpty() {
-        return items != null ? items : Collections.emptyList();
-    }
-}
--- a/jukebox/src/main/java/at/lockstep/jukebox/db/JukeboxDatabase.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/db/JukeboxDatabase.java
@@ -14,7 +14,7 @@ import androidx.room.RoomDatabase;
                TrackEntity.class,
                PlaylistTrackEntity.class
        },
-        version = 1,
+        version = 2,
        exportSchema = false
 )
 public abstract class JukeboxDatabase extends RoomDatabase {
--- a/jukebox/src/main/java/at/lockstep/jukebox/db/PlaylistDao.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/db/PlaylistDao.java
@@ -29,7 +29,7 @@ public abstract class PlaylistDao {
    public void replacePlaylistContent(
            @NonNull PlaylistEntity playlist,
            @NonNull List<PlaylistImageEntity> images,
-            @NonNull List<TrackEntity> tracks,
+            @NonNull List<TrackEntity> trackEntities,
            @NonNull List<PlaylistTrackEntity> playlistTracks
    ) {
        upsertPlaylist(playlist);
@@ -38,8 +38,8 @@ public abstract class PlaylistDao {
            insertImages(images);
        }
        deletePlaylistTracksForPlaylist(playlist.getId());
-        if (!tracks.isEmpty()) {
-            upsertTracks(tracks);
+        if (!trackEntities.isEmpty()) {
+            upsertTracks(trackEntities);
        }
        if (!playlistTracks.isEmpty()) {
            insertPlaylistTracks(playlistTracks);
--- a/jukebox/src/main/java/at/lockstep/jukebox/db/PlaylistEntity.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/db/PlaylistEntity.java
@@ -27,13 +27,15 @@ public class PlaylistEntity {
    @ColumnInfo(name = "snapshot_id")
    private String snapshotId;

+    /** From Spotify paging {@code playlist.items.href} (full playlist) or simplified {@code tracks.href}. */
    @Nullable
-    @ColumnInfo(name = "tracks_href")
-    private String tracksHref;
+    @ColumnInfo(name = "items_href")
+    private String itemsHref;

+    /** Total count from paging object {@code playlist.items.total} or simplified {@code tracks.total}. */
    @Nullable
-    @ColumnInfo(name = "tracks_total")
-    private Integer tracksTotal;
+    @ColumnInfo(name = "items_total")
+    private Integer itemsTotal;

    public PlaylistEntity(
            @NonNull String id,
@@ -41,16 +43,16 @@ public class PlaylistEntity {
            @NonNull String name,
            @Nullable String primaryColor,
            @NonNull String snapshotId,
-            @Nullable String tracksHref,
-            @Nullable Integer tracksTotal
+            @Nullable String itemsHref,
+            @Nullable Integer itemsTotal
    ) {
        this.id = id;
        this.description = description;
        this.name = name;
        this.primaryColor = primaryColor;
        this.snapshotId = snapshotId;
-        this.tracksHref = tracksHref;
-        this.tracksTotal = tracksTotal;
+        this.itemsHref = itemsHref;
+        this.itemsTotal = itemsTotal;
    }

    @NonNull
@@ -99,20 +101,20 @@ public class PlaylistEntity {
    }

    @Nullable
-    public String getTracksHref() {
-        return tracksHref;
+    public String getItemsHref() {
+        return itemsHref;
    }

-    public void setTracksHref(@Nullable String tracksHref) {
-        this.tracksHref = tracksHref;
+    public void setItemsHref(@Nullable String itemsHref) {
+        this.itemsHref = itemsHref;
    }

    @Nullable
-    public Integer getTracksTotal() {
-        return tracksTotal;
+    public Integer getItemsTotal() {
+        return itemsTotal;
    }

-    public void setTracksTotal(@Nullable Integer tracksTotal) {
-        this.tracksTotal = tracksTotal;
+    public void setItemsTotal(@Nullable Integer itemsTotal) {
+        this.itemsTotal = itemsTotal;
    }
 }
--- a/jukebox/src/main/java/at/lockstep/jukebox/map/PlaylistMappers.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/map/PlaylistMappers.java
@@ -1,11 +1,14 @@
 package at.lockstep.jukebox.map;

+import android.util.Log;
+
 import androidx.annotation.NonNull;

 import at.lockstep.jukebox.api.dto.ArtistDto;
 import at.lockstep.jukebox.api.dto.FullPlaylistDto;
 import at.lockstep.jukebox.api.dto.ImageDto;
-import at.lockstep.jukebox.api.dto.PlaylistTrackItemDto;
+import at.lockstep.jukebox.api.dto.PlaylistItemDto;
+import at.lockstep.jukebox.api.dto.SimplifiedPlaylistDto;
 import at.lockstep.jukebox.api.dto.TrackDto;
 import at.lockstep.jukebox.db.PlaylistEntity;
 import at.lockstep.jukebox.db.PlaylistImageEntity;
@@ -24,6 +27,8 @@ import java.util.Map;
 */
 public final class PlaylistMappers {

+    private static final String TAG = "JukeboxPlaylist";
+
    private PlaylistMappers() {
    }

@@ -59,20 +64,57 @@ public final class PlaylistMappers {
    }

    /**
-     * Maps the playlist metadata from a full playlist response to a {@link PlaylistEntity} row.
+     * Maps a playlist list entry to a {@link PlaylistEntity} without playlist items loaded (shell row only).
+     * Uses simplified {@code tracks} stub ({@code href}, {@code total}).
     */
    @NonNull
-    public static PlaylistEntity toPlaylistEntity(@NonNull FullPlaylistDto dto) {
-        String tracksHref = dto.tracks != null ? dto.tracks.href : null;
-        Integer tracksTotal = dto.tracks != null ? dto.tracks.total : null;
+    public static PlaylistEntity toPlaylistEntity(@NonNull SimplifiedPlaylistDto dto) {
+        if (dto.id == null || dto.id.isEmpty()) {
+            throw new IllegalArgumentException("Simplified playlist missing id");
+        }
+        String itemsHref = dto.tracks != null ? dto.tracks.href : null;
+        Integer itemsTotal = dto.tracks != null ? dto.tracks.total : null;
+        String rawName = dto.name;
+        boolean unnamed = rawName == null || rawName.trim().isEmpty();
+        String displayName = unnamed ? "Untitled playlist" : rawName;
+        if (unnamed) {
+            Log.i(TAG, "Playlist has empty name, id=" + dto.id);
+        }
+        String snapshotId = dto.snapshotId != null ? dto.snapshotId : "";
        return new PlaylistEntity(
                dto.id,
                dto.description,
-                dto.name,
+                displayName,
                dto.primaryColor,
-                dto.snapshotId,
-                tracksHref,
-                tracksTotal
+                snapshotId,
+                itemsHref,
+                itemsTotal
+        );
+    }
+
+    /**
+     * Maps the playlist metadata from a full playlist response to a {@link PlaylistEntity} row.
+     * Uses root {@code items} paging object ({@code href}, {@code total}).
+     * Empty or whitespace-only {@code name} becomes {@code "Untitled playlist"} and is logged for debugging.
+     */
+    @NonNull
+    public static PlaylistEntity toPlaylistEntity(@NonNull FullPlaylistDto dto) {
+        String itemsHref = dto.items != null ? dto.items.href : null;
+        Integer itemsTotal = dto.items != null ? dto.items.total : null;
+        String rawName = dto.name;
+        boolean unnamed = rawName == null || rawName.trim().isEmpty();
+        String displayName = unnamed ? "Untitled playlist" : rawName;
+        if (unnamed) {
+            Log.i(TAG, "Playlist has empty name, id=" + dto.id);
+        }
+        return new PlaylistEntity(
+                dto.id,
+                dto.description,
+                displayName,
+                dto.primaryColor,
+                dto.snapshotId != null ? dto.snapshotId : "",
+                itemsHref,
+                itemsTotal
        );
    }

@@ -90,12 +132,12 @@ public final class PlaylistMappers {
        for (int i = 0; i < imageDtos.size(); i++) {
            images.add(toImageEntity(imageDtos.get(i), dto.id, i));
        }
-        List<PlaylistTrackItemDto> items = dto.tracks != null ? dto.tracks.itemsOrEmpty() : new ArrayList<>();
+        List<PlaylistItemDto> entries = dto.items != null ? dto.items.itemsOrEmpty() : new ArrayList<>();

        Map<String, TrackEntity> trackById = new LinkedHashMap<>();
-        for (PlaylistTrackItemDto wrapper : items) {
-            if (wrapper.track != null) {
-                TrackDto t = wrapper.track;
+        for (PlaylistItemDto wrapper : entries) {
+            if (wrapper.item != null) {
+                TrackDto t = wrapper.item;
                TrackEntity entity = new TrackEntity(
                        t.id,
                        t.name,
@@ -108,9 +150,9 @@ public final class PlaylistMappers {
        List<TrackEntity> trackEntities = new ArrayList<>(trackById.values());

        List<PlaylistTrackEntity> playlistTrackEntities = new ArrayList<>();
-        for (int i = 0; i < items.size(); i++) {
-            PlaylistTrackItemDto wrapper = items.get(i);
-            String tid = wrapper.track != null ? wrapper.track.id : null;
+        for (int i = 0; i < entries.size(); i++) {
+            PlaylistItemDto wrapper = entries.get(i);
+            String tid = wrapper.item != null ? wrapper.item.id : null;
            playlistTrackEntities.add(new PlaylistTrackEntity(dto.id, i, tid));
        }
        return new PlaylistStorageRows(images, trackEntities, playlistTrackEntities);
@@ -123,17 +165,17 @@ public final class PlaylistMappers {
        @NonNull
        public final List<PlaylistImageEntity> images;
        @NonNull
-        public final List<TrackEntity> tracks;
+        public final List<TrackEntity> trackEntities;
        @NonNull
        public final List<PlaylistTrackEntity> playlistTracks;

        public PlaylistStorageRows(
                @NonNull List<PlaylistImageEntity> images,
-                @NonNull List<TrackEntity> tracks,
+                @NonNull List<TrackEntity> trackEntities,
                @NonNull List<PlaylistTrackEntity> playlistTracks
        ) {
            this.images = images;
-            this.tracks = tracks;
+            this.trackEntities = trackEntities;
            this.playlistTracks = playlistTracks;
        }
    }
--- a/jukebox/src/main/java/at/lockstep/jukebox/sync/SyncCoordinator.java
+++ b/jukebox/src/main/java/at/lockstep/jukebox/sync/SyncCoordinator.java
@@ -1,87 +1,79 @@
 package at.lockstep.jukebox.sync;

+import android.util.Log;
+
 import androidx.annotation.NonNull;

 import at.lockstep.jukebox.api.LockstepApiException;
 import at.lockstep.jukebox.api.LockstepPlaylistClient;
 import at.lockstep.jukebox.api.dto.FullPlaylistDto;
+import at.lockstep.jukebox.api.dto.ImageDto;
+import at.lockstep.jukebox.api.dto.PlaylistItemDto;
 import at.lockstep.jukebox.api.dto.SimplifiedPlaylistDto;
+import at.lockstep.jukebox.api.dto.TrackDto;
 import at.lockstep.jukebox.db.PlaylistDao;
+import at.lockstep.jukebox.db.PlaylistEntity;
+import at.lockstep.jukebox.db.PlaylistImageEntity;
 import at.lockstep.jukebox.db.PlaylistSnapshotRow;
 import at.lockstep.jukebox.map.PlaylistMappers;
-import at.lockstep.jukebox.map.PlaylistMappers.PlaylistStorageRows;

 import java.io.IOException;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Set;
-import java.util.concurrent.ExecutionException;
-import java.util.concurrent.ExecutorService;
-import java.util.concurrent.Executors;
-import java.util.concurrent.Future;

 /**
 * Orchestrates loading playlist metadata from {@link LockstepPlaylistClient} and writing it into
- * {@link PlaylistDao}: full initial import (clear + fetch all details) and incremental sync using
- * {@code snapshot_id} from the playlist list endpoint. Individual playlists are always replaced
- * wholesale (images, memberships, and tracks for that playlist) inside a single DAO transaction.
+ * {@link PlaylistDao}.
 * <p>
- * Network detail fetches run in parallel up to the pool size passed to
- * {@link #SyncCoordinator(PlaylistDao, LockstepPlaylistClient, int)}; methods block until finished and
- * must not be called on the Android main thread.
+ * Normal refreshes use {@link #syncDelta(boolean)}: only the playlist <em>list</em> endpoint (names, images,
+ * snapshot ids). When a playlist's snapshot changes, its cached track rows are cleared until the user opens
+ * it again. Full track lists load lazily via {@link #syncPlaylistDetail(String)}.
+ * <p>
+ * {@link #syncInitial()} performs a full reset ({@link PlaylistDao#clearAllTables()}) then persists list
+ * metadata only—use rarely; prefer {@link #syncDelta(boolean)} so lazily loaded tracks survive app restarts.
+ * <p>
+ * Methods block until finished and must not be called on the Android main thread.
 */
 public final class SyncCoordinator {

+    private static final String TAG = "SyncCoordinator";
+
+    /** Cap per-item title/artist lines so huge playlists do not overwhelm logcat. */
+    private static final int SYNC_DETAIL_TITLE_LOG_LIMIT = 50;
+
+    private static final int SYNC_DETAIL_NULL_TRACK_LOG_LIMIT = 15;
+
    private final PlaylistDao dao;
    private final LockstepPlaylistClient remote;
-    private final int detailParallelism;

-    /**
-     * @param detailParallelism maximum concurrent calls to {@link LockstepPlaylistClient#fetchPlaylistDetail(String)}
-     */
-    public SyncCoordinator(
-            @NonNull PlaylistDao dao,
-            @NonNull LockstepPlaylistClient remote,
-            int detailParallelism
-    ) {
+    public SyncCoordinator(@NonNull PlaylistDao dao, @NonNull LockstepPlaylistClient remote) {
        this.dao = dao;
        this.remote = remote;
-        this.detailParallelism = detailParallelism;
    }

    /**
-     * Same as {@link #SyncCoordinator(PlaylistDao, LockstepPlaylistClient, int)} with parallel detail
-     * concurrency of {@code 6}.
-     */
-    public SyncCoordinator(@NonNull PlaylistDao dao, @NonNull LockstepPlaylistClient remote) {
-        this(dao, remote, 6);
-    }
-
-    /**
-     * Clears all local cache tables, fetches every playlist id from the list endpoint, loads each full
-     * playlist, and persists them. Use for first-time or “reset” sync.
+     * Fetches playlist summaries, clears local cache, and stores list metadata and cover images only
+     * (no per-playlist track fetch). Network I/O is list-only so opening the app does not fan out
+     * {@code GET /playlists/{id}} for every playlist.
     */
    public void syncInitial() throws IOException, LockstepApiException {
-        dao.clearAllTables();
        List<SimplifiedPlaylistDto> summaries = remote.fetchPlaylistSummaries();
-        List<String> ids = new ArrayList<>(summaries.size());
+        dao.clearAllTables();
        for (SimplifiedPlaylistDto s : summaries) {
-            ids.add(s.id);
-        }
-        List<FullPlaylistDto> details = fetchDetailsParallel(ids);
-        for (FullPlaylistDto detail : details) {
-            persistFullPlaylist(detail);
+            persistPlaylistShellFromSummary(s);
        }
    }

    /**
-     * Fetches the current playlist list, compares each {@code snapshot_id} to the local DB, and refetches
-     * full detail only for new or changed playlists. Playlists missing from the remote list are deleted
-     * locally (including cascading images and track links) only when {@code retainRemovedPlaylists} is
-     * {@code false}, in which case orphan {@link at.lockstep.jukebox.db.TrackEntity} rows are pruned.
+     * Fetches the playlist list, updates local shells when a playlist is new or its {@code snapshot_id}
+     * changed, and optionally drops removed playlists. Does not call the detail endpoint; when a snapshot
+     * changes, cached track rows for that playlist are cleared until the user opens it again.
     */
    public void syncDelta(boolean retainRemovedPlaylists) throws IOException, LockstepApiException {
        List<SimplifiedPlaylistDto> remoteSummaries = remote.fetchPlaylistSummaries();
@@ -89,22 +81,23 @@ public final class SyncCoordinator {
        for (PlaylistSnapshotRow row : dao.getPlaylistSnapshots()) {
            localSnapshots.put(row.id, row.snapshotId);
        }
-        List<String> idsToRefresh = new ArrayList<>();
        for (SimplifiedPlaylistDto summary : remoteSummaries) {
+            if (summary.id == null || summary.id.isEmpty()) {
+                continue;
+            }
+            String remoteSnap = summary.snapshotId != null ? summary.snapshotId : "";
            String local = localSnapshots.get(summary.id);
-            if (local == null || !local.equals(summary.snapshotId)) {
-                idsToRefresh.add(summary.id);
+            if (local == null || !local.equals(remoteSnap)) {
+                persistPlaylistShellFromSummary(summary);
            }
        }
-        List<FullPlaylistDto> details = fetchDetailsParallel(idsToRefresh);
-        for (FullPlaylistDto detail : details) {
-            persistFullPlaylist(detail);
-        }
        if (!retainRemovedPlaylists) {
            Set<String> remoteIds = new HashSet<>();
            for (SimplifiedPlaylistDto s : remoteSummaries) {
+                if (s.id != null && !s.id.isEmpty()) {
                    remoteIds.add(s.id);
                }
+            }
            List<String> removedLocally = new ArrayList<>();
            for (String localId : localSnapshots.keySet()) {
                if (!remoteIds.contains(localId)) {
@@ -113,60 +106,119 @@ public final class SyncCoordinator {
            }
            if (!removedLocally.isEmpty()) {
                dao.deletePlaylistsByIds(removedLocally);
+            }
+        }
        dao.deleteOrphanTracks();
    }
+
+    private void persistPlaylistShellFromSummary(@NonNull SimplifiedPlaylistDto s) {
+        if (s.id == null || s.id.isEmpty()) {
+            return;
        }
+        PlaylistEntity playlist = PlaylistMappers.toPlaylistEntity(s);
+        List<PlaylistImageEntity> images = new ArrayList<>();
+        List<ImageDto> imageDtos = s.imagesOrEmpty();
+        for (int i = 0; i < imageDtos.size(); i++) {
+            images.add(PlaylistMappers.toImageEntity(imageDtos.get(i), s.id, i));
+        }
+        dao.replacePlaylistContent(
+                playlist,
+                images,
+                Collections.emptyList(),
+                Collections.emptyList()
+        );
    }

    /**
-     * Loads full playlist JSON for each id using a bounded thread pool; preserves input order in the result.
+     * Fetches {@code GET /playlists/{playlistId}} and replaces cached images, tracks, and memberships for
+     * that playlist only.
     */
-    @NonNull
-    private List<FullPlaylistDto> fetchDetailsParallel(@NonNull List<String> ids)
-            throws IOException, LockstepApiException {
-        if (ids.isEmpty()) {
-            return new ArrayList<>();
+    public void syncPlaylistDetail(@NonNull String playlistId) throws IOException, LockstepApiException {
+        Log.d(TAG, "syncPlaylistDetail start requestedId=" + playlistId);
+        FullPlaylistDto detail = remote.fetchPlaylistDetail(playlistId);
+        String resolvedId = detail.id;
+        Log.d(
+                TAG,
+                "syncPlaylistDetail fetched resolvedId="
+                        + resolvedId
+                        + " requestedMatch="
+                        + Objects.equals(playlistId, resolvedId)
+                        + " name="
+                        + detail.name
+                        + " snapshotId="
+                        + detail.snapshotId
+        );
+        if (detail.items == null) {
+            Log.w(TAG, "syncPlaylistDetail: detail.items is null (no playlist items page in response)");
+        } else {
+            List<PlaylistItemDto> entries = detail.items.itemsOrEmpty();
+            int withItem = 0;
+            int withoutItem = 0;
+            int titlesLogged = 0;
+            int nullItemLogged = 0;
+            for (int i = 0; i < entries.size(); i++) {
+                PlaylistItemDto w = entries.get(i);
+                if (w.item != null) {
+                    withItem++;
+                    if (titlesLogged < SYNC_DETAIL_TITLE_LOG_LIMIT) {
+                        TrackDto t = w.item;
+                        Log.d(
+                                TAG,
+                                "syncPlaylistDetail items[" + i + "] id=" + t.id
+                                        + " title=" + t.name
+                                        + " artist="
+                                        + PlaylistMappers.artistDisplayName(t.artistsOrEmpty()));
+                        titlesLogged++;
                    }
-        ExecutorService pool = Executors.newFixedThreadPool(detailParallelism);
-        try {
-            List<Future<FullPlaylistDto>> futures = new ArrayList<>(ids.size());
-            for (String id : ids) {
-                futures.add(pool.submit(() -> remote.fetchPlaylistDetail(id)));
+                } else {
+                    withoutItem++;
+                    if (nullItemLogged < SYNC_DETAIL_NULL_TRACK_LOG_LIMIT) {
+                        Log.d(
+                                TAG,
+                                "syncPlaylistDetail items[" + i + "] (null item; e.g. removed or unsupported type)");
+                        nullItemLogged++;
                    }
-            List<FullPlaylistDto> out = new ArrayList<>(ids.size());
-            try {
-                for (Future<FullPlaylistDto> f : futures) {
-                    out.add(f.get());
                }
-            } catch (InterruptedException e) {
-                Thread.currentThread().interrupt();
-                throw new IOException(e);
-            } catch (ExecutionException e) {
-                Throwable c = e.getCause();
-                if (c instanceof IOException) {
-                    throw (IOException) c;
            }
-                if (c instanceof LockstepApiException) {
-                    throw (LockstepApiException) c;
-                }
-                throw new IOException(c != null ? c : e);
-            }
-            return out;
-        } finally {
-            pool.shutdown();
+            Integer total = detail.items.total;
+            Log.d(
+                    TAG,
+                    "syncPlaylistDetail items page: entryCount="
+                            + entries.size()
+                            + " entriesWithItem="
+                            + withItem
+                            + " entriesWithNullItem="
+                            + withoutItem
+                            + " paging.total="
+                            + total
+                            + " titleArtistLinesLogged="
+                            + titlesLogged
+                            + (withItem > titlesLogged
+                                    ? " (cap=" + SYNC_DETAIL_TITLE_LOG_LIMIT + ", see SyncCoordinator constants)"
+                                    : "")
+            );
        }
+        PlaylistMappers.PlaylistStorageRows rows = PlaylistMappers.toPlaylistStorageRows(detail);
+        Log.d(
+                TAG,
+                "syncPlaylistDetail after map: dedupedTrackEntities="
+                        + rows.trackEntities.size()
+                        + " playlistTrackRows="
+                        + rows.playlistTracks.size()
+        );
+        persistFullPlaylist(detail, rows);
    }

-    /**
-     * Maps {@code detail} to entities and runs {@link PlaylistDao#replacePlaylistContent} for that playlist.
-     */
-    private void persistFullPlaylist(@NonNull FullPlaylistDto detail) {
-        PlaylistStorageRows rows = PlaylistMappers.toPlaylistStorageRows(detail);
+    private void persistFullPlaylist(
+            @NonNull FullPlaylistDto detail,
+            @NonNull PlaylistMappers.PlaylistStorageRows rows
+    ) {
        dao.replacePlaylistContent(
                PlaylistMappers.toPlaylistEntity(detail),
                rows.images,
-                rows.tracks,
+                rows.trackEntities,
                rows.playlistTracks
        );
+        Log.d(TAG, "syncPlaylistDetail persisted replacePlaylistContent for id=" + detail.id);
    }
 }
--- a/jukebox/src/test/java/at/lockstep/jukebox/sync/SyncCoordinatorTest.java
+++ b/jukebox/src/test/java/at/lockstep/jukebox/sync/SyncCoordinatorTest.java
@@ -17,10 +17,10 @@ import at.lockstep.jukebox.api.LockstepApiException;
 import at.lockstep.jukebox.api.LockstepPlaylistClient;
 import at.lockstep.jukebox.api.dto.FullPlaylistDto;
 import at.lockstep.jukebox.api.dto.ImageDto;
-import at.lockstep.jukebox.api.dto.PlaylistTrackItemDto;
+import at.lockstep.jukebox.api.dto.PlaylistItemsPageDto;
+import at.lockstep.jukebox.api.dto.PlaylistItemDto;
 import at.lockstep.jukebox.api.dto.SimplifiedPlaylistDto;
 import at.lockstep.jukebox.api.dto.TrackDto;
-import at.lockstep.jukebox.api.dto.TracksPageDto;
 import at.lockstep.jukebox.db.JukeboxDatabase;
 import at.lockstep.jukebox.db.TrackRow;
 import at.lockstep.jukebox.map.PlaylistMappers;
@@ -53,34 +53,45 @@ public class SyncCoordinatorTest {
    }

    @Test
-    public void syncDelta_sameSnapshot_skipsDetailFetch() throws Exception {
+    public void syncInitial_listOnly_noDetailCalls() throws Exception {
        FakeRemote remote = new FakeRemote();
        remote.listItems.add(simplified("p1", "snap1"));
        remote.details.put("p1", detailWithTrack("p1", "snap1", "t1", "Song"));
        SyncCoordinator coordinator = new SyncCoordinator(db.playlistDao(), remote);
        coordinator.syncInitial();
+        Assert.assertTrue(remote.detailCallIds.isEmpty());
+        Assert.assertTrue(db.playlistDao().getTracksForPlaylist("p1").isEmpty());
+    }
+
+    @Test
+    public void syncDelta_sameSnapshot_skipsShellRewrite() throws Exception {
+        FakeRemote remote = new FakeRemote();
+        remote.listItems.add(simplified("p1", "snap1"));
+        SyncCoordinator coordinator = new SyncCoordinator(db.playlistDao(), remote);
+        coordinator.syncInitial();
        remote.detailCallIds.clear();
        coordinator.syncDelta(true);
        Assert.assertTrue(remote.detailCallIds.isEmpty());
    }

    @Test
-    public void syncDelta_changedSnapshot_refetchesDetail() throws Exception {
+    public void syncDelta_changedSnapshot_clearsTracksWithoutDetailFetch() throws Exception {
        FakeRemote remote = new FakeRemote();
        remote.listItems.add(simplified("p1", "s1"));
        remote.details.put("p1", detailWithTrack("p1", "s1", "t1", "Old"));
        SyncCoordinator coordinator = new SyncCoordinator(db.playlistDao(), remote);
        coordinator.syncInitial();
+        coordinator.syncPlaylistDetail("p1");
+        Assert.assertEquals(1, db.playlistDao().getTracksForPlaylist("p1").size());
+
        remote.listItems.clear();
        remote.listItems.add(simplified("p1", "s2"));
        remote.details.put("p1", detailWithTrack("p1", "s2", "t2", "New"));
        remote.detailCallIds.clear();
        coordinator.syncDelta(true);
-        Assert.assertEquals(Collections.singletonList("p1"), remote.detailCallIds);
+        Assert.assertTrue(remote.detailCallIds.isEmpty());
        List<TrackRow> tracks = db.playlistDao().getTracksForPlaylist("p1");
-        Assert.assertEquals(1, tracks.size());
-        Assert.assertEquals("t2", tracks.get(0).trackId);
-        Assert.assertEquals("New", tracks.get(0).trackName);
+        Assert.assertEquals(0, tracks.size());
    }

    @Test
@@ -88,8 +99,6 @@ public class SyncCoordinatorTest {
        FakeRemote remote = new FakeRemote();
        remote.listItems.add(simplified("p1", "s1"));
        remote.listItems.add(simplified("gone", "sg"));
-        remote.details.put("p1", minimalDetail("p1", "s1"));
-        remote.details.put("gone", minimalDetail("gone", "sg"));
        SyncCoordinator coordinator = new SyncCoordinator(db.playlistDao(), remote);
        coordinator.syncInitial();
        remote.listItems.clear();
@@ -103,7 +112,6 @@ public class SyncCoordinatorTest {
    public void syncDelta_retainsRemovedPlaylist() throws Exception {
        FakeRemote remote = new FakeRemote();
        remote.listItems.add(simplified("p1", "s1"));
-        remote.details.put("p1", minimalDetail("p1", "s1"));
        SyncCoordinator coordinator = new SyncCoordinator(db.playlistDao(), remote);
        coordinator.syncInitial();
        FullPlaylistDto orphan = minimalDetail("orphan", "so");
@@ -111,7 +119,7 @@ public class SyncCoordinatorTest {
        db.playlistDao().replacePlaylistContent(
                PlaylistMappers.toPlaylistEntity(orphan),
                rows.images,
-                rows.tracks,
+                rows.trackEntities,
                rows.playlistTracks
        );
        coordinator.syncDelta(true);
@@ -151,16 +159,16 @@ public class SyncCoordinatorTest {
        d.snapshotId = snap;
        d.images = List.of(new ImageDto());
        d.images.get(0).url = "https://x.example/a.png";
-        TracksPageDto page = new TracksPageDto();
-        PlaylistTrackItemDto item = new PlaylistTrackItemDto();
+        PlaylistItemsPageDto page = new PlaylistItemsPageDto();
+        PlaylistItemDto item = new PlaylistItemDto();
        TrackDto t = new TrackDto();
        t.id = trackId;
        t.name = trackName;
        t.durationMs = 1000;
-        item.track = t;
+        item.item = t;
        page.items = new ArrayList<>();
        page.items.add(item);
-        d.tracks = page;
+        d.items = page;
        return d;
    }

--- a/schema/playlist_cache.sql
+++ b/schema/playlist_cache.sql
@@ -11,8 +11,8 @@ CREATE TABLE playlists (
  name TEXT NOT NULL,
  primary_color TEXT,
  snapshot_id TEXT NOT NULL,
-  tracks_href TEXT,
-  tracks_total INTEGER
+  items_href TEXT,
+  items_total INTEGER
 );

 CREATE TABLE playlist_images (
@@ -33,8 +33,8 @@ CREATE TABLE tracks (
  duration_ms INTEGER NOT NULL
 );

-- Order of tracks in a playlist (matches playlist.tracks.items[] order).
-- track_id NULL when the API returns a removed track (wrapper with track: null).
+-- Order of tracks in a playlist (matches playlist.items.items[] order).
+-- track_id NULL when the API returns a removed entry (wrapper with item: null).
 CREATE TABLE playlist_tracks (
  playlist_id TEXT NOT NULL REFERENCES playlists (id) ON DELETE CASCADE,
  position INTEGER NOT NULL,
Author	SHA1	Message	Date
David Madl	b6a0bb35a9	debug: add prints to syncPlaylistDetail()	2026-05-14 12:27:08 +02:00
David Madl	d2d6500e23	fix: rename playlist tracks -> items	2026-05-14 12:26:49 +02:00
David Madl	8a7265194c	feat: fetching playlists without their tracks (untested)	2026-05-14 03:02:13 +02:00
David Madl	e139e810a3	feat: backoff, sync 1 playlist, keep half-gotten playlists	2026-05-14 02:42:39 +02:00
David Madl	f0df38c98b	chore: downgrade AGP to 8.6.0 for my Android Studio	2026-05-14 00:43:27 +02:00