sonda/internal/playlists/playlists.go
tgiachi a880b87a9e chore: move the module path to git.kmalloc.org/squid/sonda
Migrating hosting from Codeberg to git.kmalloc.org. Renames the
module path in go.mod, every internal import, and the OCI image
source label in the Dockerfile. Build and full test suite verified
green after the rename.
2026-11-15 17:30:29 +01:00

281 lines
9 KiB
Go

// Package playlists keeps the playlists of each user: named, ordered lists of tracks that only
// their owner sees. Nothing here contacts anyone.
//
// A track can be in a playlist more than once, so an item has an id of its own, and the place of
// an item (its position) counts from 0 without gaps. A track whose files were deleted or moved
// away stays in its playlists and is listed as not available: it is not lost.
//
// A playlist that belongs to somebody else is as if it did not exist (ErrNotFound), so nobody
// can find out which ids are in use.
package playlists
import (
"context"
"errors"
"fmt"
"strings"
"time"
"unicode/utf8"
"git.kmalloc.org/squid/sonda/internal/catalog"
)
// Limits. They keep one user from filling the database and one request from doing too much.
const (
MaxNameLen = 200
MaxDescriptionLen = 2000
MaxAddAtOnce = 500 // track ids in one request
MaxItems = 10_000 // tracks in one playlist
MaxPlaylists = 1_000 // playlists of one user
DefaultLimit = 50
MaxLimit = 200
)
// Errors returned by the service and the store.
var (
ErrInvalidInput = errors.New("invalid input")
ErrNotFound = errors.New("playlist not found")
ErrItemNotFound = errors.New("item not found in the playlist")
ErrTrackNotFound = errors.New("track not found")
ErrPosition = errors.New("position out of range")
ErrTooMany = errors.New("limit reached")
)
// Playlist is a playlist and what it holds, counted over all its items, available or not.
type Playlist struct {
ID int64
Name string
Description string
TrackCount int
DurationMs int64
CreatedAt time.Time
UpdatedAt time.Time
// AlbumIDs are up to MaxCoverAlbums albums that have a cover and stand for the playlist, in the order they first
// appear in it, each once. Empty when none of its songs has an album with a cover.
AlbumIDs []int64
}
// MaxCoverAlbums is how many albums make the picture of a playlist.
const MaxCoverAlbums = 4
// Item is one place of a playlist. Available says whether the track has a file to play.
type Item struct {
ID int64
Position int
Track catalog.Track
Available bool
AddedAt time.Time
}
// Page says which part of a list is wanted.
type Page struct {
Limit int
Offset int
}
// Store keeps the playlists. Every call is for one user and gives ErrNotFound for a playlist
// that does not exist or is not theirs. Calls that change a playlist do it in one transaction
// and set its updated time.
type Store interface {
// Create makes an empty playlist, or gives ErrTooMany when the user has MaxPlaylists.
Create(ctx context.Context, userID int64, name, description string, now time.Time) (Playlist, error)
// List returns a page of the user's playlists, the one changed last first, and how many there are.
List(ctx context.Context, userID int64, limit, offset int) ([]Playlist, int, error)
Get(ctx context.Context, userID, id int64) (Playlist, error)
// Update changes the name and/or the description that are not nil.
Update(ctx context.Context, userID, id int64, name, description *string, now time.Time) (Playlist, error)
Delete(ctx context.Context, userID, id int64) error
// Items returns a page of the playlist in order, and how many items it has.
Items(ctx context.Context, userID, id int64, limit, offset int) ([]Item, int, error)
// AddTracks puts the tracks at position (at the end when nil), in the order given, and
// returns the playlist. It gives ErrTrackNotFound when one of them does not exist (nothing
// is added), ErrPosition when position is beyond the end, and ErrTooMany when the
// playlist would have more than MaxItems.
AddTracks(ctx context.Context, userID, id int64, trackIDs []int64, position *int, now time.Time) (Playlist, error)
// RemoveItem takes an item out and closes the gap; ErrItemNotFound for one that is not in it.
RemoveItem(ctx context.Context, userID, id, itemID int64, now time.Time) error
// MoveItem puts an item at a position (0 to the number of items less one), ErrPosition otherwise.
MoveItem(ctx context.Context, userID, id, itemID int64, position int, now time.Time) error
}
// Service validates what it is given and keeps the playlists.
type Service struct{ store Store }
// NewService builds a Service.
func NewService(store Store) *Service { return &Service{store: store} }
func invalid(format string, a ...any) error {
return fmt.Errorf("%w: %s", ErrInvalidInput, fmt.Sprintf(format, a...))
}
func cleanName(name string) (string, error) {
name = strings.TrimSpace(name)
if name == "" || utf8.RuneCountInString(name) > MaxNameLen {
return "", invalid("the name must have 1 to %d characters", MaxNameLen)
}
return name, nil
}
func cleanDescription(d string) (string, error) {
d = strings.TrimSpace(d)
if utf8.RuneCountInString(d) > MaxDescriptionLen {
return "", invalid("the description can have up to %d characters", MaxDescriptionLen)
}
return d, nil
}
func cleanPage(p Page) (Page, error) {
if p.Limit < 0 || p.Offset < 0 {
return p, invalid("limit and offset cannot be negative")
}
switch {
case p.Limit == 0:
p.Limit = DefaultLimit
case p.Limit > MaxLimit:
p.Limit = MaxLimit
}
return p, nil
}
// Create makes a playlist.
func (s *Service) Create(ctx context.Context, userID int64, name, description string) (Playlist, error) {
name, err := cleanName(name)
if err != nil {
return Playlist{}, err
}
description, err = cleanDescription(description)
if err != nil {
return Playlist{}, err
}
return s.store.Create(ctx, userID, name, description, time.Now())
}
// List returns a page of the user's playlists.
func (s *Service) List(ctx context.Context, userID int64, p Page) (Listing, error) {
p, err := cleanPage(p)
if err != nil {
return Listing{}, err
}
items, total, err := s.store.List(ctx, userID, p.Limit, p.Offset)
if err != nil {
return Listing{}, err
}
return Listing{Items: items, Total: total, Limit: p.Limit, Offset: p.Offset}, nil
}
// Listing is a page of playlists.
type Listing struct {
Items []Playlist
Total int
Limit int
Offset int
}
// Get returns a playlist.
func (s *Service) Get(ctx context.Context, userID, id int64) (Playlist, error) {
if id <= 0 {
return Playlist{}, ErrNotFound
}
return s.store.Get(ctx, userID, id)
}
// Update changes the name and/or the description. An empty description clears it.
func (s *Service) Update(ctx context.Context, userID, id int64, name, description *string) (Playlist, error) {
if id <= 0 {
return Playlist{}, ErrNotFound
}
if name == nil && description == nil {
return Playlist{}, invalid("nothing to change: give a name or a description")
}
if name != nil {
n, err := cleanName(*name)
if err != nil {
return Playlist{}, err
}
name = &n
}
if description != nil {
d, err := cleanDescription(*description)
if err != nil {
return Playlist{}, err
}
description = &d
}
return s.store.Update(ctx, userID, id, name, description, time.Now())
}
// Delete removes a playlist and its items; the tracks stay.
func (s *Service) Delete(ctx context.Context, userID, id int64) error {
if id <= 0 {
return ErrNotFound
}
return s.store.Delete(ctx, userID, id)
}
// ItemsListing is a page of the items of a playlist.
type ItemsListing struct {
Items []Item
Total int
Limit int
Offset int
}
// Items returns a page of the playlist, in order.
func (s *Service) Items(ctx context.Context, userID, id int64, p Page) (ItemsListing, error) {
if id <= 0 {
return ItemsListing{}, ErrNotFound
}
p, err := cleanPage(p)
if err != nil {
return ItemsListing{}, err
}
items, total, err := s.store.Items(ctx, userID, id, p.Limit, p.Offset)
if err != nil {
return ItemsListing{}, err
}
return ItemsListing{Items: items, Total: total, Limit: p.Limit, Offset: p.Offset}, nil
}
// AddTracks puts tracks in a playlist, at the end or at position, in the order given.
func (s *Service) AddTracks(ctx context.Context, userID, id int64, trackIDs []int64, position *int) (Playlist, error) {
if id <= 0 {
return Playlist{}, ErrNotFound
}
if len(trackIDs) == 0 || len(trackIDs) > MaxAddAtOnce {
return Playlist{}, invalid("give 1 to %d track ids", MaxAddAtOnce)
}
for _, t := range trackIDs {
if t <= 0 {
return Playlist{}, invalid("a track id must be positive")
}
}
if position != nil && *position < 0 {
return Playlist{}, invalid("the position cannot be negative")
}
return s.store.AddTracks(ctx, userID, id, trackIDs, position, time.Now())
}
// RemoveItem takes an item out of a playlist.
func (s *Service) RemoveItem(ctx context.Context, userID, id, itemID int64) error {
if id <= 0 {
return ErrNotFound
}
if itemID <= 0 {
return ErrItemNotFound
}
return s.store.RemoveItem(ctx, userID, id, itemID, time.Now())
}
// MoveItem puts an item at another place of its playlist.
func (s *Service) MoveItem(ctx context.Context, userID, id, itemID int64, position int) error {
if id <= 0 {
return ErrNotFound
}
if itemID <= 0 {
return ErrItemNotFound
}
if position < 0 {
return invalid("the position cannot be negative")
}
return s.store.MoveItem(ctx, userID, id, itemID, position, time.Now())
}