feat(api): upload queue with quota, tus intake, processing and import (M5.5)
ci / api / api (push) Successful in 46s
ci / contract / contract (сгенерированный код совпадает с openapi.yaml) (push) Successful in 1m3s
ci / mobile / mobile (Metro-бандл Android) (push) Successful in 1m22s
ci / ts / ts (packages + web) (push) Successful in 1m38s

- Migration 00008: upload_batches, upload_files, upload_quota.
- Quota reserved under a row lock when a batch is created; every status
  change goes through one transition that frees space in the same
  transaction. SHA-256 duplicates are rejected before any upload.
- tus 1.0.0 core (HEAD/PATCH) for the author only; offset is the real
  staging file size, data beyond the declared size is refused (ADR-015).
- Processing worker: ffprobe checks, SHA-256 verification, exact and
  Chromaprint duplicates against library and queue, metadata from tags
  or the dropped folder path, possible_duplicate on metadata match, and
  the target path from write_template reusing existing folder spelling.
- Import worker: edited tags written with ffmpeg stream copy, file
  written by storage-agent, point scan of the new file, imported status;
  idempotent and resumed after restart. Stale uploads expire after 24 h,
  orphan staging files are removed at startup.
- API: quota, precheck, batches, my uploads, withdraw, admin list,
  metadata edit, bulk review, retry and queue settings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mrleo1nidandClaude Opus 5.5 committed 2026-10-20 17:23:05 +03:00
1 parent f66be2ba0a
commit ca106e8eb1
21 files changed
+5552 -198

No files matched your search

+650
View File
@@ -305,6 +305,199 @@ export interface paths {
patch?: never;
trace?: never;
};
"/api/v1/uploads/quota": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/** Квота очереди на добавление (moderator, admin) */
get: operations["getUploadQuota"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/uploads/precheck": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Предпроверка дублей до загрузки (moderator, admin)
* @description Ничего не резервирует. SHA-256 и теги клиент считает сам (docs/uploads.md#4).
*/
post: operations["precheckUploads"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/uploads": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Создать пачку и зарезервировать место (moderator, admin)
* @description Для принятых файлов — `tus_url` (tus 1.0.0, только HEAD / PATCH, куски до 64 МБ). Не поместившиеся —
* `uploads.queue_full` / `uploads.user_quota_full`, дубли — `uploads.duplicate`, без места в квоте.
*/
post: operations["createUploadBatch"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/uploads/mine": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/** Мои предложения (moderator, admin) */
get: operations["listMyUploads"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/uploads/files/{id}": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["EntityId"];
};
cookie?: never;
};
get?: never;
put?: never;
post?: never;
/**
* Отозвать своё предложение до решения
* @description HEAD / PATCH по этому же адресу — приём файла по tus (вне контракта OpenAPI).
*/
delete: operations["withdrawUpload"];
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/admin/uploads": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/** Очередь на добавление (admin) */
get: operations["listUploads"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/admin/uploads/files/{id}": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["EntityId"];
};
cookie?: never;
};
get?: never;
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
/**
* Править метаданные и хранилище (admin)
* @description Путь в хранилище пересчитывается; правленые теги записываются в файл при импорте.
*/
patch: operations["updateUpload"];
trace?: never;
};
"/api/v1/admin/uploads/files/{id}/retry": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["EntityId"];
};
cookie?: never;
};
get?: never;
put?: never;
/** Повторить импорт после import_failed (admin) */
post: operations["retryUploadImport"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/admin/uploads/review": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/** Одобрить / отклонить файлы (admin) */
post: operations["reviewUploads"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/api/v1/admin/settings/uploads": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/** Настройки очереди (admin) */
get: operations["getUploadSettings"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
/**
* Изменить настройки очереди (admin)
* @description Уменьшение лимита ниже занятого ничего не удаляет — новые загрузки ждут, пока очередь освободится.
*/
patch: operations["updateUploadSettings"];
trace?: never;
};
"/api/v1/admin/audit": {
parameters: {
query?: never;
@@ -969,6 +1162,191 @@ export interface paths {
export type webhooks = Record<string, never>;
export interface components {
schemas: {
UserRef: {
/** Format: uuid */
id: string;
username: string;
};
/** @enum {string} */
UploadStatus: "uploading" | "processing" | "pending_review" | "approved" | "importing" | "imported" | "import_failed" | "duplicate" | "invalid" | "rejected" | "withdrawn" | "expired";
UploadQuota: {
/** Format: int64 */
limit_bytes: number;
/** Format: int64 */
used_bytes: number;
/** Format: int64 */
per_user_limit_bytes: number | null;
/** Format: int64 */
user_used_bytes: number;
/** Format: int64 */
max_file_bytes: number;
};
UploadPrecheckRequest: {
files: {
client_id: string;
/** Format: int64 */
size: number;
sha256: string;
artist?: string;
title?: string;
duration_ms?: number;
}[];
};
UploadPrecheckResult: {
files: {
client_id: string;
/** @enum {string} */
result: "accepted" | "duplicate" | "too_large";
/**
* Format: uuid
* @description С каким треком совпал (дубль или похожие метаданные)
*/
track_id: string | null;
/** @description Совпали только метаданные — файл примут, админ решит */
possible_duplicate: boolean;
}[];
};
UploadBatchRequest: {
comment?: string;
files: {
client_id: string;
name: string;
/** @description Относительный путь в перетащенной папке */
rel_path?: string;
/** Format: int64 */
size: number;
sha256: string;
}[];
};
UploadBatchCreated: {
/** Format: uuid */
batch_id: string;
files: {
client_id: string;
/** Format: uuid */
upload_file_id: string | null;
tus_url: string | null;
/** @description Код отказа — uploads.queue_full, uploads.user_quota_full, uploads.too_large, uploads.duplicate, uploads.unsupported_format */
rejected: string | null;
/** Format: uuid */
track_id: string | null;
}[];
};
UploadMeta: {
artist: string;
albumartist: string;
album: string;
title: string;
genre: string;
year: number | null;
track: number | null;
disc: number | null;
};
UploadFile: {
/** Format: uuid */
id: string;
/** Format: uuid */
batch_id: string;
batch_comment: string | null;
author: components["schemas"]["UserRef"];
status: components["schemas"]["UploadStatus"];
original_name: string;
client_rel_path: string | null;
/** Format: int64 */
size_bytes: number;
/** Format: int64 */
received_bytes: number;
format: string | null;
codec: string | null;
bitrate: number | null;
sample_rate: number | null;
bit_depth: number | null;
duration_ms: number | null;
tags: {
[key: string]: string;
};
metadata: components["schemas"]["UploadMeta"] | null;
metadata_edited: boolean;
/**
* Format: uuid
* @description Найден в каталоге — файл добавится к существующему исполнителю
*/
matched_artist_id: string | null;
/**
* Format: uuid
* @description Найден в каталоге — «будет добавлено к существующему альбому»
*/
matched_album_id: string | null;
/** Format: uuid */
duplicate_of_track_id: string | null;
/** @enum {string|null} */
duplicate_level: "sha256" | "metadata" | "fingerprint" | null;
possible_duplicate: boolean;
/** Format: uuid */
target_source_id: string | null;
/** @description Путь в хранилище по write_template (null — не построился, причина в status_reason) */
target_rel_path: string | null;
status_reason: string | null;
/** Format: date-time */
reviewed_at: string | null;
/** Format: date-time */
created_at: string;
/** Format: date-time */
updated_at: string;
/** @description Только автору и пока файл в статусе uploading */
tus_url: string | null;
};
UploadFilePage: {
items: components["schemas"]["UploadFile"][];
next_cursor: string | null;
};
UploadPatch: {
metadata?: components["schemas"]["UploadMeta"];
/** Format: uuid */
target_source_id?: string;
};
UploadReviewRequest: {
file_ids: string[];
/** @enum {string} */
decision: "approve" | "reject";
/** @description Причина отклонения — её видит автор */
reason?: string;
};
UploadReviewResult: {
items: {
/** Format: uuid */
id: string;
ok: boolean;
error: components["schemas"]["Problem"] | null;
}[];
};
UploadSettings: {
/** Format: int64 */
queue_limit_bytes: number;
/** Format: int64 */
per_user_limit_bytes: number | null;
/** Format: int64 */
max_file_bytes: number;
/** Format: uuid */
default_source_id: string | null;
};
/** @description Лимит на пользователя и хранилище по умолчанию передаются всегда (null — выключить / не задано). */
UploadSettingsPatch: {
/** Format: int64 */
queue_limit_bytes?: number;
/**
* Format: int64
* @description null — выключить лимит на пользователя
*/
per_user_limit_bytes: number | null;
/** Format: int64 */
max_file_bytes?: number;
/**
* Format: uuid
* @description null — без хранилища по умолчанию
*/
default_source_id: string | null;
};
HealthStatus: {
/** @enum {string} */
status: "ok";
@@ -1635,6 +2013,8 @@ export interface components {
Limit: number;
/** @description Непрозрачный курсор из `next_cursor` предыдущей страницы */
Cursor: string;
/** @description Статусы через запятую */
UploadStatusFilter: components["schemas"]["UploadStatus"][];
UserId: string;
};
requestBodies: never;
@@ -2064,6 +2444,276 @@ export interface operations {
default: components["responses"]["Problem"];
};
};
getUploadQuota: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Лимиты и занятое место */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadQuota"];
};
};
default: components["responses"]["Problem"];
};
};
precheckUploads: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["UploadPrecheckRequest"];
};
};
responses: {
/** @description Итог по каждому файлу */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadPrecheckResult"];
};
};
default: components["responses"]["Problem"];
};
};
createUploadBatch: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["UploadBatchRequest"];
};
};
responses: {
/** @description Пачка создана */
201: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadBatchCreated"];
};
};
default: components["responses"]["Problem"];
};
};
listMyUploads: {
parameters: {
query?: {
/** @description Статусы через запятую */
status?: components["parameters"]["UploadStatusFilter"];
limit?: components["parameters"]["Limit"];
/** @description Непрозрачный курсор из `next_cursor` предыдущей страницы */
cursor?: components["parameters"]["Cursor"];
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Страница предложений */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadFilePage"];
};
};
default: components["responses"]["Problem"];
};
};
withdrawUpload: {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["EntityId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Отозвано, место освобождено */
204: {
headers: {
[name: string]: unknown;
};
content?: never;
};
default: components["responses"]["Problem"];
};
};
listUploads: {
parameters: {
query?: {
/** @description Статусы через запятую */
status?: components["parameters"]["UploadStatusFilter"];
author?: string;
batch?: string;
possible_duplicate?: boolean;
limit?: components["parameters"]["Limit"];
/** @description Непрозрачный курсор из `next_cursor` предыдущей страницы */
cursor?: components["parameters"]["Cursor"];
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Страница очереди */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadFilePage"];
};
};
default: components["responses"]["Problem"];
};
};
updateUpload: {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["EntityId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["UploadPatch"];
};
};
responses: {
/** @description Файл */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadFile"];
};
};
default: components["responses"]["Problem"];
};
};
retryUploadImport: {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["EntityId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Файл снова одобрен */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadFile"];
};
};
default: components["responses"]["Problem"];
};
};
reviewUploads: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["UploadReviewRequest"];
};
};
responses: {
/** @description Итог по каждому файлу */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadReviewResult"];
};
};
default: components["responses"]["Problem"];
};
};
getUploadSettings: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Настройки */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadSettings"];
};
};
default: components["responses"]["Problem"];
};
};
updateUploadSettings: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["UploadSettingsPatch"];
};
};
responses: {
/** @description Настройки */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["UploadSettings"];
};
};
default: components["responses"]["Problem"];
};
};
listAudit: {
parameters: {
query?: {
+17
View File
@@ -76,5 +76,22 @@
},
"app": {
"update_unavailable": "Update is unavailable"
},
"uploads": {
"queue_full": "The upload queue is full",
"user_quota_full": "Your upload queue limit is exceeded",
"too_large": "The file is larger than allowed",
"duplicate": "This track is already in the library or in the queue",
"invalid_audio": "The file does not look like audio (one audio stream, 5 s to 3 h)",
"unsupported_format": "Unsupported format: FLAC, MP3, M4A, OGG, Opus, WAV, AIFF and WavPack are accepted",
"not_found": "Upload not found",
"wrong_status": "The file is already in another status; refresh the page",
"no_target": "No storage accepts uploads (or several do and none is the default)",
"no_template": "The storage has no path template",
"missing_field": "Not enough metadata to build the storage path",
"offset_mismatch": "The upload got out of sync; try again",
"size_mismatch": "The file size does not match the declared one",
"hash_mismatch": "The file was corrupted in transit (SHA-256 mismatch)",
"import_failed": "Could not write the file to the storage"
}
}
+17
View File
@@ -76,5 +76,22 @@
},
"app": {
"update_unavailable": "Обновление недоступно"
},
"uploads": {
"queue_full": "В очереди на добавление нет места",
"user_quota_full": "Превышен ваш лимит в очереди на добавление",
"too_large": "Файл больше допустимого размера",
"duplicate": "Такой трек уже есть в библиотеке или в очереди",
"invalid_audio": "Файл не похож на аудио (нужен один аудиопоток длительностью от 5 с до 3 ч)",
"unsupported_format": "Формат не поддерживается: подойдут FLAC, MP3, M4A, OGG, Opus, WAV, AIFF, WavPack",
"not_found": "Загрузка не найдена",
"wrong_status": "Файл уже в другом статусе — обновите страницу",
"no_target": "Нет хранилища, принимающего загрузки (или их несколько и не выбрано по умолчанию)",
"no_template": "У хранилища не задан шаблон пути",
"missing_field": "Не хватает метаданных для пути в хранилище",
"offset_mismatch": "Загрузка рассинхронизировалась — повторите",
"size_mismatch": "Размер файла не совпал с заявленным",
"hash_mismatch": "Файл повредился при загрузке (не совпал SHA-256)",
"import_failed": "Не удалось записать файл в хранилище"
}
}