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/

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/

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

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/

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

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

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

Response (200 OK)

{
  "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)

{
  "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:

1. Move A from 5 to 0: Track at position 5 becomes position 0, others shift
2. 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:

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