Add Playlist Reordering Skill

Implement track reordering within playlists using move operations with stable position management.

Overview

Playlist reordering allows users to change the order of tracks via move operations. Each move specifies a source position and target position.

Steps

1. Create Move Operation Model

Location: src/NovaTuneApp/NovaTuneApp.ApiService/Models/Playlists/

csharp

namespace NovaTuneApp.ApiService.Models.Playlists;

/// <summary>
/// Represents a single move operation in a reorder request.
/// </summary>
/// <param name="From">Current position of the track (0-based)</param>
/// <param name="To">Target position for the track (0-based)</param>
public record MoveOperation(int From, int To);

/// <summary>
/// Request to reorder tracks within a playlist.
/// </summary>
/// <param name="Moves">List of move operations (applied sequentially)</param>
public record ReorderRequest(IReadOnlyList<MoveOperation> Moves);

2. Add Validation

Location: src/NovaTuneApp/NovaTuneApp.ApiService/Validators/

csharp

using FluentValidation;

namespace NovaTuneApp.ApiService.Validators;

public class ReorderRequestValidator : AbstractValidator<ReorderRequest>
{
    public ReorderRequestValidator(IOptions<PlaylistOptions> options)
    {
        RuleFor(x => x.Moves)
            .NotEmpty()
            .WithMessage("At least one move operation is required")
            .Must(m => m.Count <= options.Value.MaxMovesPerReorderRequest)
            .WithMessage($"Maximum {options.Value.MaxMovesPerReorderRequest} moves per request");

        RuleForEach(x => x.Moves)
            .ChildRules(move =>
            {
                move.RuleFor(m => m.From)
                    .GreaterThanOrEqualTo(0)
                    .WithMessage("From position must be non-negative");

                move.RuleFor(m => m.To)
                    .GreaterThanOrEqualTo(0)
                    .WithMessage("To position must be non-negative");
            });
    }
}

3. Implement Reorder Logic in Service

Location: src/NovaTuneApp/NovaTuneApp.ApiService/Services/PlaylistService.cs

csharp

public async Task<PlaylistDetails> ReorderTracksAsync(
    string playlistId,
    string userId,
    ReorderRequest request,
    CancellationToken ct = default)
{
    var playlist = await _session.LoadAsync<Playlist>($"Playlists/{playlistId}", ct);

    if (playlist is null)
        throw new PlaylistNotFoundException(playlistId);

    if (playlist.UserId != userId)
        throw new PlaylistAccessDeniedException(playlistId);

    if (playlist.Tracks.Count == 0)
        throw new InvalidOperationException("Cannot reorder empty playlist");

    // Validate all positions before applying any moves
    foreach (var move in request.Moves)
    {
        if (move.From < 0 || move.From >= playlist.Tracks.Count)
            throw new InvalidPositionException(move.From, playlist.Tracks.Count);

        if (move.To < 0 || move.To >= playlist.Tracks.Count)
            throw new InvalidPositionException(move.To, playlist.Tracks.Count);
    }

    // Sort tracks by position to work with a proper list
    var tracks = playlist.Tracks.OrderBy(t => t.Position).ToList();

    // Apply moves sequentially
    foreach (var move in request.Moves)
    {
        if (move.From == move.To)
            continue; // No-op move

        var track = tracks[move.From];
        tracks.RemoveAt(move.From);
        tracks.Insert(move.To, track);
    }

    // Reassign positions to maintain contiguous 0-based indices
    for (var i = 0; i < tracks.Count; i++)
    {
        tracks[i].Position = i;
    }

    playlist.Tracks = tracks;
    playlist.UpdatedAt = DateTimeOffset.UtcNow;

    await _session.SaveChangesAsync(ct);

    _logger.LogInformation(
        "Reordered {MoveCount} tracks in playlist {PlaylistId} for user {UserId}",
        request.Moves.Count, playlistId, userId);

    return await MapToDetailsAsync(playlist, ct);
}

4. Create Custom Exception

Location: src/NovaTuneApp/NovaTuneApp.ApiService/Infrastructure/Exceptions/

csharp

namespace NovaTuneApp.ApiService.Infrastructure.Exceptions;

/// <summary>
/// Thrown when a position is out of valid range.
/// </summary>
public class InvalidPositionException : Exception
{
    public int Position { get; }
    public int MaxPosition { get; }

    public InvalidPositionException(int position, int trackCount)
        : base($"Position {position} is out of range. Valid range: 0 to {trackCount - 1}")
    {
        Position = position;
        MaxPosition = trackCount - 1;
    }
}

5. Add Endpoint

Location: src/NovaTuneApp/NovaTuneApp.ApiService/Endpoints/PlaylistEndpoints.cs

csharp

group.MapPost("/{playlistId}/reorder", HandleReorderTracks)
    .WithName("ReorderPlaylistTracks")
    .WithSummary("Reorder tracks within a playlist")
    .Produces<PlaylistDetails>(StatusCodes.Status200OK)
    .ProducesProblem(StatusCodes.Status400BadRequest)
    .ProducesProblem(StatusCodes.Status404NotFound)
    .ProducesProblem(StatusCodes.Status409Conflict)
    .RequireRateLimiting("playlist-reorder");

private static async Task<IResult> HandleReorderTracks(
    [FromRoute] string playlistId,
    [FromBody] ReorderRequest request,
    [FromServices] IPlaylistService playlistService,
    [FromServices] IValidator<ReorderRequest> validator,
    ClaimsPrincipal user,
    CancellationToken ct)
{
    if (!Ulid.TryParse(playlistId, out _))
    {
        return Results.Problem(
            title: "Invalid playlist ID",
            detail: "Playlist ID must be a valid ULID.",
            statusCode: StatusCodes.Status400BadRequest,
            type: "https://novatune.dev/errors/invalid-playlist-id");
    }

    var validationResult = await validator.ValidateAsync(request, ct);
    if (!validationResult.IsValid)
    {
        return Results.ValidationProblem(validationResult.ToDictionary());
    }

    var userId = user.FindFirstValue(ClaimTypes.NameIdentifier)!;

    try
    {
        var playlist = await playlistService.ReorderTracksAsync(
            playlistId, userId, request, ct);
        return Results.Ok(playlist);
    }
    catch (PlaylistNotFoundException)
    {
        return Results.Problem(
            title: "Playlist not found",
            statusCode: StatusCodes.Status404NotFound,
            type: "https://novatune.dev/errors/playlist-not-found");
    }
    catch (PlaylistAccessDeniedException)
    {
        return Results.Problem(
            title: "Access denied",
            statusCode: StatusCodes.Status403Forbidden,
            type: "https://novatune.dev/errors/forbidden");
    }
    catch (InvalidPositionException ex)
    {
        return Results.Problem(
            title: "Invalid position",
            detail: ex.Message,
            statusCode: StatusCodes.Status400BadRequest,
            type: "https://novatune.dev/errors/invalid-position",
            extensions: new Dictionary<string, object?>
            {
                ["position"] = ex.Position,
                ["maxPosition"] = ex.MaxPosition
            });
    }
    catch (ConcurrencyException)
    {
        return Results.Problem(
            title: "Concurrent modification",
            detail: "The playlist was modified by another request. Please retry.",
            statusCode: StatusCodes.Status409Conflict,
            type: "https://novatune.dev/errors/concurrency-conflict");
    }
}

Request/Response Examples

Request

json

POST /playlists/01HXK.../reorder
{
  "moves": [
    { "from": 5, "to": 0 },
    { "from": 10, "to": 3 }
  ]
}

Response (200 OK)

json

{
  "playlistId": "01HXK...",
  "name": "My Playlist",
  "trackCount": 20,
  "tracks": {
    "items": [
      { "position": 0, "trackId": "01HXL...", "title": "Moved Track" },
      { "position": 1, "trackId": "01HXM...", "title": "Second Track" }
    ],
    "hasMore": true
  }
}

Error Response (400 Bad Request)

json

{
  "type": "https://novatune.dev/errors/invalid-position",
  "title": "Invalid position",
  "status": 400,
  "detail": "Position 25 is out of range. Valid range: 0 to 19",
  "position": 25,
  "maxPosition": 19
}

Move Semantics

Moves are applied sequentially, which means:

Move A from 5 to 0: Track at position 5 becomes position 0, others shift
Move B from 10 to 3: Applied to the new state after Move A

This allows complex reorderings with predictable results.

Example: Moving track from end to beginning

Before: [A, B, C, D, E] (positions 0-4) Move: { "from": 4, "to": 0 } After: [E, A, B, C, D] (positions 0-4)

Example: Swapping two tracks

Before: [A, B, C, D, E] Moves: [{ "from": 0, "to": 4 }, { "from": 4, "to": 0 }] After Move 1: [B, C, D, E, A] After Move 2: [A, B, C, D, E] (back to original - this is NOT a swap)

For a true swap, use: [{ "from": 0, "to": 4 }, { "from": 3, "to": 0 }]

Alternative: Single Move Endpoint

For simpler UX, consider also exposing a single-move endpoint:

csharp

group.MapPost("/{playlistId}/tracks/{position:int}/move", HandleMoveTrack)
    .WithName("MovePlaylistTrack")
    .WithSummary("Move a single track to a new position");

Request: POST /playlists/01HXK.../tracks/5/move?to=0

Validation Rules

Rule	Error
Moves array not empty	400 Bad Request
Max 50 moves per request	400 Bad Request
From position in valid range	400 Bad Request
To position in valid range	400 Bad Request
Playlist exists	404 Not Found
User owns playlist	403 Forbidden

Performance Considerations

Embedded list: Track entries are embedded in the playlist document, so reordering is atomic
Position reindexing: O(n) operation where n = track count
Optimistic concurrency: Use RavenDB etag to detect concurrent modifications
Max moves limit: Prevents abuse and excessive computation

Stage 6 Documentation

Reorder API: doc/implementation/stage-6/09-api-reorder-tracks.md
Service Interface: doc/implementation/stage-6/10-service-interface.md
Test Strategy: doc/implementation/stage-6/18-test-strategy.md

Related Skills

implement-playlists - Full playlist implementation plan
add-playlist-tracks - Track add/remove operations
add-api-endpoint - Minimal API endpoint structure

Search AI Tools

add-playlist-reordering

Install this agent skill to your Project

SKILL.md

Add Playlist Reordering Skill

Overview

Steps

1. Create Move Operation Model

2. Add Validation

3. Implement Reorder Logic in Service

4. Create Custom Exception

5. Add Endpoint

Request/Response Examples

Request

Response (200 OK)

Error Response (400 Bad Request)

Move Semantics

Example: Moving track from end to beginning

Example: Swapping two tracks

Alternative: Single Move Endpoint

Validation Rules

Performance Considerations

Stage 6 Documentation

Related Skills