Files
AudioManager/src/main/kotlin/win/taptap/musicmanager/api/ApiModels.kt
T
TapTap 44b75c4d4d
CI / chart (push) Successful in 3s
CI / test (push) Successful in 2m20s
CI / chart-push (push) Successful in 6s
CI / image (push) Successful in 3m39s
feat: accept, store and expose client diagnostics
- V11 client_logs table with per-user storage and retention/pruning
- POST/GET/DELETE /logs with batch validation, rate limit and admin access
- redact bearer tokens, Authorization headers and query/JSON secrets twice
- add X-Request-Id to responses and include it in the server log pattern
- report client error entries immediately in the server log
- scripts/logs.sh for source-side retrieval and clearing
- chart knobs CLIENT_LOG_RETENTION_DAYS and CLIENT_LOG_MAX_ROWS_PER_USER
2026-11-20 13:43:05 +00:00

372 lines
9.0 KiB
Kotlin

package win.taptap.musicmanager.api
import kotlinx.serialization.Serializable
import win.taptap.musicmanager.db.MoodRecord
import win.taptap.musicmanager.db.MoodSongRecord
import win.taptap.musicmanager.db.RecommendationRecord
import win.taptap.musicmanager.db.SongRecord
@Serializable
data class ApiErrorBody(val error: ApiError)
@Serializable
data class ApiError(val code: String, val message: String)
@Serializable
data class LoginRequest(
val username: String,
val password: String,
val deviceName: String = "Unknown device",
val platform: String = "unknown",
)
@Serializable
data class UserDto(
val name: String,
val admin: Boolean,
)
@Serializable
data class LoginResponse(
val token: String,
val expiresAt: String,
val user: UserDto,
)
@Serializable
data class DeviceDto(
val id: String,
val deviceName: String,
val platform: String,
val createdAt: String,
val lastUsedAt: String,
val expiresAt: String,
val current: Boolean,
)
@Serializable
data class ClientLogEntryDto(
/** Device clock in epoch milliseconds; informational, the server clamps it. */
val timestamp: Long = 0,
val level: String,
val tag: String,
val message: String,
val detail: String? = null,
val sessionId: String? = null,
)
@Serializable
data class ClientLogBatchDto(
val deviceId: String = "unknown",
val platform: String = "unknown",
val appVersion: String = "unknown",
val entries: List<ClientLogEntryDto> = emptyList(),
)
@Serializable
data class ClientLogDto(
val id: Long,
val deviceId: String,
val platform: String,
val appVersion: String,
val sessionId: String? = null,
val level: String,
val tag: String,
val message: String,
val detail: String? = null,
val createdAt: String,
val receivedAt: String,
)
@Serializable
data class ClientLogsDto(val logs: List<ClientLogDto>)
@Serializable
data class ClientLogsAcceptedDto(val accepted: Int)
@Serializable
data class ClientLogsDeletedDto(val deleted: Int)
@Serializable
data class ServerInfoDto(
val defaultSource: String,
/** 0 = 128 kbps MP3, 1 = 320 kbps MP3 for Deezer downloads. */
val deezerQuality: Int,
val loudnessEnabled: Boolean,
val loudnessTargetLufs: Double,
/** How long the server keeps uploaded client diagnostics. */
val clientLogRetentionDays: Int,
)
@Serializable
data class SongDto(
val id: String,
val source: String,
val externalId: String,
val title: String,
val artist: String,
val album: String? = null,
val duration: Int,
val bitRate: Int,
val size: Long,
val suffix: String,
val thumbnail: String? = null,
/** Measured integrated loudness; null when the server has not analyzed it yet. */
val loudnessLufs: Double? = null,
/** Gain in dB the client applies to reach the server's target loudness. */
val gainDb: Double? = null,
)
fun SongRecord.toDto(): SongDto = SongDto(
id = id,
source = source,
externalId = externalId,
title = title,
artist = artist,
album = album,
duration = duration,
bitRate = bitRate,
size = size,
suffix = suffix,
thumbnail = thumbnail,
loudnessLufs = loudnessLufs,
gainDb = gainDb,
)
@Serializable
data class MoodSongDto(
val song: SongDto,
val origin: String,
val addedAt: String,
)
fun MoodSongRecord.toDto(song: SongRecord): MoodSongDto =
MoodSongDto(song = song.toDto(), origin = origin, addedAt = addedAt)
@Serializable
data class MoodDto(
val id: String,
val name: String,
val description: String? = null,
val query: String? = null,
val genres: List<String> = emptyList(),
val source: String,
val collectionPercent: Int,
val recommendationPercent: Int,
val recommendationCount: Int,
val refreshHours: Int,
val lastDiscoveryAt: String? = null,
val createdAt: String,
val changedAt: String,
val lastError: String? = null,
val songCount: Int,
val recommendationReady: Int,
val recommendationDownloading: Int,
val recommendationFailed: Int,
)
fun MoodRecord.toDto(): MoodDto = MoodDto(
id = id,
name = name,
description = description,
query = query,
genres = genres,
source = source,
collectionPercent = collectionPercent,
recommendationPercent = 100 - collectionPercent,
recommendationCount = recommendationCount,
refreshHours = refreshHours,
lastDiscoveryAt = lastDiscoveryAt,
createdAt = createdAt,
changedAt = changedAt,
lastError = lastError,
songCount = songCount,
recommendationReady = recommendationReady,
recommendationDownloading = recommendationDownloading,
recommendationFailed = recommendationFailed,
)
@Serializable
data class MoodDetailDto(
val mood: MoodDto,
val songs: List<MoodSongDto> = emptyList(),
val recommendations: List<RecommendationDto> = emptyList(),
/** In-flight and recent downloads, so the client can show a per-track status. */
val downloads: List<DownloadStatusDto> = emptyList(),
)
@Serializable
data class DownloadStatusDto(
val source: String,
val externalId: String,
val state: String,
val attempts: Int = 0,
val error: String? = null,
val songId: String? = null,
)
@Serializable
data class RecommendationDto(
val source: String,
val externalId: String,
val title: String,
val artist: String,
val album: String? = null,
val duration: Int? = null,
val thumbnail: String? = null,
val state: String,
val song: SongDto? = null,
val download: DownloadDto? = null,
val error: String? = null,
val firstSeen: String,
val lastSeen: String,
)
fun RecommendationRecord.toDto(
song: SongRecord? = null,
download: DownloadDto? = null,
): RecommendationDto = RecommendationDto(
source = source,
externalId = externalId,
title = title,
artist = artist,
album = album,
duration = duration,
thumbnail = thumbnail,
state = state,
song = song?.toDto(),
download = download,
error = error,
firstSeen = firstSeen,
lastSeen = lastSeen,
)
@Serializable
data class DownloadDto(
val state: String,
val attempts: Int,
val error: String? = null,
val updatedAt: String,
)
@Serializable
data class SearchResultDto(
val source: String,
val externalId: String,
val title: String,
val artist: String,
val album: String? = null,
val duration: Int? = null,
val thumbnail: String? = null,
val songId: String? = null,
val downloaded: Boolean = false,
val inMood: Boolean = false,
)
@Serializable
data class SearchResponse(val results: List<SearchResultDto> = emptyList())
@Serializable
data class CreateMoodRequest(
val name: String,
val description: String? = null,
val query: String? = null,
val genres: List<String> = emptyList(),
val source: String? = null,
val collectionPercent: Int = 50,
val recommendationCount: Int = 10,
val refreshHours: Int = 24,
)
@Serializable
data class UpdateMoodRequest(
val name: String? = null,
val description: String? = null,
val clearDescription: Boolean = false,
val query: String? = null,
val clearQuery: Boolean = false,
val genres: List<String>? = null,
val source: String? = null,
val collectionPercent: Int? = null,
val recommendationCount: Int? = null,
val refreshHours: Int? = null,
)
/**
* Adding music accepts one of:
* - `songId`: an already downloaded song, attached instantly;
* - `videoId`: a YouTube id from search, downloaded if necessary;
* - `url`: a pasted watch URL resolved by yt-dlp.
*/
@Serializable
data class AddSongRequest(
val songId: String? = null,
val source: String? = null,
val externalId: String? = null,
val url: String? = null,
)
@Serializable
data class AddSongResponse(
val detail: MoodDetailDto,
val added: Boolean,
val downloading: Boolean = false,
)
@Serializable
data class RecommendationDecisionDto(
val detail: MoodDetailDto,
val recommendation: RecommendationDto,
)
@Serializable
data class AddToMoodRequest(val songId: String, val moodId: String? = null)
@Serializable
data class AddToMoodResponse(
val mood: MoodDto,
val added: Boolean,
)
@Serializable
data class TracksResponse(val songs: List<SongDto>)
@Serializable
data class StartSessionRequest(val limit: Int? = null)
@Serializable
data class NextTracksRequest(
val limit: Int? = null,
val excludeSongIds: List<String> = emptyList(),
)
@Serializable
data class SessionDto(
val id: String,
val moodId: String,
val moodName: String,
val startedAt: String,
val closedAt: String? = null,
val queue: List<SongDto> = emptyList(),
)
@Serializable
data class PlaybackEvent(
val songId: String,
val type: String,
val positionSeconds: Int? = null,
)
@Serializable
data class PlaybackEventsRequest(val events: List<PlaybackEvent>)
@Serializable
data class PlaybackEventsResponse(val accepted: Int)
@Serializable
data class ScanStatusDto(
val scanning: Boolean,
val count: Long,
val error: String? = null,
)