feat: V2__add_retry_count.sql (retry_count для jobs)

⚠️ ПОБАЙТОВО одинаковый с worker (общая БД)

README.md

@@ -1,3 +1,210 @@
-# media-mirror-api
+# media-mirror — API координатора зеркал
 
-Media mirror: конвертация в зеркала для очков
+Сервис конвертации видео в «зеркала» для AR-очков: одно видео (480p, H.264, без звука) + N аудиодорожек (Vorbis/ogg) отдельными файлами. Воркеры на GPU-машинах молотят очередь из Postgres, готовые файлы лежат в S3 (SeaweedFS).
+
+## Базовый URL
+
+| Окружение | URL |
+|-----------|-----|
+| Прод (из интернета) | `https://mirror.binom.pw` |
+| Прод (внутри сети) | `http://mirror-api-media-mirror-api:8080` |
+
+## Авторизация
+
+Все эндпоинты `/api/**` требуют заголовок:
+
+```
+X-API-Key: <ключ>
+```
+
+Без ключа или с неверным — `401`. `/actuator/**` открыт (health-пробы).
+
+## Модель задачи (Job)
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `id` | uuid | ID задачи |
+| `itemId` | string | ID элемента из Jellyfin |
+| `status` | string | `new` → `processing` → `done` / `failed` / `cancelled` |
+| `progress` | int | 0..100 |
+| `videoKey` | string | S3-ключ видео (после done) |
+| `audioKeys` | array | список аудиодорожек (после done) |
+
+## Эндпоинты
+
+### 1. Создать задачу на конвертацию
+
+```
+POST /api/mirror
+```
+
+**Запрос:**
+```json
+{
+  "itemId": "d57a20a9909921f0bd133c3bbae6f9db",
+  "sourceUrl": "",        // опционально; пусто = воркер сам построит из itemId
+  "sourceType": "jellyfin" // по умолчанию jellyfin
+}
+```
+
+**Ответы:**
+- `201 Created` — задача создана
+- `200 OK` — задача с таким itemId уже существует (не дублируется), возвращается существующая
+
+```json
+{ "id": "4a063de2-f5e9-40b7-b395-e9c17dd23301", "status": "new" }
+```
+
+- `400` — itemId пустой / битый JSON
+- `401` — нет/неверный X-API-Key
+
+### 2. Статус задачи по ID
+
+```
+GET /api/mirror/{id}
+```
+
+```json
+{
+  "id": "4a063de2-f5e9-40b7-b395-e9c17dd23301",
+  "itemId": "d57a20a9909921f0bd133c3bbae6f9db",
+  "status": "processing",
+  "progress": 45
+}
+```
+
+`404` — задачи нет.
+
+### 3. Статус + файлы зеркала по itemId (главный для клиента!)
+
+```
+GET /api/mirror/by-item/{itemId}
+```
+
+**Ответ, если готово:**
+```json
+{
+  "itemId": "d57a20a9909921f0bd133c3bbae6f9db",
+  "status": "done",
+  "files": {
+    "video": {
+      "key": "mirror/d57a20a9909921f0bd133c3bbae6f9db/video.mkv",
+      "url": "https://s3.binom.pw/media/mirror/d57a20a9909921f0bd133c3bbae6f9db/video.mkv"
+    },
+    "audios": [
+      {
+        "index": 0,
+        "key": "mirror/d57a20a9909921f0bd133c3bbae6f9db/audio-0.ogg",
+        "title": "Dub [Reanimedia]",
+        "language": "rus",
+        "url": "https://s3.binom.pw/media/mirror/d57a20a9909921f0bd133c3bbae6f9db/audio-0.ogg"
+      },
+      {
+        "index": 1,
+        "key": "mirror/d57a20a9909921f0bd133c3bbae6f9db/audio-1.ogg",
+        "title": "Original",
+        "language": "eng",
+        "url": "https://s3.binom.pw/media/mirror/d57a20a9909921f0bd133c3bbae6f9db/audio-1.ogg"
+      }
+    ]
+  }
+}
+```
+
+**Ответ, если ещё не готово:**
+```json
+{ "itemId": "...", "status": "processing", "files": null }
+```
+
+**Ответ, если задачи нет вообще:**
+`404` — клиент понимает: «ещё не конвертировано, можно заказать».
+
+### 4. Список задач (фильтр по статусу)
+
+```
+GET /api/mirror?status=done&limit=50
+```
+
+`status` — опционально (`new`/`processing`/`done`/`failed`/`cancelled`), `limit` — опционально (дефолт 50).
+
+**Ответ:**
+```json
+[
+  { "id": "...", "itemId": "...", "status": "done", "progress": 100 }
+]
+```
+
+### 5. Удалить / отменить задачу
+
+```
+DELETE /api/mirror/{id}
+```
+
+- задача `new`/`processing` → `cancelled` (воркер пропустит)
+- задача `done` → файлы удаляются из S3 + запись удаляется
+- повторный DELETE → `404`
+
+### 6. Сканировать библиотеку Jellyfin (догонялка)
+
+```
+POST /api/mirror/scan
+```
+
+Обходит Jellyfin (Movies + Episodes), создаёт задачи на **только недостающее**:
+- есть активная задача (`new`/`processing`/`done`) → **skip**
+- нет задачи / последняя `failed`/`cancelled` → **create**
+
+Идемпотентен — можно дёргать сколько угодно, дублей не будет. Используется, когда webhook'и Jellyfin потерялись.
+
+**Ответ:**
+```json
+{ "found": 1387, "created": 12, "skipped": 1375 }
+```
+
+`502` — Jellyfin недоступен.
+
+## Формат зеркала (что получит клиент)
+
+| Файл | Кодек | Контейнер | Разрешение | Описание |
+|------|-------|-----------|------------|----------|
+| `video.mkv` | H.264 (NVENC) | mkv | 480p (высота ≤480) | **без звука**, без субтитров/метаданных |
+| `audio-N.ogg` | Vorbis | ogg | 2ch | **каждая** дорожка исходника отдельным файлом |
+
+Сколько аудио — столько дорожек было в исходнике (все без исключения). Мета каждой дорожки (`title`, `language`) — в ответе `by-item`, берётся из ffprobe исходника.
+
+## Скачивание файлов (S3)
+
+Клиент качает файлы **напрямую из S3** (SeaweedFS), не через координатор:
+
+- S3 endpoint: `https://s3.binom.pw`
+- bucket: `media`
+- путь: `mirror/{itemId}/video.mkv`, `mirror/{itemId}/audio-{index}.ogg`
+
+**Креды клиента (зашиты в приложение):**
+```
+accessKey: MirrorClient01QwertyKey
+secretKey: MirrorClient01SecretKeyValueForGlassesOnly
+```
+
+Права клиентского ключа: **только чтение** `media/mirror/*` — писать/удалять/листать нельзя. Подписывать запросы по S3 SigV4 (AWS SDK, region `us-east-1`). Поддержка Range-запросов есть (видео можно качать/играть по кускам).
+
+## Пример полного цикла клиента
+
+```text
+1. GET https://mirror.binom.pw/api/mirror/by-item/{itemId}   [X-API-Key]
+   → 404 → 2а
+   → files → 4
+2а. POST /api/mirror  {"itemId": "..."}                      [X-API-Key]
+2б. GET by-item, пока status != done (поллинг раз в 5-10с)
+3. status == done → берём files.video.url + files.audios[].url
+4. Качаем по url с mirror-client кредами (SigV4) → играем
+   (видео — на очки, выбранную аудио-дорожку — на телефон)
+```
+
+## Health
+
+```
+GET /actuator/health
+```
+
+Открыт без ключа. `{"status": "UP"}` — сервис жив.

build.gradle.kts

@@ -33,6 +33,7 @@ dependencies {
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
     implementation("org.springframework.boot:spring-boot-starter-jdbc")
     implementation("org.springframework.boot:spring-boot-starter-flyway")
+    implementation("org.springframework.boot:spring-boot-starter-actuator")
     implementation("org.springframework.boot:spring-boot-starter-validation")
     implementation("org.postgresql:postgresql")
     implementation("org.flywaydb:flyway-database-postgresql")

helm/templates/configmap.yaml

@@ -9,8 +9,10 @@ data:
       forward-headers-strategy: framework
 
     app:
+      api-key: ${API_KEY}
       jellyfin:
         url: {{ $.Values.app.jellyfin.url | quote }}
+        api-key: ${JELLYFIN_API_KEY}
       s3:
         url: {{ $.Values.app.s3.url | quote }}
         access-key: ${S3_ACCESS_KEY}

helm/templates/deployment.yaml

@@ -69,16 +69,26 @@ spec:
                   key: dbPassword
             - name: DB_URL
               value: "jdbc:postgresql://{{ $.Values.db.host }}:{{ $.Values.db.port }}/{{ $.Values.db.name }}"
+            - name: API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ $.Release.Name }}-{{ $.Chart.Name }}-secret
+                  key: apiKey
+            - name: JELLYFIN_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ $.Release.Name }}-{{ $.Chart.Name }}-secret
+                  key: jellyfinApiKey
             - name: S3_ACCESS_KEY
               valueFrom:
                 secretKeyRef:
                   name: {{ $.Release.Name }}-{{ $.Chart.Name }}-secret
-                  key: app.s3.accessKey
+                  key: accessKey
             - name: S3_SECRET_KEY
               valueFrom:
                 secretKeyRef:
                   name: {{ $.Release.Name }}-{{ $.Chart.Name }}-secret
-                  key: app.s3.secretKey
+                  key: secretKey
           volumeMounts:
             - mountPath: '/opt/app/config'
               name: application-properties-volume

helm/templates/ingress.yaml

@@ -0,0 +1,17 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: "{{ $.Release.Name }}-{{ $.Chart.Name }}"
+  annotations: {}
+spec:
+  rules:
+    - host: {{.Values.ingress.host }}
+      http:
+        paths:
+          - backend:
+              service:
+                name: "{{ $.Release.Name }}-{{ $.Chart.Name }}"
+                port:
+                  number: {{ .Values.port }}
+            path: /
+            pathType: Prefix

helm/templates/secret.yaml

@@ -8,3 +8,5 @@ data:
   dbPassword: {{ (required "DB password не установлен" $.Values.db.password) | b64enc | quote }}
   accessKey: {{ (required "Accesskey не установлен" $.Values.app.s3.accessKey) | b64enc | quote }}
   secretKey: {{ (required "Secretkey не установлен" $.Values.app.s3.secretKey) | b64enc | quote }}
+  apiKey: {{ (required "ApiKey не установлен" $.Values.app.apiKey) | b64enc | quote }}
+  jellyfinApiKey: {{ (required "Jellyfin ApiKey не установлен" $.Values.app.jellyfin.apiKey) | b64enc | quote }}

helm/values.yaml

@@ -23,8 +23,10 @@ db:
   maxConnections: 10
 
 app:
+  apiKey: null
   jellyfin:
     url: null
+    apiKey: null
   s3:
     url: null
     accessKey: null
@@ -35,3 +37,5 @@ app:
 
 securityContext:
   privileged: false
+ingress:
+  host: null

src/main/kotlin/pw/binom/mirror/api/config/ApiKeyFilter.kt

@@ -0,0 +1,49 @@
+package pw.binom.mirror.api.config
+
+import jakarta.servlet.FilterChain
+import jakarta.servlet.http.HttpServletRequest
+import jakarta.servlet.http.HttpServletResponse
+import kotlinx.serialization.json.Json
+import org.slf4j.LoggerFactory
+import org.springframework.core.Ordered
+import org.springframework.core.annotation.Order
+import org.springframework.http.HttpStatus
+import org.springframework.http.MediaType
+import org.springframework.stereotype.Component
+import org.springframework.web.filter.OncePerRequestFilter
+import pw.binom.mirror.api.dto.ErrorResponse
+
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE)
+class ApiKeyFilter(
+    private val properties: AppProperties,
+    private val json: Json,
+) : OncePerRequestFilter() {
+
+    private val log = LoggerFactory.getLogger(ApiKeyFilter::class.java)
+
+    init {
+        if (properties.apiKey.isEmpty()) {
+            log.warn("app.api-key is empty, API is unprotected (dev mode)")
+        }
+    }
+
+    override fun doFilterInternal(
+        request: HttpServletRequest,
+        response: HttpServletResponse,
+        filterChain: FilterChain,
+    ) {
+        val apiKey = properties.apiKey
+        if (apiKey.isEmpty()) {
+            filterChain.doFilter(request, response)
+            return
+        }
+        if (request.requestURI.startsWith("/api/") && request.getHeader("X-API-Key") != apiKey) {
+            response.status = HttpStatus.UNAUTHORIZED.value()
+            response.contentType = MediaType.APPLICATION_JSON_VALUE
+            response.writer.write(json.encodeToString(ErrorResponse("Invalid or missing X-API-Key")))
+            return
+        }
+        filterChain.doFilter(request, response)
+    }
+}

src/main/kotlin/pw/binom/mirror/api/config/AppProperties.kt

@@ -9,6 +9,8 @@ data class AppProperties(
     val jellyfin: Jellyfin,
     @param:DefaultValue
     val s3: S3,
+    @param:DefaultValue("")
+    val apiKey: String,
 ) {
     data class Jellyfin(
         @param:DefaultValue("https://jellyfin.binom.pw/")

src/main/kotlin/pw/binom/mirror/api/dto/CreateMirrorRequest.kt

@@ -7,7 +7,6 @@ import kotlinx.serialization.Serializable
 data class CreateMirrorRequest(
     @field:NotBlank(message = "itemId must not be blank")
     val itemId: String,
-    @field:NotBlank(message = "sourceUrl must not be blank")
-    val sourceUrl: String,
+    val sourceUrl: String = "",
     val sourceType: String = "jellyfin",
 )

src/main/resources/application.yaml

@@ -1,4 +1,5 @@
 app:
+  api-key: ${MIRROR_API_KEY:}
   jellyfin:
     url: https://jellyfin.binom.pw/
     api-key: ${JELLYFIN_API_KEY}

src/main/resources/db/migration/V2__add_retry_count.sql

@@ -0,0 +1 @@
+ALTER TABLE media_mirror.jobs ADD COLUMN IF NOT EXISTS retry_count int NOT NULL DEFAULT 0;

src/test/kotlin/pw/binom/mirror/api/ApiKeyFilterTest.kt

@@ -0,0 +1,39 @@
+package pw.binom.mirror.api
+
+import org.junit.jupiter.api.Test
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.boot.test.context.SpringBootTest
+import org.springframework.test.web.servlet.MockMvc
+import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get
+import org.springframework.test.web.servlet.result.MockMvcResultMatchers.status
+
+@SpringBootTest(properties = ["app.api-key=test-secret"])
+class ApiKeyFilterTest : AbstractIntegrationTest() {
+
+    @Autowired
+    lateinit var mockMvc: MockMvc
+
+    @Test
+    fun `missing X-API-Key returns 401`() {
+        mockMvc.perform(get("/api/mirror"))
+            .andExpect(status().isUnauthorized)
+    }
+
+    @Test
+    fun `invalid X-API-Key returns 401`() {
+        mockMvc.perform(get("/api/mirror").header("X-API-Key", "wrong-key"))
+            .andExpect(status().isUnauthorized)
+    }
+
+    @Test
+    fun `valid X-API-Key is accepted`() {
+        mockMvc.perform(get("/api/mirror").header("X-API-Key", "test-secret"))
+            .andExpect(status().isOk)
+    }
+
+    @Test
+    fun `actuator health is not protected`() {
+        mockMvc.perform(get("/actuator/health"))
+            .andExpect(status().isOk)
+    }
+}

src/test/kotlin/pw/binom/mirror/api/DevModeFilterTest.kt

@@ -0,0 +1,19 @@
+package pw.binom.mirror.api
+
+import org.junit.jupiter.api.Test
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.test.web.servlet.MockMvc
+import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get
+import org.springframework.test.web.servlet.result.MockMvcResultMatchers.status
+
+class DevModeFilterTest : AbstractIntegrationTest() {
+
+    @Autowired
+    lateinit var mockMvc: MockMvc
+
+    @Test
+    fun `empty api key allows requests without X-API-Key`() {
+        mockMvc.perform(get("/api/mirror"))
+            .andExpect(status().isOk)
+    }
+}

src/test/kotlin/pw/binom/mirror/api/controller/MirrorControllerTest.kt

@@ -83,6 +83,21 @@ class MirrorControllerTest : AbstractIntegrationTest() {
         assertEquals(1, count)
     }
 
+    @Test
+    fun `POST mirror without sourceUrl creates a job`() {
+        mockMvc.perform(
+            post("/api/mirror")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("""{"itemId":"no-url-id"}"""),
+        ).andExpect(status().isCreated)
+
+        val response = json.decodeFromString<ByItemResponse>(
+            bodyOf(mockMvc.perform(get("/api/mirror/by-item/no-url-id")).andExpect(status().isOk).andReturn()),
+        )
+        assertEquals("no-url-id", response.itemId)
+        assertEquals("new", response.status)
+    }
+
     @Test
     fun `POST mirror returns 400 on blank itemId`() {
         postCreate("", "https://source.example/stream")