Add anonymous playback with an optional Spotify-style preview cap

New Playback:AllowAnonymousListening / Playback:AnonymousFragmentSeconds
settings control whether a request without a session can stream at all,
and if so, whether it's limited to a fragment instead of the full track:

- GET /tracks/{id}/stream and GET /youtube/tracks/{videoId}/stream no
  longer require authorization outright; the handlers gate on the config
  instead, so both keep working exactly as before when it's off (the
  default).
- The fragment cap is enforced by the Streaming Gateway, not the client:
  the stream ticket now carries an optional maxBytes claim (computed from
  AnonymousFragmentSeconds and the transcoder's known bitrate), and
  TicketValidationMiddleware clamps the Range it forwards to SeaweedFS to
  stay under it — synthesizing one if the request didn't send one, and
  answering 416 outright if the requested range starts past the cap.
- A YouTube track that hasn't been provisioned server-side yet streams
  straight from YouTube's CDN, bypassing the Gateway entirely — there's no
  way to cap that, so an anonymous request for one is refused (409) instead
  of silently handing out an uncapped stream.
- ListeningHistory has a non-nullable UserId, so anonymous plays simply
  don't get recorded rather than trying to force a row through the FK.

Also fixes a real, pre-existing bug this surfaced: the AppSettings.Development.json
of the Api, Worker, and StreamingGateway all pointed StreamTicket/Workers
paths at "../../deploy/..." — one directory short of deploy/'s actual
location at the repo root relative to each project's own folder. Docker
never hit this (it mounts an absolute /keys path), so it had apparently
never been exercised via `dotnet run` before.

backend/Core/Musify.Application/ApplicationDependencyInjection.cs

@@ -20,6 +20,7 @@ public static class ApplicationDependencyInjection
         services.AddValidatedOptions<MixConfiguration>(configuration, MixConfiguration.SectionName);
         services.AddValidatedOptions<StreamGatewayConfiguration>(configuration, StreamGatewayConfiguration.SectionName);
         services.AddValidatedOptions<UploadIntentConfiguration>(configuration, UploadIntentConfiguration.SectionName);
+        services.AddValidatedOptions<PlaybackConfiguration>(configuration, PlaybackConfiguration.SectionName);
 
         return services;
     }

backend/Core/Musify.Application/Configuration/PlaybackConfiguration.cs

@@ -0,0 +1,30 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Musify.Application.Configuration
+{
+    /// <summary>Controls whether listeners without a session can stream music at all, and if so,
+    /// how much of a track they get to hear before being cut off (a Spotify-style preview).</summary>
+    public sealed class PlaybackConfiguration
+    {
+        public const string SectionName = "Playback";
+
+        /// <summary>When false (the default), every stream endpoint requires a signed-in user, exactly
+        /// like before this setting existed. When true, an anonymous request is issued a stream ticket
+        /// too, capped by <see cref="AnonymousFragmentSeconds"/> if that is greater than zero.</summary>
+        public bool AllowAnonymousListening { get; set; }
+
+        /// <summary>How many seconds of a track an anonymous listener may hear, enforced by the
+        /// Streaming Gateway clamping the byte range it will serve for that ticket. Zero (the default)
+        /// means no cap: anonymous listeners hear the full track, same as a signed-in user. Ignored
+        /// when <see cref="AllowAnonymousListening"/> is false.</summary>
+        [Range(0, 3600)]
+        public int AnonymousFragmentSeconds { get; set; }
+
+        /// <summary>Bytes per second of the transcoded audio, used to turn <see cref="AnonymousFragmentSeconds"/>
+        /// into a byte cap for the stream ticket. Defaults to the app's own transcoder output (128 kbps
+        /// AAC, <c>AudioTranscoder:Ffmpeg:AudioBitrate</c>) — update this alongside that setting if it
+        /// ever changes, since the two aren't wired together.</summary>
+        [Range(1, int.MaxValue)]
+        public int EstimatedAudioBytesPerSecond { get; set; } = 16_000;
+    }
+}

backend/Core/Musify.Application/Contracts/IStreamTicketService.cs

@@ -2,7 +2,12 @@ namespace Musify.Application.Contracts
 {
     public interface IStreamTicketService
     {
-        StreamTicket IssueTicket(long userId, string keyPrefix);
+        /// <param name="userId">Null for an anonymous listener — the ticket is issued without a
+        /// <c>sub</c> claim.</param>
+        /// <param name="keyPrefix">The storage key (prefix) the ticket authorizes reading from.</param>
+        /// <param name="maxBytes">When set, the Streaming Gateway clamps the byte range it will serve
+        /// for this ticket to <c>[0, maxBytes)</c> — used for the anonymous preview fragment.</param>
+        StreamTicket IssueTicket(long? userId, string keyPrefix, long? maxBytes = null);
     }
 
     public record StreamTicket(string Token, int ExpiresInSeconds);

backend/Core/Musify.Application/Services/TrackStreamIssuer.cs

@@ -9,18 +9,20 @@ public sealed class TrackStreamIssuer(
     IDatabase database,
     IStreamTicketService ticketService,
     TrackConfiguration trackConfiguration,
-    StreamGatewayConfiguration streamGatewayConfiguration)
+    StreamGatewayConfiguration streamGatewayConfiguration,
+    PlaybackConfiguration playbackConfiguration)
 {
     public async Task<TrackStreamResponse> IssueAsync(
         Guid trackId,
         string audioFolderName,
-        long userId,
+        long? userId,
         CancellationToken cancellationToken)
     {
         var folderPath = trackConfiguration.Routes.BuildProcessedAudioPath(audioFolderName);
         var keyPrefix = $"{folderPath}/";
 
-        var ticket = ticketService.IssueTicket(userId, keyPrefix);
+        var maxBytes = AnonymousFragmentBytes(userId);
+        var ticket = ticketService.IssueTicket(userId, keyPrefix, maxBytes);
 
         var manifestUrl = string.Join('/',
             streamGatewayConfiguration.PublicBaseUrl.TrimEnd('/'),
@@ -28,14 +30,27 @@ public sealed class TrackStreamIssuer(
             folderPath,
             streamGatewayConfiguration.AudioFileName);
 
-        var newListeningHistory = new ListeningHistory
+        // Anonymous listeners have no User row to satisfy ListeningHistory's foreign key against, and
+        // their plays aren't "history" anyone can look back on anyway, so there's nothing to record.
+        if (userId is not null)
         {
-            UserId = userId,
-            TrackId = trackId,
-        };
-        await database.ListeningHistories.AddAsync(newListeningHistory, cancellationToken);
-        await database.SaveChangesAsync(cancellationToken);
+            var newListeningHistory = new ListeningHistory
+            {
+                UserId = userId.Value,
+                TrackId = trackId,
+            };
+            await database.ListeningHistories.AddAsync(newListeningHistory, cancellationToken);
+            await database.SaveChangesAsync(cancellationToken);
+        }
 
         return new TrackStreamResponse(manifestUrl, ticket.Token, ticket.ExpiresInSeconds);
     }
+
+    private long? AnonymousFragmentBytes(long? userId)
+    {
+        if (userId is not null || playbackConfiguration.AnonymousFragmentSeconds <= 0)
+            return null;
+
+        return (long)playbackConfiguration.AnonymousFragmentSeconds * playbackConfiguration.EstimatedAudioBytesPerSecond;
+    }
 }

backend/Core/Musify.Application/Tracks/GetTrackStream.cs

@@ -2,23 +2,30 @@ using ErrorOr;
 using Mediator;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging;
+using Musify.Application.Configuration;
 using Musify.Application.Contracts;
 using Musify.Application.Services;
 using Musify.Application.Tracks.Responses;
 
 namespace Musify.Application.Tracks
 {
-    public record GetTrackStreamQuery(Guid TrackId, long UserId)
+    /// <param name="UserId">Null for an anonymous request — allowed only when
+    /// <see cref="PlaybackConfiguration.AllowAnonymousListening"/> is enabled.</param>
+    public record GetTrackStreamQuery(Guid TrackId, long? UserId)
         : IQuery<ErrorOr<TrackStreamResponse>>;
 
     public class GetTrackStreamQueryHandler(
         IDatabase database,
         TrackStreamIssuer streamIssuer,
+        PlaybackConfiguration playbackConfiguration,
         ILogger<GetTrackStreamQueryHandler> logger)
         : IQueryHandler<GetTrackStreamQuery, ErrorOr<TrackStreamResponse>>
     {
         public async ValueTask<ErrorOr<TrackStreamResponse>> Handle(GetTrackStreamQuery request, CancellationToken cancellationToken)
         {
+            if (request.UserId is null && !playbackConfiguration.AllowAnonymousListening)
+                return Error.Unauthorized(description: "Sign in to stream music, or ask an administrator to enable anonymous listening.");
+
             var track = await database.Tracks.AsNoTracking()
                 .Where(t => t.Id == request.TrackId)
                 .Select(t => new { t.Id, t.Audio })
@@ -35,7 +42,7 @@ namespace Musify.Application.Tracks
 
             var response = await streamIssuer.IssueAsync(track.Id, track.Audio.FolderName, request.UserId, cancellationToken);
 
-            logger.LogInformation("Issued stream ticket for track {TrackId} to user {UserId}", request.TrackId, request.UserId);
+            logger.LogInformation("Issued stream ticket for track {TrackId} to user {UserId}", request.TrackId, request.UserId?.ToString() ?? "(anonymous)");
 
             return response;
         }

backend/Core/Musify.Application/YouTube/ResolveYouTubeTrackStream.cs

@@ -2,6 +2,7 @@ using ErrorOr;
 using Mediator;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging;
+using Musify.Application.Configuration;
 using Musify.Application.Contracts;
 using Musify.Application.Services;
 using Musify.Application.YouTube.Responses;
@@ -9,7 +10,9 @@ using Musify.Domain.Entities;
 
 namespace Musify.Application.YouTube
 {
-    public record ResolveYouTubeTrackStreamCommand(string VideoId, long UserId)
+    /// <param name="UserId">Null for an anonymous request — allowed only when
+    /// <see cref="PlaybackConfiguration.AllowAnonymousListening"/> is enabled.</param>
+    public record ResolveYouTubeTrackStreamCommand(string VideoId, long? UserId)
         : ICommand<ErrorOr<YouTubeStreamResponse>>;
 
     public class ResolveYouTubeTrackStreamCommandHandler(
@@ -17,14 +20,19 @@ namespace Musify.Application.YouTube
         IYouTubeMusicService youTubeMusicService,
         YouTubeTrackProvisioner provisioner,
         TrackStreamIssuer streamIssuer,
+        PlaybackConfiguration playbackConfiguration,
         ILogger<ResolveYouTubeTrackStreamCommandHandler> logger)
         : ICommandHandler<ResolveYouTubeTrackStreamCommand, ErrorOr<YouTubeStreamResponse>>
     {
         public async ValueTask<ErrorOr<YouTubeStreamResponse>> Handle(ResolveYouTubeTrackStreamCommand request, CancellationToken cancellationToken)
         {
+            var isAnonymous = request.UserId is null;
+            if (isAnonymous && !playbackConfiguration.AllowAnonymousListening)
+                return Error.Unauthorized(description: "Sign in to stream music, or ask an administrator to enable anonymous listening.");
+
             var track = await provisioner.FindAsync(request.VideoId, cancellationToken);
 
-            if (track != null&& track.Audio.IsProcessed)
+            if (track != null && track.Audio.IsProcessed)
             {
                 var serverStream = await streamIssuer.IssueAsync(track.Id, track.Audio.FolderName, request.UserId, cancellationToken);
                 return new YouTubeStreamResponse(
@@ -35,6 +43,13 @@ namespace Musify.Application.YouTube
                     serverStream.ExpiresInSeconds);
             }
 
+            // Below this point the only option left is streaming straight from YouTube's own CDN,
+            // which bypasses our Gateway (and its stream tickets) entirely — there's no way to cap that
+            // to the configured anonymous fragment, so an anonymous listener simply doesn't get it: they
+            // can retry once the track has been provisioned server-side, where the cap above applies.
+            if (isAnonymous && playbackConfiguration.AnonymousFragmentSeconds > 0)
+                return Error.Conflict(description: "This track isn't available for anonymous preview yet. Try again in a moment.");
+
             var streamInfo = await youTubeMusicService.GetAudioStreamAsync(request.VideoId, cancellationToken);
             if (streamInfo.IsError)
                 return streamInfo.Errors;
@@ -48,11 +63,11 @@ namespace Musify.Application.YouTube
                     logger.LogWarning("Could not provision YouTube track {VideoId}: {Error}", request.VideoId, provisionResult.FirstError.Description);
             }
 
-            if (track != null)
+            if (track != null && request.UserId is not null)
             {
                 await database.ListeningHistories.AddAsync(new ListeningHistory
                 {
-                    UserId = request.UserId,
+                    UserId = request.UserId.Value,
                     TrackId = track.Id,
                 }, cancellationToken);
 

backend/Core/Musify.Infrastructure/Services/StreamTicketService.cs

@@ -24,10 +24,16 @@ namespace Musify.Infrastructure.Services
             signingCredentials = new SigningCredentials(key, SecurityAlgorithms.RsaSha256);
         }
 
-        public StreamTicket IssueTicket(long userId, string keyPrefix)
+        public StreamTicket IssueTicket(long? userId, string keyPrefix, long? maxBytes = null)
         {
             var now = DateTimeOffset.UtcNow;
 
+            var claims = new Dictionary<string, object> { ["prefix"] = keyPrefix };
+            if (userId is not null)
+                claims["sub"] = userId.Value.ToString();
+            if (maxBytes is not null)
+                claims["maxBytes"] = maxBytes.Value.ToString();
+
             var descriptor = new SecurityTokenDescriptor
             {
                 Issuer = configuration.Issuer,
@@ -35,11 +41,7 @@ namespace Musify.Infrastructure.Services
                 IssuedAt = now.UtcDateTime,
                 NotBefore = now.UtcDateTime,
                 Expires = now.AddSeconds(configuration.TicketTtlSeconds).UtcDateTime,
-                Claims = new Dictionary<string, object>
-                {
-                    ["sub"] = userId.ToString(),
-                    ["prefix"] = keyPrefix,
-                },
+                Claims = claims,
                 SigningCredentials = signingCredentials,
             };