.github/workflows/build-pr.yml

@@ -14,8 +14,8 @@ on:
       - ".github/ISSUE_TEMPLATE/**"
 
 env:
-  BUN_VERSION: latest
-  NODE_VERSION: 22
+  PNPM_VERSION: 10
+  NODE_VERSION: 20
   PYTHON_VERSION: "3.13"
 
 jobs:
@@ -43,56 +43,45 @@ jobs:
       - name: Run Python tests
         run: uv run pytest app/tests/ -v --tb=short
 
-      - name: Cache bun installation
-        id: cache-bun
-        uses: actions/cache@v4
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
         with:
-          path: ~/.bun/install/cache
-          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
+          version: ${{ env.PNPM_VERSION }}
 
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
           node-version: ${{ env.NODE_VERSION }}
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ env.BUN_VERSION }}
+          cache: pnpm
+          cache-dependency-path: "ui/pnpm-lock.yaml"
 
       - name: Install frontend dependencies
         working-directory: ui
         env:
           NODE_ENV: development
-        run: bun install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       - name: Prepare frontend (nuxt prepare)
         working-directory: ui
         env:
           NODE_ENV: development
-        run: bun nuxt prepare
+        run: pnpm nuxt prepare
 
       - name: Run frontend linting
         working-directory: ui
-        run: bun run lint
+        run: pnpm run lint
 
       - name: Run frontend type checking
         working-directory: ui
-        run: bun run typecheck
-
-      - name: Run frontend tsc
-        working-directory: ui
-        run: bun run lint:tsc
+        run: pnpm run typecheck
 
       - name: Run frontend tests
         working-directory: ui
-        run: bun run test:ci
+        run: pnpm run test:ci
 
       - name: Build frontend
         working-directory: ui
-        run: bun run generate
+        run: pnpm run generate
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3

.github/workflows/main.yml

@@ -28,8 +28,8 @@ env:
   BUILD_ARM64: ${{ vars.BUILD_ARM64 != 'false' && 'true' || 'false' }}
   DOCKERHUB_SLUG: arabcoders/ytptube
   GHCR_SLUG: ghcr.io/arabcoders/ytptube
-  BUN_VERSION: latest
-  NODE_VERSION: 22
+  PNPM_VERSION: 10
+  NODE_VERSION: 20
   PYTHON_VERSION: "3.13"
 
 jobs:
@@ -77,64 +77,53 @@ jobs:
       - name: Run Python tests
         run: uv run pytest app/tests/ -v --tb=short
 
-      - name: Cache bun installation
-        id: cache-bun
-        uses: actions/cache@v4
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
         with:
-          path: ~/.bun/install/cache
-          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
+          version: ${{ env.PNPM_VERSION }}
 
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
           node-version: ${{ env.NODE_VERSION }}
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ env.BUN_VERSION }}
+          cache: pnpm
+          cache-dependency-path: "ui/pnpm-lock.yaml"
 
       - name: Install frontend dependencies
         working-directory: ui
         env:
           NODE_ENV: development
-        run: bun install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       - name: Prepare frontend (nuxt prepare)
         working-directory: ui
         env:
           NODE_ENV: development
-        run: bun nuxt prepare
+        run: pnpm nuxt prepare
 
       - name: Run frontend linting
         working-directory: ui
-        run: bun run lint
+        run: pnpm run lint
 
       - name: Run frontend type checking
         working-directory: ui
-        run: bun run typecheck
-
-      - name: Run frontend tsc
-        working-directory: ui
-        run: bun run lint:tsc
+        run: pnpm run typecheck
 
       - name: Run frontend tests
         working-directory: ui
-        run: bun run test:ci
+        run: pnpm run test:ci
 
       - name: Remove dev dependencies
         working-directory: ui
         env:
           NODE_ENV: production
-        run: bun install --frozen-lockfile --production --ignore-scripts
+        run: pnpm install --frozen-lockfile --prod --ignore-scripts
 
       - name: Build frontend
         working-directory: ui
         env:
           NODE_ENV: production
-        run: bun run generate
+        run: pnpm run generate
 
       - name: Install GitPython
         run: pip install gitpython
@@ -432,53 +421,42 @@ jobs:
           script: |
             const tag = context.ref.replace('refs/tags/', '');
 
-            const { data: releases } = await github.rest.repos.listReleases({
+            const latestRelease = await github.rest.repos.listReleases({
               owner: context.repo.owner,
               repo: context.repo.repo,
             });
 
-            const release = releases.find(r => r.tag_name === tag);
+            const release = latestRelease.data.find(r => r.tag_name === tag);
             if (!release) {
               core.setFailed(`Release with tag ${tag} not found`);
               return;
             }
 
-            const baseTag = releases[1]?.tag_name || '';
-            if (!baseTag) {
-              core.setFailed('Could not determine a base tag (no previous release found)');
-              return;
-            }
-
             const { data: comparison } = await github.rest.repos.compareCommits({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              base: baseTag,
+              base: latestRelease.data[1]?.tag_name || '',
               head: tag,
             });
 
-            const commits = comparison.commits.filter(c => c.parents.length === 1);
+            const commits = comparison.commits.filter(c => 1 === c.parents.length);
 
-            const changelog = commits
-              .map(c => `- ${c.sha.substring(0, 7)} ${c.commit.message.split('\n')[0]}`)
-              .join('\n');
+            const changelog = commits.map(
+              c => `- ${c.sha.substring(0, 7)} ${c.commit.message.split('\n')[0]}`
+            ).join('\n');
 
             if (!changelog) {
               core.setFailed('No commits found for the changelog');
               return;
             }
 
-            const existingBody = (release.body || '').trim();
-
-            const separator = `\n\n---\n\n## Commits since ${baseTag}\n\n`;
-            const newBody = existingBody
-              ? `${existingBody}${separator}${changelog}`
-              : `## Commits since ${baseTag}\n\n${changelog}`;
+            console.log(`Changelog for ${tag}:\n${changelog}`);
 
             await github.rest.repos.updateRelease({
               owner: context.repo.owner,
               repo: context.repo.repo,
               release_id: release.id,
-              body: newBody,
+              body: changelog
             });
 
   dockerhub-sync-readme:

.github/workflows/native-build.yml

@@ -37,9 +37,9 @@ jobs:
       contents: write
 
     env:
-      PYTHON_VERSION: "3.13"
-      BUN_VERSION: latest
-      NODE_VERSION: 22
+      PYTHON_VERSION: 3.11
+      PNPM_VERSION: 10
+      NODE_VERSION: 20
       TAG_NAME: ${{ github.event.inputs.tag || github.ref_name }}
 
     steps:
@@ -60,40 +60,8 @@ jobs:
 
       - name: Replace app.spec with version from workflow branch
         if: ${{ github.event.inputs.useWorkflowSpec == 'true' }}
-        shell: bash
         run: cp temp-spec/app.spec ./app.spec
 
-      - name: Update app/library/version.py
-        shell: bash
-        run: |
-          VERSION="${TAG_NAME}"
-          SHA=$(git rev-parse HEAD)
-          DATE=$(date -u +"%Y%m%d")
-          BRANCH=$(git branch --show-current)
-
-          if [ -z "${BRANCH}" ]; then
-            BRANCH="${TAG_NAME}"
-          fi
-
-          BRANCH=$(echo "${BRANCH}" | sed 's#/#-#g')
-
-          echo "APP_VERSION=${VERSION}" >> "$GITHUB_ENV"
-          echo "APP_SHA=${SHA}" >> "$GITHUB_ENV"
-          echo "APP_DATE=${DATE}" >> "$GITHUB_ENV"
-          echo "APP_BRANCH=${BRANCH}" >> "$GITHUB_ENV"
-
-          sed -i.bak \
-            -e "s/^APP_VERSION = \".*\"/APP_VERSION = \"${VERSION}\"/" \
-            -e "s/^APP_COMMIT_SHA = \".*\"/APP_COMMIT_SHA = \"${SHA}\"/" \
-            -e "s/^APP_BUILD_DATE = \".*\"/APP_BUILD_DATE = \"${DATE}\"/" \
-            -e "s/^APP_BRANCH = \".*\"/APP_BRANCH = \"${BRANCH}\"/" \
-            app/library/version.py
-
-          rm -f app/library/version.py.bak
-
-          echo "Updated version info:"
-          cat app/library/version.py
-
       - name: Cache Python venv
         id: cache-python
         uses: actions/cache@v4
@@ -110,63 +78,37 @@ jobs:
           architecture: "x64"
 
       - name: Install Python dependencies
-        shell: bash
         run: |
           pip install uv
-          if [ ! -d .venv ]; then
-            uv venv --system-site-packages --relocatable
-          fi
+          uv venv --system-site-packages --relocatable
           uv sync --link-mode=copy --active --extra installer
 
-      - name: Cache bun installation
-        id: cache-bun
-        uses: actions/cache@v4
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
         with:
-          path: ~/.bun/install/cache
-          key: ${{ runner.os }}-${{ matrix.arch }}-bun-${{ hashFiles('**/bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ matrix.arch }}-bun-
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ env.BUN_VERSION }}
+          version: ${{ env.PNPM_VERSION }}
 
       - name: Install Node.js
         uses: actions/setup-node@v4
         with:
           node-version: ${{ env.NODE_VERSION }}
+          cache: pnpm
+          cache-dependency-path: "ui/pnpm-lock.yaml"
 
       - name: Build frontend
         working-directory: ui
-        shell: bash
         run: |
-          bun install --production --prefer-offline --frozen-lockfile
-          bun run generate
-
-      - name: Clean build outputs (Unix)
-        if: runner.os != 'Windows'
-        shell: bash
-        run: rm -rf build dist release || true
-
-      - name: Clean build outputs (Windows)
-        if: runner.os == 'Windows'
-        shell: powershell
-        run: |
-          if (Test-Path build)   { Remove-Item -Recurse -Force build }
-          if (Test-Path dist)    { Remove-Item -Recurse -Force dist }
-          if (Test-Path release) { Remove-Item -Recurse -Force release }
+          pnpm install --production --prefer-offline --frozen-lockfile
+          pnpm run generate
 
       - name: Build native binary (Windows)
         if: matrix.os == 'windows-latest'
-        shell: powershell
         run: |
           .\.venv\Scripts\activate
           uv run pyinstaller ./app.spec
 
       - name: Build native binary (Linux/macOS)
         if: matrix.os != 'windows-latest'
-        shell: bash
         run: |
           . .venv/bin/activate
           uv run pyinstaller ./app.spec
@@ -175,45 +117,34 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: app-${{ runner.os }}-${{ matrix.arch }}-${{ env.TAG_NAME }}
-          path: dist/YTPTube/**
+          path: dist/*
 
       - name: Package artifact (Unix)
         if: startsWith(env.TAG_NAME, 'v') && runner.os != 'Windows'
-        shell: bash
         run: |
           mkdir -p release
-          PKG_DIR="YTPTube-${{ env.TAG_NAME }}"
           ZIP_NAME="ytptube-${{ runner.os }}-${{ matrix.arch }}-${{ env.TAG_NAME }}.zip"
 
-          if [ ! -f "dist/YTPTube/YTPTube" ]; then
-            echo "Missing dist/YTPTube/YTPTube"
-            find dist -maxdepth 3 -type f | head -n 200
+          if [ ! -d dist ] || [ -z "$(ls -A dist)" ]; then
+            echo "dist directory is empty, skipping packaging."
             exit 1
           fi
 
-          rm -rf "dist/${PKG_DIR}"
-          mv "dist/YTPTube" "dist/${PKG_DIR}"
-
-          zip -yr "release/${ZIP_NAME}" "dist/${PKG_DIR}"
+          zip -r "release/${ZIP_NAME}" dist/
 
       - name: Package artifact (Windows)
         if: startsWith(env.TAG_NAME, 'v') && runner.os == 'Windows'
         shell: powershell
         run: |
-          $pkgDir = "YTPTube-${{ env.TAG_NAME }}"
           $zipName = "ytptube-${{ runner.os }}-${{ matrix.arch }}-${{ env.TAG_NAME }}.zip"
           New-Item -ItemType Directory -Force -Path release | Out-Null
 
-          if (!(Test-Path "dist\YTPTube\YTPTube.exe")) {
-            Write-Host "Missing dist\YTPTube\YTPTube.exe"
-            Get-ChildItem -Recurse dist | Select-Object -First 200 | Format-Table -AutoSize
+          if (!(Test-Path dist) -or !(Get-ChildItem -Path dist)) {
+            Write-Host "dist directory is empty, skipping packaging."
             exit 1
           }
 
-          if (Test-Path "dist\$pkgDir") { Remove-Item -Recurse -Force "dist\$pkgDir" }
-          Move-Item "dist\YTPTube" "dist\$pkgDir"
-
-          Compress-Archive -Path "dist\$pkgDir" -DestinationPath "release\$zipName" -Force
+          Compress-Archive -Path dist\* -DestinationPath "release\$zipName"
 
       - name: Upload to GitHub Release
         if: startsWith(env.TAG_NAME, 'v')

.github/workflows/update-yt-dlp.yml

@@ -42,7 +42,7 @@ jobs:
           VER=$(uv pip list --outdated | awk '$1 == "yt-dlp" {print $3}')
           if [ -n "$VER" ]; then
             echo "YTLDLP_VER=${VER}" >> "$GITHUB_OUTPUT"
-            uv pip install --upgrade yt-dlp[default]
+            uv pip install --upgrade yt-dlp
             uv sync --upgrade
             UPDATED=true
           else

.vscode/launch.json

@@ -2,7 +2,7 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "UI: Dev",
+      "name": "Node: Nuxt3",
       "request": "launch",
       "runtimeArgs": [
         "run",
@@ -10,7 +10,7 @@
         "--port",
         "8082"
       ],
-      "runtimeExecutable": "bun",
+      "runtimeExecutable": "pnpm",
       "type": "node",
       "cwd": "${workspaceFolder}/ui",
       "env": {
@@ -21,7 +21,7 @@
       "outputCapture": "std"
     },
     {
-      "name": "Python: main.py",
+      "name": "Python: main.py ",
       "type": "debugpy",
       "request": "launch",
       "program": "app/main.py",
@@ -33,18 +33,17 @@
         "YTP_DOWNLOAD_PATH": "${workspaceFolder}/var/downloads",
         "YTP_TEMP_PATH": "${workspaceFolder}/var/tmp",
         "PYDEVD_DISABLE_FILE_VALIDATION": "1",
-        "YTP_IGNORE_UI": "true",
-        "YTP_DEBUG": "true"
+        "YTP_IGNORE_UI": "true"
       },
     },
     {
-      "name": "UI: Generate",
+      "name": "Node: Generate UI",
       "request": "launch",
       "runtimeArgs": [
         "run",
         "generate"
       ],
-      "runtimeExecutable": "bun",
+      "runtimeExecutable": "pnpm",
       "type": "node",
       "cwd": "${workspaceFolder}/ui",
       "console": "internalConsole",

.vscode/settings.json

@@ -2,9 +2,211 @@
   "files.exclude": {
     "**/__pycache__": true
   },
-  "editor.rulers": [120],
-  "cSpell.enabled": false,
-  "css.styleSheets": ["ui/app/assets/css/*.css"],
+  "autopep8.args": [
+    "--max-line-length",
+    "120",
+    "--experimental"
+  ],
+  "editor.rulers": [
+    120
+  ],
+  "cSpell.words": [
+    "aconvert",
+    "addopts",
+    "ahas",
+    "ahash",
+    "aiocron",
+    "aiosqlite",
+    "alnum",
+    "anyio",
+    "Archiver",
+    "arrowdown",
+    "arrowleft",
+    "arrowless",
+    "arrowright",
+    "arrowup",
+    "asyncio",
+    "attl",
+    "autonumber",
+    "autouse",
+    "bgutil",
+    "bgutilhttp",
+    "bilibili",
+    "brainicism",
+    "brotlicffi",
+    "buildcache",
+    "cand",
+    "caplog",
+    "Cfmrc",
+    "choco",
+    "cifs",
+    "connectionpool",
+    "consoletitle",
+    "contenteditable",
+    "continuedl",
+    "cookiesfrombrowser",
+    "copyts",
+    "creationflags",
+    "cronsim",
+    "crosshairs",
+    "currsize",
+    "dailymotion",
+    "datas",
+    "dateparser",
+    "daterange",
+    "defusedxml",
+    "delenv",
+    "denoland",
+    "dlfields",
+    "dotdot",
+    "dotenv",
+    "dpkg",
+    "dunder",
+    "Edes",
+    "edgechromium",
+    "EISGPM",
+    "engineio",
+    "Errno",
+    "esac",
+    "euuo",
+    "eventbus",
+    "excepthook",
+    "exitcode",
+    "falsey",
+    "faststart",
+    "Fetc",
+    "fetchall",
+    "fetchone",
+    "filterwarnings",
+    "finaldir",
+    "flac",
+    "forcejson",
+    "forceprint",
+    "Fpasswd",
+    "fribidi",
+    "Funsafe",
+    "getpid",
+    "gibibytes",
+    "gitea",
+    "gitpython",
+    "googledrive",
+    "gpac",
+    "hiddenimports",
+    "hookspath",
+    "httpx",
+    "imagetools",
+    "isinstance",
+    "jmespath",
+    "jsonschema",
+    "kibibytes",
+    "Kodi",
+    "kwdefaults",
+    "lastgroup",
+    "levelno",
+    "libcurl",
+    "libjavascriptcoregtk",
+    "libmfx",
+    "libstdc",
+    "libwebkit",
+    "libx",
+    "LPAREN",
+    "matchtitle",
+    "matroska",
+    "mbed",
+    "mccabe",
+    "mebibytes",
+    "MEIPASS",
+    "merch",
+    "metaclass",
+    "Metaclasses",
+    "metadataparser",
+    "mgmt",
+    "Microformat",
+    "microformats",
+    "mkvtoolsnix",
+    "movflags",
+    "mpegts",
+    "msvideo",
+    "mult",
+    "multidict",
+    "muxdelay",
+    "mweb",
+    "nfsvers",
+    "nodesc",
+    "noninteractive",
+    "noprogress",
+    "onefile",
+    "oneline",
+    "parsel",
+    "pathex",
+    "pickleable",
+    "platformdirs",
+    "playlistend",
+    "playlistrandom",
+    "playlistreverse",
+    "plexmatch",
+    "postprocessor",
+    "preferredcodec",
+    "preferredquality",
+    "printtraffic",
+    "procps",
+    "pycryptodome",
+    "pycryptodomex",
+    "pyinstaller",
+    "pypi",
+    "pythonpath",
+    "quicktime",
+    "ratecontrol",
+    "rejecttitle",
+    "remux",
+    "reqs",
+    "RPAREN",
+    "rtime",
+    "rvfc",
+    "SIGUSR",
+    "smhd",
+    "socketio",
+    "softprops",
+    "sstr",
+    "startswith",
+    "SUPPRESSHELP",
+    "tablehead",
+    "tebibytes",
+    "testpaths",
+    "threadsafe",
+    "tiktok",
+    "timespec",
+    "tinyurl",
+    "tmpfilename",
+    "toplevel",
+    "trixie",
+    "ungroup",
+    "unmark",
+    "unnegated",
+    "unpickleable",
+    "Unraid",
+    "upgrader",
+    "urandom",
+    "urlparse",
+    "urlsafe",
+    "usegmt",
+    "usermod",
+    "ustr",
+    "vainfo",
+    "vcodec",
+    "vconvert",
+    "Vitest",
+    "writedescription",
+    "xerror",
+    "youtu",
+    "youtubepot",
+    "zstd",
+    "русский",
+    "العربية"
+  ],
+  "css.styleSheets": [
+    "ui/app/assets/css/*.css"
+  ],
   "search.exclude": {
     "ui/.nuxt": true,
     "ui/.output": true,
@@ -12,23 +214,49 @@
     "ui/exported": true,
     "ui/node_modules": true,
     "ui/.out": true,
-    "**/.venv": true
+    "**/.venv": true,
   },
-  "eslint.format.enable": false,
+  "eslint.format.enable": true,
   "eslint.ignoreUntitled": true,
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": true,
-  "python.testing.pytestArgs": ["app"],
-  "oxc.path.oxfmt": "./ui/node_modules/.bin/oxfmt",
-  "oxc.fmt.configPath": "./ui/.oxfmtrc.json",
-  "[typescript]": {
-    "editor.defaultFormatter": "oxc.oxc-vscode",
-    "editor.formatOnSave": true,
-    "editor.formatOnSaveMode": "file"
-  },
-  "[vue]": {
-    "editor.defaultFormatter": "oxc.oxc-vscode",
-    "editor.formatOnSave": true,
-    "editor.formatOnSaveMode": "file"
-  }
+  "json.schemas": [
+    {
+      "fileMatch": [
+        "**/tasks/*.json"
+      ],
+      "url": "./app/schema/task_definition.json"
+    },
+    {
+      "fileMatch": [
+        "**/config/conditions.json"
+      ],
+      "url": "./app/schema/conditions.json"
+    },
+    {
+      "fileMatch": [
+        "**/config/dl_fields.json"
+      ],
+      "url": "./app/schema/dl_fields.json"
+    },
+    {
+      "fileMatch": [
+        "**/config/notifications.json"
+      ],
+      "url": "./app/schema/notifications.json"
+    },
+    {
+      "fileMatch": [
+        "**/config/presets.json"
+      ],
+      "url": "./app/schema/presets.json"
+    },
+    {
+      "fileMatch": [
+        "**/config/tasks.json"
+      ],
+      "url": "./app/schema/tasks.json"
+    }
+  ],
+  "python.testing.cwd": "app/tests"
 }

CONTRIBUTING.md

@@ -1,149 +1,715 @@
 # Contributing to YTPTube
 
-YTPTube is a **personal-first project**. While contributions are welcome, **all final decisions rest with the maintainer**.
+Thank you for your interest in contributing to **YTPTube**! We welcome contributions from the community to help improve this project.
 
-## Core Principles
+This document provides guidelines and instructions for contributing to the project.
 
-* **The maintainer has final say** on all changes and project direction.
-* This project is built **for personal use first**. Community contributions are secondary.
-* **All contributions require prior discussion and approval.**
-* **All pull requests must target the `dev` branch** never `master`.
-* Contributions must align with the project's goals, architecture, and coding standards.
+## Table of Contents
 
-**Opening a PR without prior approval will result in immediate closure without review.**
+- [Contributing to YTPTube](#contributing-to-ytptube)
+  - [Table of Contents](#table-of-contents)
+  - [Code of Conduct](#code-of-conduct)
+  - [Getting Started](#getting-started)
+    - [Prerequisites](#prerequisites)
+      - [Backend Requirements](#backend-requirements)
+      - [Frontend Requirements](#frontend-requirements)
+      - [Optional Tools](#optional-tools)
+    - [Installing Required Package Managers](#installing-required-package-managers)
+      - [Installing uv (Python Package Manager)](#installing-uv-python-package-manager)
+      - [Installing pnpm (Node.js Package Manager)](#installing-pnpm-nodejs-package-manager)
+    - [Cloning the Repository](#cloning-the-repository)
+  - [Development Setup](#development-setup)
+    - [Backend Setup (Python)](#backend-setup-python)
+    - [Frontend Setup (Node.js)](#frontend-setup-nodejs)
+  - [Development Workflow](#development-workflow)
+    - [Working on a Feature or Bug Fix](#working-on-a-feature-or-bug-fix)
+  - [Branching Strategy](#branching-strategy)
+    - [Important Rules:](#important-rules)
+    - [Branch Naming Conventions:](#branch-naming-conventions)
+  - [Testing Requirements](#testing-requirements)
+    - [Backend Testing (Python)](#backend-testing-python)
+    - [Frontend Testing (TypeScript/Vue)](#frontend-testing-typescriptvue)
+    - [Test Coverage Expectations](#test-coverage-expectations)
+  - [Code Quality and Linting](#code-quality-and-linting)
+    - [Backend (Python)](#backend-python)
+    - [Frontend (TypeScript/Vue)](#frontend-typescriptvue)
+    - [Code Quality Checklist](#code-quality-checklist)
+  - [Pre-commit Hooks](#pre-commit-hooks)
+    - [Setting Up Pre-commit Hooks](#setting-up-pre-commit-hooks)
+    - [Before Submitting](#before-submitting)
+  - [Pull Request Guidelines](#pull-request-guidelines)
+    - [Creating a Pull Request](#creating-a-pull-request)
+    - [PR Review Process](#pr-review-process)
+    - [After Your PR is Merged](#after-your-pr-is-merged)
+  - [Code Style](#code-style)
+    - [Python Code Style](#python-code-style)
+    - [TypeScript/Vue Code Style](#typescriptvue-code-style)
+  - [Getting Help](#getting-help)
+    - [Resources](#resources)
+    - [Ask Questions](#ask-questions)
+    - [Reporting Bugs](#reporting-bugs)
+  - [License](#license)
 
 ---
 
-## Contribution Process
+## Code of Conduct
 
-### 1. Start a Discussion
+Please be respectful and constructive in all interactions. We aim to maintain a welcoming and inclusive community.
 
-Before writing any code, **propose your idea** through one of these channels:
+---
 
-* Open a **GitHub Issue** for bug fixes or small features
-* Start a **GitHub Discussion** for larger changes or questions
+## Getting Started
 
-**Include in your proposal:**
-* **What** you want to change
-* **Why** it's needed or beneficial
-  * Bug fixes and functional improvements are prioritized
-  * Performance enhancements with measurable impact
-  * Features that align with the project's core purpose
-  * **Not acceptable:** Personal UI/UX preferences, stylistic changes, or "I think it looks better" rationale
-* **How** you plan to implement it (high-level approach)
-* Any relevant context or use cases
+### Prerequisites
 
-### 2. Wait for Approval
+Before you begin, ensure you have the following tools installed on your system:
 
-* Only proceed after **explicit approval** from the maintainer to not waste effort.
-* The maintainer may suggest modifications or alternative approaches.
-* Not all proposals will be accepted this protects project coherence.
+#### Backend Requirements
 
-### 3. Develop Your Changes
+- **Python 3.13+**: YTPTube requires Python 3.13 or higher
+- **uv**: Modern Python package manager and virtual environment tool
+
+#### Frontend Requirements
+
+- **Node.js 18+**: Required for the Nuxt/Vue frontend
+- **pnpm**: Fast, disk space efficient package manager
+
+#### Optional Tools
+
+- **Git**: Version control
+- **Docker**: For containerized development (optional)
+- **ffmpeg**: Required for video player functionality
+
+### Installing Required Package Managers
+
+#### Installing uv (Python Package Manager)
+
+**uv** is a fast Python package installer and resolver written in Rust. It's used for managing Python dependencies and virtual environments.
+
+**On Linux/macOS:**
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**On Windows (PowerShell):**
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+**Using pip:**
+
+```bash
+pip install uv
+```
+
+**Verify installation:**
+
+```bash
+uv --version
+```
+
+For more information, visit: https://github.com/astral-sh/uv
+
+#### Installing pnpm (Node.js Package Manager)
+
+**pnpm** is a fast, disk space efficient package manager for Node.js.
+
+**Using npm:**
+
+```bash
+npm install -g pnpm
+```
+
+**Using Homebrew (macOS):**
+
+```bash
+brew install pnpm
+```
+
+**Using Scoop (Windows):**
+
+```bash
+scoop install pnpm
+```
+
+**Using standalone script:**
+
+```bash
+curl -fsSL https://get.pnpm.io/install.sh | sh -
+```
+
+**Verify installation:**
+
+```bash
+pnpm --version
+```
+
+For more information, visit: https://pnpm.io/installation
+
+### Cloning the Repository
+
+Clone the repository to your local machine:
+
+```bash
+git clone https://github.com/arabcoders/ytptube.git
+cd ytptube
+```
+
+**Important**: Always work on the `dev` branch, not `master`/`main`:
+
+```bash
+git checkout dev
+```
+
+---
+
+## Development Setup
+
+### Backend Setup (Python)
+
+1. **Navigate to the project root:**
+
+```bash
+cd ytptube
+```
+
+2. **Install Python dependencies using uv:**
+
+```bash
+uv sync
+```
+
+This will:
+- Create a virtual environment (`.venv/`)
+- Install all dependencies from `pyproject.toml`
+- Install development dependencies
+
+3. **Install development dependencies:**
+
+Development dependencies are defined in `pyproject.toml` under `[dependency-groups]`:
+
+```bash
+uv sync --group dev
+```
+
+4. **Verify installation:**
+
+```bash
+uv run python --version
+uv run pytest --version
+```
+
+5. **Run the backend development server:**
+
+```bash
+uv run app/main.py
+```
+
+The backend API will be available at `http://localhost:8081`
+
+### Frontend Setup (Node.js)
+
+1. **Navigate to the UI directory:**
+
+```bash
+cd ui
+```
+
+2. **Install Node.js dependencies using pnpm:**
+
+```bash
+pnpm install
+```
+
+> [!NOTE]
+> Create a `.env` file in the `ui/` directory based on `.env.example` to configure environment variables.
+> to link the frontend to the backend API.
+
+3. **Run the frontend development server:**
+
+```bash
+pnpm dev
+```
+
+The frontend will be available at `http://localhost:8082` (or the port shown in the terminal)
+
+4. **Verify the setup:**
+
+```bash
+pnpm run typecheck
+pnpm run lint
+```
+
+---
+
+## Development Workflow
+
+### Working on a Feature or Bug Fix
+
+1. **Ensure you're on the `dev` branch:**
 
-**Branch from `dev`:**
 ```bash
 git checkout dev
 git pull origin dev
-git checkout -b feature/descriptive-name
 ```
 
-**Follow project standards:**
-* Match existing code style and conventions
-* Add or update tests for all changes:
-  * New features **MUST** include tests
-  * Bug fixes **MUST** include a regression test
-* Ensure all linting and tests pass
-* Keep changes focused and atomic
+2. **Create a feature branch:**
 
-### 4. Submit a Pull Request
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/bug-description
+```
 
-**Target the `dev` branch:**
-* Reference the approved issue or discussion number
-* Provide a clear description of what changed and why
-* List any breaking changes or migration steps
-* Ensure CI checks pass
+3. **Make your changes**
 
-**PR template checklist:**
-- [ ] Discussed and approved beforehand
-- [ ] Targets `dev` branch
-- [ ] Tests added/updated and passing
-- [ ] Linting passes
-- [ ] Documentation updated (if needed)
+4. **Test your changes** (see [Testing Requirements](#testing-requirements))
+
+5. **Run code quality checks** (see [Code Quality and Linting](#code-quality-and-linting))
+
+6. **Commit your changes:**
+
+```bash
+git add .
+git commit -m "feat: add new feature description"
+# or
+git commit -m "fix: fix bug description"
+```
+
+7. **Push to your fork:**
+
+```bash
+git push origin feature/your-feature-name
+```
+
+8. **Create a Pull Request** targeting the `dev` branch
 
 ---
 
-## Automatic Rejections
+## Branching Strategy
 
-The following will be **closed immediately without review**:
+**YTPTube uses a two-branch strategy:**
 
-* PRs opened without prior discussion and approval
-* PRs targeting `master` instead of `dev`
-* Large refactors or architectural changes without approval
-* Fully AI-generated code without meaningful human oversight
-* Changes that don't align with project goals or philosophy
-* PRs where the contributor cannot explain or justify the changes
+- **`master`**: Production-ready code. Only maintainers merge to this branch.
+- **`dev`**: Development branch. **All contributions must target this branch.**
 
----
+### Important Rules:
 
-## AI-Assisted Development
+- ✅ **DO**: Create feature branches from `dev`
+- ✅ **DO**: Submit pull requests to `dev`
+- ❌ **DON'T**: Submit pull requests to `master`/`main`
+- ❌ **DON'T**: Commit directly to `dev` (use feature branches)
 
-AI tools are **permitted** as development aids, but **you remain fully responsible** for all submitted code.
+### Branch Naming Conventions:
 
-### Acceptable Use
-
-AI-assisted code is welcome **when**:
-
-* You **fully understand** every line being submitted
-* The code **seamlessly integrates** with existing patterns and style
-* You have **reviewed, tested, and validated** the output yourself
-* **Comprehensive tests** are included (not AI-generated stubs)
-* The code is **indistinguishable in quality** from hand-written contributions
-* You can **explain and defend** design decisions in the PR
-
-**AI is a tool, not a substitute for understanding.**
-
-### Not Acceptable
-
-The following will be rejected:
-
-* Fully AI-generated PRs with minimal human review
-* Code that introduces new patterns or abstractions without approval
-* "Prompt-dump" output that doesn't match project conventions
-* Changes the contributor cannot explain or justify
-* AI-generated test suites that don't meaningfully validate behavior
-
-### Disclosure
-
-You are **not required** to disclose AI usage. However, if code quality suggests pure AI generation without human oversight, the PR will be closed.
-
-**You are accountable for correctness, maintainability, and alignment regardless of how the code was created.**
+- `feature/description` - For new features
+- `fix/description` - For bug fixes
+- `refactor/description` - For code refactoring
+- `docs/description` - For documentation updates
+- `test/description` - For test additions/improvements
 
 ---
 
 ## Testing Requirements
 
-All contributions must include appropriate tests:
+**All code changes must include appropriate tests.** This ensures code quality and prevents regressions.
 
-* **New features:** Full test coverage including edge cases
-* **Bug fixes:** Regression test that fails before the fix and passes after
-* **Refactors:** Existing tests must continue to pass
-* **Performance changes:** Benchmarks or performance tests when applicable
+### Backend Testing (Python)
 
-Tests should be clear, maintainable, and actually validate the intended behavior.
+Tests are located in `app/tests/` and use **pytest**.
+
+**Running tests:**
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run specific test file
+uv run pytest app/tests/test_download.py
+
+# Run with verbose output
+uv run pytest -v
+
+# Run with coverage
+uv run pytest --cov=app --cov-report=html
+```
+
+**Creating new tests:**
+
+1. Create a test file in `app/tests/` with the prefix `test_`
+2. Use pytest conventions:
+
+```python
+import pytest
+from app.library.YourModule import YourClass
+
+class TestYourClass:
+    def test_feature_name(self):
+        """Test description."""
+        # Arrange
+        instance = YourClass()
+        
+        # Act
+        result = instance.method()
+        
+        # Assert
+        assert result == expected_value
+    
+    @pytest.mark.asyncio
+    async def test_async_feature(self):
+        """Test async functionality."""
+        result = await async_function()
+        assert result is not None
+```
+
+**Testing Singleton Classes:**
+
+When testing singleton classes, always reset the singleton instance:
+
+```python
+from app.library.Presets import Presets
+
+class TestPresets:
+    def setup_method(self):
+        """Reset singleton before each test."""
+        Presets._reset_singleton()
+    
+    def teardown_method(self):
+        """Reset singleton after each test."""
+        Presets._reset_singleton()
+```
+
+### Frontend Testing (TypeScript/Vue)
+
+Tests are located in `ui/tests/` and use **Vitest**.
+
+**Running tests:**
+
+```bash
+cd ui
+
+# Run all tests
+pnpm test
+
+# Run in watch mode
+pnpm test:watch
+
+# Run with coverage
+pnpm run test --coverage
+```
+
+**Creating new tests:**
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import YourComponent from '~/components/YourComponent.vue'
+
+describe('YourComponent', () => {
+    it('renders correctly', () => {
+        const wrapper = mount(YourComponent)
+        expect(wrapper.exists()).toBe(true)
+    })
+    
+    it('handles user interaction', async () => {
+        const wrapper = mount(YourComponent)
+        await wrapper.find('button').trigger('click')
+        expect(wrapper.emitted('event-name')).toBeTruthy()
+    })
+})
+```
+
+### Test Coverage Expectations
+
+- **New features**: Must include comprehensive tests
+- **Bug fixes**: Must include a test that reproduces the bug
+- **Refactoring**: Existing tests should still pass
+- **Coverage goal**: Aim for >80% code coverage on new code
 
 ---
 
-## Questions?
+## Code Quality and Linting
 
-* Check existing **Issues** and **Discussions** first
-* Join the project **Discord** for real-time discussion
-* Be patient, this is a personal project with limited maintenance time
+### Backend (Python)
+
+YTPTube uses **Ruff** for linting and formatting Python code.
+
+**Running Ruff:**
+
+```bash
+# Check for linting issues
+uv run ruff check app/
+
+# Auto-fix linting issues
+uv run ruff check --fix app/
+
+# Format code
+uv run ruff format app/
+
+# Check specific file
+uv run ruff check app/library/Download.py
+uv run ruff check --fix app/library/Download.py
+```
+
+**Configuration:**
+
+Ruff configuration is in `pyproject.toml` under `[tool.ruff]`.
+
+### Frontend (TypeScript/Vue)
+
+The frontend uses **ESLint** for linting and **TypeScript** for type checking.
+
+**Running checks:**
+
+```bash
+cd ui
+
+# Type checking
+pnpm run typecheck
+
+# Linting
+pnpm run lint
+
+# Auto-fix linting issues
+pnpm run lint:fix
+```
+
+### Code Quality Checklist
+
+Before committing, ensure:
+
+- ✅ All tests pass (`uv run pytest` and `pnpm test`)
+- ✅ No linting errors (`ruff check` and `pnpm run lint`)
+- ✅ TypeScript compilation succeeds (`pnpm run typecheck`)
+- ✅ Code is formatted properly
+- ✅ No unused imports or variables
+- ✅ Type hints are present (Python 3.13+)
+
+---
+
+## Pre-commit Hooks
+
+YTPTube uses a custom shell script-based pre-commit hook that runs all checks in parallel for faster execution.
+
+### Setting Up Pre-commit Hooks
+
+1. **Create the pre-commit hook script:**
+
+Create a file at `.git/hooks/pre-commit` with the following content:
+
+```bash
+#!/bin/sh
+set -eu
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+cd "$REPO_ROOT" || exit 1
+
+PIDS_FILE=$(mktemp)
+trap 'rm -f "$PIDS_FILE"' EXIT
+
+export CI=1
+run_step() {
+  local label="$1"
+  shift
+  echo "🔹 Starting $label..." >&2
+  (
+    if ! "$@"; then
+      echo "❌ [$label] failed. Commit aborted." >&2
+      exit 1
+    else
+      echo "✅ [$label] passed." >&2
+    fi
+  ) &
+  echo $! >>"$PIDS_FILE"
+}
+
+run_step "Ruff (Python linter)" uv run ruff check app/
+run_step "PyTest" uv run pytest app/ -q
+run_step "ESLint" pnpm --dir ./ui run lint
+run_step "Vitest" pnpm --dir ./ui run test
+
+fail=0
+while read -r pid; do
+  if ! wait "$pid"; then
+    fail=1
+  fi
+done <"$PIDS_FILE"
+
+if [ "$fail" -eq 1 ]; then
+  echo "❌ One or more checks failed. Commit aborted." >&2
+  exit 1
+fi
+
+echo "✅ All checks passed. Commit allowed."
+exit 0
+```
+
+2. **Make the hook executable:**
+
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+3. **Test the hook:**
+
+```bash
+# Test manually
+.git/hooks/pre-commit
+
+# Or make a test commit
+git commit --allow-empty -m "test: verify pre-commit hook"
+```
+
+---
+
+### Before Submitting
+
+✅ **Checklist:**
+
+- [ ] Code is on a feature branch created from `dev`
+- [ ] All tests pass locally
+- [ ] Code passes linting and formatting checks
+- [ ] TypeScript types are properly defined (no `any`) without justification
+- [ ] New features include tests
+- [ ] Documentation is updated (if applicable)
+- [ ] Commit messages are clear and descriptive
+- [ ] Pre-commit hooks pass
+
+---
+
+## Pull Request Guidelines
+
+### Creating a Pull Request
+
+1. **Push your branch to GitHub:**
+
+```bash
+git push origin feature/your-feature-name
+```
+
+2. **Open a Pull Request on GitHub**
+
+3. **Target the `dev` branch** (not `master`)
+
+4. **Fill out the PR template** with:
+   - Description of changes
+   - Related issue numbers (if applicable)
+   - Testing performed
+   - Screenshots (for UI changes)
+   - Breaking changes (if any)
+
+### PR Review Process
+
+1. **Automated Checks**: CI pipeline runs tests and linting
+2. **Code Review**: Maintainers review your code
+3. **Feedback**: Address any requested changes
+4. **Approval**: Once approved, maintainers will merge
+
+### After Your PR is Merged
+
+1. **Delete your feature branch** (optional but recommended)
+2. **Pull the latest `dev` branch:**
+
+```bash
+git checkout dev
+git pull origin dev
+```
+
+3. **Celebrate!** Thank you for contributing!
+
+---
+
+## Code Style
+
+### Python Code Style
+
+- **Line length**: 120 characters
+- **Indentation**: 4 spaces
+- **Quotes**: Double quotes for strings
+- **Type hints**: Use Python 3.13+ type hints
+- **Imports**: Absolute imports from `app.library`
+- **Comparison**: Use Yoda comparisons for literals (`"value" == variable`)
+
+**Example:**
+
+```python
+from app.library.Download import Download
+from app.library.ItemDTO import ItemDTO
+
+async def process_download(item: ItemDTO) -> bool:
+    """Process a download item."""
+    try:
+        if "pending" == item.status:  # Yoda comparison
+            result = await Download.start(item)
+            return result.success
+    except Exception as e:
+        LOG.error(f"Download failed: {e}")
+        return False
+```
+
+### TypeScript/Vue Code Style
+
+- **Type safety**: No `any` types without justification
+- **Explicit imports**: Import all Vue functions explicitly
+- **Component structure**: Use `<script setup lang="ts">`
+- **Props/Emits**: Always type-define
+
+**Example:**
+
+```vue
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue'
+import type { DownloadItem } from '~/types/download'
+
+const props = defineProps<{
+    items: Array<DownloadItem>
+}>()
+
+const emit = defineEmits<{
+    (e: 'itemSelected', item: DownloadItem): void
+}>()
+
+const selectedItem = ref<DownloadItem | null>(null)
+</script>
+```
+
+---
+
+## Getting Help
+
+### Resources
+
+- **API Docs**: See [API.md](API.md) for API reference
+- **FAQ**: Check [FAQ.md](FAQ.md) for common questions
+- **Issues**: Browse existing [GitHub Issues](https://github.com/arabcoders/ytptube/issues)
+
+### Ask Questions
+
+- **GitHub Discussions**: For general questions and discussions
+- **GitHub Issues**: For bug reports and feature requests
+- **Pull Requests**: For code review and implementation questions
+- **Discord**: Join our community on Discord (link in README)
+
+### Reporting Bugs
+
+When reporting bugs, please include:
+
+1. **Description**: Clear description of the issue
+2. **Steps to Reproduce**: Detailed steps to reproduce the bug
+3. **Expected Behavior**: What you expected to happen
+4. **Actual Behavior**: What actually happened
+5. **Environment**: OS, Python version, Node version, etc.
+6. **Logs**: Relevant error messages or logs
+7. **Screenshots**: If applicable
 
 ---
 
 ## License
 
-By contributing, you agree that your code will be licensed under the project's **MIT License**.
+By contributing to YTPTube, you agree that your contributions will be licensed under the [MIT License](LICENSE).
 
-Thank you for respecting this contribution process. It helps maintain project quality and the maintainer's sanity.
+---
+
+Thank you for contributing to YTPTube! Your efforts help make this project better for everyone.

Dockerfile

@@ -1,12 +1,13 @@
+# syntax=docker/dockerfile:1.4
 FROM node:lts-alpine AS node_builder
 
 WORKDIR /app
 COPY ui ./
 ENV NODE_ENV=production
 RUN if [ ! -f "/app/exported/index.html" ]; then \
-  npm install -g bun && \
-  NODE_ENV=production bun install --frozen-lockfile --production && \
-  bun run generate; \
+  npm install -g pnpm && \
+  NODE_ENV=production pnpm install --frozen-lockfile --prod --ignore-scripts && \
+  pnpm run generate; \
   else echo "Skipping UI build, already built."; fi
 
 FROM python:3.13-bookworm AS python_builder

FAQ.md

@@ -3,80 +3,66 @@
 Certain configuration values can be set via environment variables, using the `-e` parameter on the docker command line, 
 or the `environment:` section in `compose.yaml` file.
 
-<details>
-<summary>Click to expand</summary>
-
-| Environment Variable            | Description                                                         | Default               |
-| ------------------------------- | ------------------------------------------------------------------- | --------------------- |
-| TZ                              | The timezone to use for the application                             | `(not_set)`           |
-| YTP_OUTPUT_TEMPLATE             | The template for the filenames of the downloaded videos             | `%(title)s.%(ext)s`   |
-| YTP_DEFAULT_PRESET              | The default preset to use for the download                          | `default`             |
-| YTP_INSTANCE_TITLE              | The title of the instance                                           | `(not_set)`           |
-| YTP_FILE_LOGGING                | Whether to log to file                                              | `false`               |
-| YTP_DOWNLOAD_PATH               | Path to where the downloads will be saved                           | `/downloads`          |
-| YTP_MAX_WORKERS                 | The maximum number of workers to use for downloading                | `20`                  |
-| YTP_MAX_WORKERS_PER_EXTRACTOR   | The maximum number of concurrent downloads per extractor            | `2`                   |
-| YTP_AUTH_USERNAME               | Username for basic authentication                                   | `(not_set)`           |
-| YTP_AUTH_PASSWORD               | Password for basic authentication                                   | `(not_set)`           |
-| YTP_CONSOLE_ENABLED             | Whether to enable the console                                       | `false`               |
-| YTP_REMOVE_FILES                | Remove the actual file when clicking the remove button              | `false`               |
-| YTP_CONFIG_PATH                 | Path to where the config files will be stored.                      | `/config`             |
-| YTP_TEMP_PATH                   | Path to where tmp files are stored.                                 | `/tmp`                |
-| YTP_TEMP_KEEP                   | Whether to keep the Individual video temp directory or remove it    | `false`               |
-| YTP_HOST                        | Which IP address to bind to                                         | `0.0.0.0`             |
-| YTP_PORT                        | Which port to bind to                                               | `8081`                |
-| YTP_LOG_LEVEL                   | Log level                                                           | `info`                |
-| YTP_STREAMER_VCODEC             | The video encoding codec, default to GPU and fallback to software   | `""`                  |
-| YTP_STREAMER_ACODEC             | The audio codec to use for in-browser streaming                     | `aac`                 |
-| YTP_VAAPI_DEVICE                | The VAAPI device to use for hardware acceleration.                  | `/dev/dri/renderD128` |
-| YTP_ACCESS_LOG                  | Whether to log access to the web server                             | `true`                |
-| YTP_DEBUG                       | Whether to turn on debug mode                                       | `false`               |
-| YTP_DEBUGPY_PORT                | The port to use for the debugpy debugger                            | `5678`                |
-| YTP_EXTRACT_INFO_TIMEOUT        | The timeout for extracting video information                        | `70`                  |
-| YTP_PIP_PACKAGES                | A space separated list of pip packages to install                   | `(not_set)`           |
-| YTP_PIP_IGNORE_UPDATES          | Do not update the custom pip packages                               | `false`               |
-| YTP_PICTURES_BACKENDS           | A comma separated list of pictures urls to use                      | `(not_set)`           |
-| YTP_BROWSER_CONTROL_ENABLED     | Whether to enable the file browser actions                          | `false`               |
-| YTP_YTDLP_AUTO_UPDATE           | Whether to enable the auto update for yt-dlp                        | `true`                |
-| YTP_YTDLP_DEBUG                 | Whether to turn debug logging for the internal `yt-dlp` package     | `false`               |
-| YTP_YTDLP_VERSION               | The version of yt-dlp to use. Defaults to latest version            | `(not_set)`           |
-| YTP_BROWSER_URL                 | Remote browser endpoint for the bundled `browser` extractor         | `(not_set)`           |
-| YTP_FLARESOLVERR_URL            | FlareSolverr endpoint URL.                                          | `(not_set)`           |
-| YTP_FLARESOLVERR_MAX_TIMEOUT    | Max FlareSolverr challenge timeout in seconds                       | `120`                 |
-| YTP_FLARESOLVERR_CLIENT_TIMEOUT | HTTP client timeout (seconds) when calling FlareSolverr             | `120`                 |
-| YTP_FLARESOLVERR_CACHE_TTL      | The cache TTL (in seconds) for FlareSolverr solutions               | `600`                 |
-| YTP_BASE_PATH                   | Set this if you are serving YTPTube from sub-folder                 | `/`                   |
-| YTP_PREVENT_LIVE_PREMIERE       | Prevents the initial youtube premiere stream from being downloaded  | `false`               |
-| YTP_QUEUE_DISPLAY_LIMIT         | Max queued downloads returned to the UI. `0` = unlimited            | `100`                 |
-| YTP_LIVE_PREMIERE_BUFFER        | buffer time in minutes to add to video duration                     | `5`                   |
-| YTP_TASKS_HANDLER_TIMER         | The cron expression for the tasks handler timer                     | `15 */1 * * *`        |
-| YTP_TEMP_DISABLED               | Disable temp files handling.                                        | `false`               |
-| YTP_ALLOW_INTERNAL_URLS         | Allow requests to internal URLs                                     | `false`               |
-| YTP_SIMPLE_MODE                 | Switch default interface to Simple mode.                            | `false`               |
-| YTP_STATIC_UI_PATH              | Path to custom static UI files.                                     | `(not_set)`           |
-| YTP_AUTO_CLEAR_HISTORY_DAYS     | Number of days after which completed download history is cleared.   | `0`                   |
-| YTP_DEFAULT_PAGINATION          | The default number of items per page for history.                   | `50`                  |
-| YTP_TASK_HANDLER_RANDOM_DELAY   | The maximum random delay in seconds before starting a task handler. | `60`                  |
-| YTP_IGNORE_ARCHIVED_ITEMS       | Don't report archived items in the download history.                | `false`               |
-| YTP_CHECK_FOR_UPDATES           | Whether to check for application updates.                           | `true`                |
-| YTP_EXTRACT_INFO_CONCURRENCY    | The number of concurrent extract info operations.                   | `4`                   |
-| YTP_THUMB_CONCURRENCY           | The number of concurrent ffmpeg thumbnail generations allowed.      | `2`                   |
-| YTP_THUMB_GENERATE              | Enable ffmpeg thumbnail generation when no local thumbnail exists.  | `true`                |
-| YTP_THUMB_SIDECAR               | Save generated thumbnails next to media instead of temp cache.      | `false`               |
-| YTP_DISABLE_EXEC                | Strip some dangerous yt-dlp options.                                | `false`               |
-</details>
+| Environment Variable           | Description                                                        | Default               |
+| ------------------------------ | ------------------------------------------------------------------ | --------------------- |
+| TZ                             | The timezone to use for the application                            | `(not_set)`           |
+| YTP_OUTPUT_TEMPLATE            | The template for the filenames of the downloaded videos            | `%(title)s.%(ext)s`   |
+| YTP_DEFAULT_PRESET             | The default preset to use for the download                         | `default`             |
+| YTP_INSTANCE_TITLE             | The title of the instance                                          | `(not_set)`           |
+| YTP_FILE_LOGGING               | Whether to log to file                                             | `false`               |
+| YTP_DOWNLOAD_PATH              | Path to where the downloads will be saved                          | `/downloads`          |
+| YTP_MAX_WORKERS                | The maximum number of workers to use for downloading               | `20`                  |
+| YTP_MAX_WORKERS_PER_EXTRACTOR  | The maximum number of concurrent downloads per extractor           | `2`                   |
+| YTP_AUTH_USERNAME              | Username for basic authentication                                  | `(not_set)`           |
+| YTP_AUTH_PASSWORD              | Password for basic authentication                                  | `(not_set)`           |
+| YTP_CONSOLE_ENABLED            | Whether to enable the console                                      | `false`               |
+| YTP_REMOVE_FILES               | Remove the actual file when clicking the remove button             | `false`               |
+| YTP_CONFIG_PATH                | Path to where the config files will be stored.                     | `/config`             |
+| YTP_TEMP_PATH                  | Path to where tmp files are stored.                                | `/tmp`                |
+| YTP_TEMP_KEEP                  | Whether to keep the Individual video temp directory or remove it   | `false`               |
+| YTP_HOST                       | Which IP address to bind to                                        | `0.0.0.0`             |
+| YTP_PORT                       | Which port to bind to                                              | `8081`                |
+| YTP_LOG_LEVEL                  | Log level                                                          | `info`                |
+| YTP_STREAMER_VCODEC            | The video encoding codec, default to GPU and fallback to software  | `""`                  |
+| YTP_STREAMER_ACODEC            | The audio codec to use for in-browser streaming                    | `aac`                 |
+| YTP_VAAPI_DEVICE               | The VAAPI device to use for hardware acceleration.                 | `/dev/dri/renderD128` |
+| YTP_ACCESS_LOG                 | Whether to log access to the web server                            | `true`                |
+| YTP_DEBUG                      | Whether to turn on debug mode                                      | `false`               |
+| YTP_DEBUGPY_PORT               | The port to use for the debugpy debugger                           | `5678`                |
+| YTP_EXTRACT_INFO_TIMEOUT       | The timeout for extracting video information                       | `70`                  |
+| YTP_UI_UPDATE_TITLE            | Whether to update the title of the page with the current stats     | `true`                |
+| YTP_PIP_PACKAGES               | A space separated list of pip packages to install                  | `(not_set)`           |
+| YTP_PIP_IGNORE_UPDATES         | Do not update the custom pip packages                              | `false`               |
+| YTP_PICTURES_BACKENDS          | A comma separated list of pictures urls to use                     | `(not_set)`           |
+| YTP_BROWSER_CONTROL_ENABLED    | Whether to enable the file browser actions                         | `false`               |
+| YTP_YTDLP_AUTO_UPDATE          | Whether to enable the auto update for yt-dlp                       | `true`                |
+| YTP_YTDLP_DEBUG                | Whether to turn debug logging for the internal `yt-dlp` package    | `false`               |
+| YTP_YTDLP_VERSION              | The version of yt-dlp to use. Defaults to latest version           | `(not_set)`           |
+| YTP_BASE_PATH                  | Set this if you are serving YTPTube from sub-folder                | `/`                   |
+| YTP_PREVENT_LIVE_PREMIERE      | Prevents the initial youtube premiere stream from being downloaded | `false`               |
+| YTP_LIVE_PREMIERE_BUFFER       | buffer time in minutes to add to video duration                    | `5`                   |
+| YTP_TASKS_HANDLER_TIMER        | The cron expression for the tasks handler timer                    | `15 */1 * * *`        |
+| YTP_PLAYLIST_ITEMS_CONCURRENCY | The number of playlist items be to processed at same time          | `1`                   |
+| YTP_TEMP_DISABLED              | Disable temp files handling.                                       | `false`               |
+| YTP_DOWNLOAD_PATH_DEPTH        | How many subdirectories to show in auto complete.                  | `1`                   |
+| YTP_ALLOW_INTERNAL_URLS        | Allow requests to internal URLs                                    | `false`               |
+| YTP_SIMPLE_MODE                | Switch default interface to Simple mode.                           | `false`               |
+| YTP_STATIC_UI_PATH             | Path to custom static UI files.                                    | `(not_set)`           |
+| YTP_AUTO_CLEAR_HISTORY_DAYS    | Number of days after which completed download history is cleared.  | `0`                   |
+| YTP_DEFAULT_PAGINATION         | The default number of items per page for history.                  | `50`                  |
 
 > [!NOTE]
-> To raise the worker limit for a specific extractor, set an env variable using this format: `YTP_MAX_WORKERS_FOR_<EXTRACTOR_NAME>`
-> The extractor name must be uppercase. You can find the extractor name in the download logs. This value cannot be 
-> higher than `YTP_MAX_WORKERS`; higher values are ignored.
->
-> `YTP_SIMPLE_MODE=true` only applies when the browser has no saved layout choice yet. Users can still choose a layout in 
-> WebUI Settings. `/?simple=1` forces and saves Simple for that browser.
-> 
-> `YTP_AUTO_CLEAR_HISTORY_DAYS`  `0` days means no automatic clearing of the download history. lowest value that will 
-> trigger the clearing is `1` day. This setting will **NOT** delete the downloaded files, it will only clear the 
-> history from the database.
+> To raise the maximum workers for specific extractor, you need to add a ENV variable that follows the pattern `YTP_MAX_WORKERS_FOR_<EXTRACTOR_NAME>`.
+> The extractor name must be in uppercase, to know the extractor name, check the log for the specific extractor used for the download.
+> The limit should not exceed the `YTP_MAX_WORKERS` value as it will be ignored.
+
+> [!IMPORTANT]
+> The env variable `YTP_SIMPLE_MODE` only control what being displayed for first time visitor, the users can still switch between the two modes via the WebUI settings page.
+
+## Notes about YTP_AUTO_CLEAR_HISTORY_DAYS
+
+- `0` days means no automatic clearing of the download history. lowest value that will trigger the clearing is `1` day.
+- This setting will **NOT** delete the downloaded files, it will only clear the history from the database.
 
 # Browser extensions & bookmarklets
 
@@ -98,7 +84,7 @@ Change the the variable `url` and `preset` variables to match your YTPTube insta
 
 ## iOS Shortcuts
 
-You can download [Add To YTPTube](https://www.icloud.com/shortcuts/6df61c97d97b4e539c9100999ba39dd4) shortcut and use it to send links to your YTPTube instance.
+You can download [Add To YTPTube](https://www.icloud.com/shortcuts/18b8f70666a04a06aed09424f97ce951) shortcut and use it to send links to your YTPTube instance.
 You have to edit the shortcut and replace the following:
 
 - `https://ytp.example.org` with your YTPTube instance.
@@ -110,7 +96,7 @@ and use that preset to download directly from your iOS device.
 
 ### Advanced iOS Shortcut
 
-This shortcut [YTPTube To Media](https://www.icloud.com/shortcuts/4dc579382f254635ad5785424055f173) is more advanced, as it's parses
+This shortcut [YTPTube To Media](https://www.icloud.com/shortcuts/6e3db0bd532843e3aec70e6ce211be08) is more advanced, as it's parses
 the `yt-dlp` output and attempt to download the media directly to your iOS device. It doesn't always work, but it's a good
 starting point for those who want to download media directly to their iOS device. We provide no support for this use case
 other than the shortcut itself. this shortcut missing support for parsing the http_headers, it's only parse the cookies.
@@ -123,35 +109,6 @@ As this is a simple basic authentication, if your browser doesn't show the promp
 
 `http://username:password@your_ytptube_url:port`
 
-# Security recommendations
-
-YTPTube is designed for LAN and home-lab use behind a firewall or reverse proxy. The web interface and API are
-unauthenticated by default because in a trusted network, auth adds friction without meaningful benefit. However,
-if you expose YTPTube to the internet directly or via port forwarding **YOU MUST enable authentication**.
-
-### Without auth, anyone who can reach the API can:
-
-- Download arbitrary content through your IP and server.
-- Delete or modify your downloaded files and database.
-- Run arbitrary `yt-dlp` options, including `--exec`, which executes shell commands inside the container.
-
-This is not a vulnerability, it's the intended design. The `cli` field passes options directly to `yt-dlp`,
-a tool that by design can execute commands. Auth is the mechanism that controls who gets to use that power.
-
-**If you expose YTPTube to untrusted networks**, do one of the following:
-
-1. **Enable authentication** — set both `YTP_AUTH_USERNAME` and `YTP_AUTH_PASSWORD`.
-2. **Put it behind a reverse proxy** with its own authentication layer (see [Run behind reverse proxy](#run-behind-reverse-proxy)).
-3. **Keep it on a private network** with no public exposure.
-
-YTPTube already gates other powerful features behind explicit opt-in: the built-in terminal, file browser actions and internal
-URL requests for example. The `cli` field is no different, its power is by design, and access control is your responsibility.
-
-> [!NOTE]
-> If you choose to run without authentication but still want to reduce at least some impact, you can set
-> `YTP_DISABLE_EXEC=true`. This strips some dangerous options at run time. However, understand that this is not a 
-> substitute for auth an unauthenticated API is still fully open for all other operations.
-
 # I cant download anything
 
 If you are receiving errors like:
@@ -204,49 +161,27 @@ YTP_YTDLP_VERSION=2025.07.21 or master or nightly
 
 Then restart the container to apply the changes.
 
-# Custom output template placeholders
-
-YTPTube supports custom `ytp_*` placeholders in `yt-dlp` output template via the following syntax `%(ytp_*:<args>)s`.
-
-## Currently available extra placeholders are:
-
-- `ytp_random`: random mixed letters and digits,
-  - `N` A number is required to specify the length of the random string, for example `%(ytp_random:8)s` will generate a random string of 8 characters. 
-  - if the args followed by `:s` it will generate random letters only, if followed by `:d` it will generate random digits only.
-
-## Examples of the custom placeholders in action:
-
-- Template: `%(title)s [%(ytp_random:8)s].%(ext)s`
-  - Example result: `My Video [A7k2Pq9Z].mp4`
-- Template: `%(uploader)s/%(ytp_random:6:d)s - %(title)s.%(ext)s`
-  - Example result: `MyChannel/483920 - My Video.mp4`
-- Template: `%(playlist)s/%(ytp_random:10:s)s/%(title)s.%(ext)s`
-  - Example result: `Favorites/QwErTyUiOp/My Video.mp4`
-
-> [!NOTE]
-> `%(ytp_` placeholders are a YTPTube extension and not avaliable via console or directly via yt-dlp.
-
 # How can I monitor sites without RSS feeds?
 
-YTPTube includes a **generic task handler** that turns JSON definitions into site-specific scrapers. You can use it
+YTPTube includes a **generic task handler** that turns JSON definition files into site-specific scrapers. You can use it
 to watch pages that do not expose RSS or public APIs and automatically enqueue new links into the download queue.
 
-1. Create definition via the WebUI > tasks > Definitions.
-2. Create task that reference same url click on inspect to see the results. Make sure it uses a preset that enables 
-   a download archive (`--download-archive`).
-3. When the task handler run, the handler scans the definitions, picks the first definition whose `match` rule covers
-   the task URL, fetches the page, extracts items, and queues the unseen ones.
+1. Create definition files under `/config/tasks/*.json` (for Docker this is the mounted `config/tasks/` folder).
+2. Keep your scheduled task in `tasks.json` pointing at the page you want to monitor and make sure it uses a preset that
+   enables a download archive (`--download-archive`).
+3. When the task runs, the handler scans the JSON files, picks the first definition whose `match` rule covers the task
+   URL, fetches the page, extracts items, and queues the unseen ones.
 
 ### Definition schema
 
-Each definition must contain a single JSON object with the following keys:
+Each file must contain a single JSON object with the following keys:
 
 ```json5
 {
   "name": "example",                  // Friendly identifier shown in logs
-  "match_url": [
-    "https://example.com/articles/*", // Glob strings
-    "https://example.com/post/[0-9]+" // Regex strings
+  "match": [
+    "https://example.com/articles/*", // Glob strings, or objects with {"regex": "..."} or {"glob": "..."}
+    { "regex": "https://example.com/post/[0-9]+" }
   ],
   "engine": {                         // Optional, defaults to HTTPX
     "type": "httpx",                  // "httpx" (default) or "selenium"
@@ -264,7 +199,7 @@ Each definition must contain a single JSON object with the following keys:
     "headers": { "User-Agent": "MyAgent/1.0" },
     "params": { "page": 1 },
     "data": null,
-    "json_data": null,
+    "json": null,
     "timeout": 30
   },
   "response": {                      // Optional: how to interpret the body
@@ -304,7 +239,6 @@ For JSON endpoints, switch the response format and use `jsonpath` selectors:
 
 ```json5
 {
-  ...
   "response": { "type": "json" },
   "parse": {
     "items": {
@@ -340,6 +274,9 @@ For JSON endpoints, switch the response format and use `jsonpath` selectors:
   the moment. Optional keys: `arguments` (list or string), `wait_for` (type `css`/`xpath` + `expression`), `wait_timeout`,
   and `page_load_timeout`.
 
+Definitions are reloaded automatically when files change, so you can tweak them without restarting YTPTube. Check
+`var/config/tasks/01-*.json` for sample files.
+
 > [!NOTE]
 > A machine-readable schema is available at `app/schema/task_definition.json` if you want to validate your JSON with editors or CI tools.
 
@@ -375,13 +312,22 @@ Then simply create a new preset, and in the `Command options for yt-dlp` field s
 
 ```bash
 --extractor-args "youtubepot-bgutilhttp:base_url=http://bgutil_provider:4416" 
+--extractor-args "youtube:player-client=default,tv,mweb;formats=incomplete"
 ```
 
+you and also enable the fallback by using the follow extractor args
+
+```bash
+--extractor-args "youtubepot-bgutilhttp:base_url=http://bgutil_provider:4416;disable_innertube=1"
+--extractor-args "youtube:player-client=default,tv,mweb;formats=incomplete"
+```
+
+Use this alternative extractor args in case the extractor fails to get the pot tokens from the bgutil provider server. 
 For more information please visit [bgutil-ytdlp-pot-provider](https://github.com/Brainicism/bgutil-ytdlp-pot-provider) project.
 
 # Troubleshooting and submitting issues
 
-Before asking a question or submitting an issue for YTPTube, please remember that YTPTube is only a wrapper for 
+Before asking a question or submitting an issue for YTPTube, please remember that YTPTube is only a thin wrapper for 
 [yt-dlp](https://github.com/yt-dlp/yt-dlp). Any issues you might be experiencing with authentication to video websites, 
 postprocessing, permissions, other `yt-dlp options` configurations which seem not to work, or anything else that 
 concerns the workings of the underlying yt-dlp library, need not be opened on the YTPTube project.
@@ -392,8 +338,7 @@ and once that is working, importing the options that worked for you into a new `
 ## Via HTTP
 
 If you have enabled the web terminal via `YTP_CONSOLE_ENABLED` environment variable, simply go to `Other > Terminal` use
- the yt-dlp command, the interface is jailed to the `yt-dlp` binary you can't access anything else. Or from download form 
- by clicking `advanced options` button than the yellow terminal icon `Run directly in console`.
+ the yt-dlp command, the interface is jailed to the `yt-dlp` binary you can't access anything else.
 
 ## Via CLI 
 
@@ -553,7 +498,7 @@ as we only test for GPU encoding once on first video stream.
 
 # Allowing internal URLs requests
 
-By default, YTPTube prevents requests to internal resources. However, if you want to allow requests to internal URLs, you can set the `YTP_ALLOW_INTERNAL_URLS` environment variable to `true`. This will allow requests to internal URLs. 
+By default, YTPTube prevents requests to internal resources, for security reasons. However, if you want to allow requests to internal URLs, you can set the `YTP_ALLOW_INTERNAL_URLS` environment variable to `true`. This will allow requests to internal URLs. 
 
 We do not recommend enabling this option unless you know what you are doing, as it can expose your internal network to 
 potential security risks. This should only be used if it's truly needed.
@@ -607,6 +552,7 @@ services:
 After making the changes, restart your container. This should resolve the "No space left on device" 
 error during download.
 
+
 # How to prevent loading screen during YouTube premieres?
 
 Depending on how you look at it, YTPTube live download implementation is rather great and fast. However, during YouTube 
@@ -615,144 +561,10 @@ playing. By default we wait for 5min + the duration of the video before starting
 the loading screen. However, you can override the behavior by setting the following environment variable:
 
 ```env
+YTP_PREVENT_LIVE_PREMIERE=true
 YTP_LIVE_PREMIERE_BUFFER=10
 ```
 
 Where `YTP_LIVE_PREMIERE_BUFFER` is the buffer time in minutes to add to the video duration before the download starts. 
 This will help in case the premiere has a longer loading screen than usual.
 
-# How to bypass CF challenges?
-
-You need to setup [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) and then set the `YTP_FLARESOLVERR_URL` 
-environment variable to point to your FlareSolverr instance. For example:
-
-```yaml
-services:
-  ytptube:
-    user: "${UID:-1000}:${UID:-1000}" # change this to your user id and group id, for example: "1000:1000"
-    image: ghcr.io/arabcoders/ytptube:latest
-    container_name: ytptube
-    restart: unless-stopped
-    environment:
-      - YTP_FLARESOLVERR_URL=http://flaresolverr:8191/v1
-    ports:
-      - "8081:8081"
-    volumes:
-      - ./config:/config:rw
-      - ./downloads:/downloads:rw
-    tmpfs:
-      - /tmp
-    depends_on:
-      - flaresolverr
-  flaresolverr:
-    image: flaresolverr/flaresolverr:latest
-    container_name: flaresolverr
-    restart: unless-stopped    
-```
-
-For more information please visit [FlareSolverr](https://github.com/FlareSolverr/FlareSolverr) project.
-
-# How to use the browser extractor?
-
-YTPTube ships with a bundled `browser` extractor plugin for `yt-dlp`. It opens the target page in a remote browser,
-waits for the page network activity, then tries to extract media urls from the captured requests and media elements.
-
-This is mainly useful for sites where the regular extractor or generic page parsing does not expose the final media url,
-but a real browser session does.
-
-## Environment variables
-
-You can define the remote browser endpoint globally with the following environment variable.
-
-### Selenium example
-
-```env
-YTP_BROWSER_URL=selenium+http://selenium:4444/wd/hub
-```
-
-### Playwright example
-
-For a native Playwright server, point to the Playwright websocket endpoint:
-
-```env
-YTP_BROWSER_URL=playwright+ws://playwright:3000/
-```
-
-### Playwright CDP example
-
-To connect Playwright over the Chrome DevTools Protocol, use either the shorthand `playwright+cdp://` form or an explicit transport form:
-
-```env
-YTP_BROWSER_URL=playwright+cdp://chrome:9222/
-# same as playwright+cdp+http://chrome:9222/
-```
-
-- `YTP_BROWSER_URL` is the full backend selector and endpoint in one value.
-- Supported forms are:
-  - `selenium+http://...`
-  - `selenium+https://...`
-  - `playwright+ws://...`
-  - `playwright+wss://...`
-  - `playwright+cdp://...` which is treated as `playwright+cdp+http://...`
-  - `playwright+cdp+http://...`
-  - `playwright+cdp+https://...`
-  - `playwright+cdp+ws://...`
-  - `playwright+cdp+wss://...`
-
-## yt-dlp usage
-
-If you want to set the browser extractor options directly on the yt-dlp side, you can also use `--extractor-args` with `generic:url=...`:
-
-### Selenium example
-
-```bash
---use-extractors "generic" --extractor-args "generic:url=selenium+http://selenium:4444/wd/hub"
-```
-
-### Playwright example
-
-```bash
---use-extractors "generic" --extractor-args "generic:url=playwright+ws://playwright:3000/"
-```
-
-### Playwright CDP example
-
-```bash
---use-extractors "generic" --extractor-args "generic:url=playwright+cdp://chrome:9222/"
-```
-
-The explicit `--extractor-args` value takes priority over `YTP_BROWSER_URL`.
-
-## Example compose setup
-
-```yaml
-services:
-  ytptube:
-    user: "${UID:-1000}:${UID:-1000}"
-    image: ghcr.io/arabcoders/ytptube:latest
-    container_name: ytptube
-    restart: unless-stopped
-    environment:
-      - YTP_BROWSER_URL=selenium+http://selenium:4444/wd/hub # or playwright+ws://playwright:3000/ or playwright+cdp://chrome:9222/
-    ports:
-      - "8081:8081"
-    volumes:
-      - ./config:/config:rw
-      - ./downloads:/downloads:rw
-
-  selenium:
-    image: selenium/standalone-chrome:latest
-    container_name: selenium
-    restart: unless-stopped
-    shm_size: 2gb
-    
-  playwright:
-    image: mcr.microsoft.com/playwright:v1.59.0-noble
-    container_name: playwright
-    restart: unless-stopped
-    command: /bin/sh -c "npx -y playwright@1.59.0 run-server --port 3000 --host 0.0.0.0"
-```
-
-> [!NOTE]
-> The browser extractor is slower than the normal extractor flow and should only be used when a site actually needs a real browser session.
-> playwright require same version for both the server and the client, so make sure to use the same version in the container and in your local environment if you want to test it locally.

README.md

@@ -1,9 +1,8 @@
 # YTPTube
 
-![Build Status](https://github.com/arabcoders/ytptube/actions/workflows/main.yml/badge.svg)
+![Build Status](https://github.com/ArabCoders/ytptube/actions/workflows/main.yml/badge.svg)
 ![MIT License](https://img.shields.io/github/license/arabcoders/ytptube.svg)
-![Docker Pull](https://img.shields.io/docker/pulls/arabcoders/ytptube.svg)
-![gchr Pull](https://ghcr-badge.elias.eu.org/shield/arabcoders/ytptube/ytptube)
+![Docker pull](https://ghcr-badge.elias.eu.org/shield/arabcoders/ytptube/ytptube)
 
 **YTPTube** is a web-based GUI for [yt-dlp](https://github.com/yt-dlp/yt-dlp), designed to make downloading videos from 
 video platforms easier and user-friendly. It supports downloading playlists, channels, live streams and 
@@ -33,40 +32,29 @@ Example of the Simple mode interface.
 * Basic authentication support.
 * Supports `curl-cffi`. See [yt-dlp documentation](https://github.com/yt-dlp/yt-dlp?tab=readme-ov-file#impersonation). `In docker only`.
 * Bundled `pot provider plugin`. See [yt-dlp documentation](https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide). `In docker only`.
-* Support using [flaresolverr/flaresolverr](https://github.com/flaresolverr/flaresolverr) to bypass Cloudflare protections for yt-dlp and internal http client. See [related FAQ](FAQ.md#how-to-bypass-cf-challenges).
 * Automatic updates for `yt-dlp` and custom `pip` packages. `In docker only`.
 * Conditions feature to apply custom options based on `yt-dlp` returned info.
 * Custom browser extensions, bookmarklets and iOS shortcuts to send links to YTPTube instance.
 * A bundled executable version for Windows, macOS and Linux. `MacOS version is untested`.
-* Use playwright or selenium for extractors that require a browser. see [related FAQ](FAQ.md#how-to-use-the-browser-extractor).
 
 Please read the [FAQ](FAQ.md) for more information.
 
 # Installation
 
-> [!IMPORTANT]
-> By default YTPTube runs without authentication. If you expose it to the internet, **enable auth**. See [security recommendations](FAQ.md#security-recommendations).
-
 ## Run using docker command
 
 ```bash
-mkdir -p ./{config,downloads/{files,tmp}} && docker run -itd --rm --user "${UID}:${UID}" --name ytptube \
--e YTP_TEMP_PATH=/downloads/tmp -e YTP_DOWNLOAD_PATH=/downloads/files \
+mkdir -p ./{config,downloads} && docker run -d --rm --user "${UID}:${UID}" --name ytptube \
 -p 8081:8081 -v ./config:/config:rw -v ./downloads:/downloads:rw \
 ghcr.io/arabcoders/ytptube:latest
 ```
 
-## Run using podman
-
-```bash
-mkdir -p ./{config,downloads/{files,tmp}} && podman run -itd --rm --userns=keep-id --name ytptube \
--e YTP_TEMP_PATH=/downloads/tmp -e YTP_DOWNLOAD_PATH=/downloads/files \
--p 8081:8081 -v ./config:/config:rw -v ./downloads:/downloads:rw \
-arabcoders/ytptube:latest
-```
-
 Then you can access the WebUI at `http://localhost:8081`.
 
+> [!NOTE]
+> If you are using `podman` instead of `docker`, you can use the same command, but you need to change the user to `0:0`
+> it will appears to be running as root, but it will run as the user who started the container.
+
 ## Using compose file
 
 The following is an example of a `compose.yaml` file that can be used to run YTPTube.
@@ -74,31 +62,33 @@ The following is an example of a `compose.yaml` file that can be used to run YTP
 ```yaml
 services:
   ytptube:
-    user: "${UID:-1000}:${UID:-1000}" # change this to your user id and group id.
-    # comment out the above line and uncomment the below line if you are using podman-compose.
-    #userns_mode: keep-id
+    user: "${UID:-1000}:${UID:-1000}" # change this to your user id and group id, for example: "1000:1000"
     image: ghcr.io/arabcoders/ytptube:latest
     container_name: ytptube
     restart: unless-stopped
-    environment:
-      - YTP_TEMP_PATH=/downloads/tmp
-      - YTP_DOWNLOAD_PATH=/downloads/files
     ports:
       - "8081:8081"
     volumes:
       - ./config:/config:rw
       - ./downloads:/downloads:rw
+    tmpfs:
+      - /tmp
 ```
 
 > [!IMPORTANT]
-> Make sure to change the `user` line to match your user id and group id in docker setups, or use `userns_mode: keep-id` in podman setups.
+> Make sure to change the `user` line to match your user id and group id
+> If you have low RAM, remove the `tmpfs` and mount a disk-based directory to `/tmp` instead. See [FAQ](FAQ.md#getting-no-space-left-on-device-error) for more information.
 
 ```bash
-mkdir -p ./{config,downloads/{files,tmp}} && docker compose -f compose.yaml up -d
+mkdir -p ./{config,downloads} && docker compose -f compose.yaml up -d
 ```
 
 Then you can access the WebUI at `http://localhost:8081`.
 
+> [!NOTE]
+> you can use podman-compose instead of docker-compose, as it supports the same syntax. However, you should change the 
+> user to `0:0` it will appears to be running as root, but it will run as the user who started the container.
+
 ## Unraid
 
 For `Unraid` users You can install the `Community Applications` plugin, and search for **ytptube** it comes 
@@ -112,14 +102,15 @@ For simple API documentation, you can refer to the [API documentation](API.md).
 
 This project is not affiliated with yt-dlp or any other service.
 
-This is a personal project designed to make downloading videos from the internet more convenient for me. It is not 
-intended for piracy or any unlawful use. This project was built primarily for my own use and preferences.
+It’s a personal project designed to make downloading videos from the internet more convenient. It’s not intended for 
+piracy or any unlawful use.
 
-AI-assisted tools are used in this project. If you are uncomfortable with this, you should not use this project.
+This project was built primarily for my own needs and preferences. The UI might not be the most polished or visually 
+refined, but I’m happy with it as it is. You can, however, create and load your own UI for complete customization. I 
+plan to refactor the UI/UX in the future using [Nuxt/ui](https://ui.nuxt.com/).
 
-Contributions are welcome, but I may decline changes that do not interest me or do not align with my vision for this 
-project. Unsolicited pull requests will be closed. For suggestions or feature requests, please open a discussion or 
-join the Discord server.
+Contributions are welcome, but I may decline changes that don’t align with my vision for the project. Unsolicited pull 
+requests may be ignored. For suggestions or feature requests, please open a discussion or join the Discord server.
 
 # Social contact
 

app.spec

@@ -13,6 +13,10 @@ MANUAL_MAP = {
 
 
 def top_level_modules(dist_name: str) -> list[str]:
+    """
+    Resolve distribution name -> importable top-level modules.
+    Honors MANUAL_MAP first; falls back to metadata or normalized name.
+    """
     manual: list[str] | None = MANUAL_MAP.get(dist_name) or MANUAL_MAP.get(dist_name.replace("-", "_"))
     if manual:
         return manual
@@ -20,7 +24,7 @@ def top_level_modules(dist_name: str) -> list[str]:
     try:
         dist = importlib.metadata.distribution(dist_name)
 
-        top_level: list[str] = []
+        top_level = []
         for f in dist.files or []:
             if f.name == "top_level.txt":
                 txt = (dist.locate_file(f)).read_text().splitlines()
@@ -40,7 +44,7 @@ def top_level_modules(dist_name: str) -> list[str]:
     return [dist_name.replace("-", "_")]
 
 
-def parse_pyproject(path: str = "pyproject.toml") -> set[str]:
+def parse_pyproject(path="pyproject.toml") -> set[str]:
     with open(path, "rb") as f:
         data = tomllib.load(f)
 
@@ -48,11 +52,12 @@ def parse_pyproject(path: str = "pyproject.toml") -> set[str]:
     for extra in data["project"].get("optional-dependencies", {}).values():
         reqs.update(extra)
 
+    # Strip env markers and versions
     return {re.split(r"[ ;<>=]", r, 1)[0] for r in reqs}  # noqa: B034
 
 
 dist_names = parse_pyproject()
-hidden: list[str] = []
+hidden = []
 
 for dist in dist_names:
     if sys.platform != "win32" and dist in ("python-magic-bin", "tzdata"):
@@ -64,13 +69,14 @@ for dist in dist_names:
 hidden += [
     "engineio.async_drivers.aiohttp",
     "socketio.async_drivers.aiohttp",
-    "socketio",  # python-socketio top-level
-    "engineio",
-    "aiohttp",
-    "dotenv",
     "app",
+    "dotenv"
+    "socketio",
+    "aiohttp",
+    "engineio"
 ]
 
+# Deduplicate
 hidden = sorted(set(hidden))
 
 a = Analysis(  # noqa: F821 # type: ignore
@@ -84,29 +90,23 @@ a = Analysis(  # noqa: F821 # type: ignore
     hiddenimports=hidden,
     hookspath=[],
     runtime_hooks=[],
-    excludes=[],  # do NOT exclude libstdc++.so.6
+    excludes=["libstdc++.so.6"],
     cipher=block_cipher,
 )
 
 pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)  # type: ignore # noqa: F821
 
-exe = EXE(  # noqa: F821 # type: ignore
+exe = EXE(  # type: ignore # noqa: F821
     pyz,
     a.scripts,
-    name="YTPTube",
-    debug=False,
-    strip=False,
-    console=True,
-    icon="ui/public/favicon.ico",
-    exclude_binaries=True,
-)
-
-coll = COLLECT(  # noqa: F821 # type: ignore
-    exe,
     a.binaries,
     a.zipfiles,
     a.datas,
-    strip=False,
-    upx=False,
     name="YTPTube",
+    debug=False,
+    strip=False,
+    upx=True,
+    console=True,
+    icon="ui/public/favicon.ico",
+    onefile=True,
 )

app/conftest.py

@@ -1,25 +0,0 @@
-from __future__ import annotations
-
-import os
-import tempfile
-
-from app.tests.helpers import cleanup_test_run_root, get_test_run_root, get_test_system_temp_root
-
-
-def pytest_configure(config) -> None:
-    temp_root = get_test_system_temp_root()
-    for env_name in ("TMPDIR", "TEMP", "TMP"):
-        os.environ[env_name] = str(temp_root)
-
-    tempfile.tempdir = None
-
-    if getattr(config.option, "basetemp", None) is None:
-        config.option.basetemp = str(get_test_run_root() / "pytest")
-
-    os.environ["YTP_FILE_LOGGING"] = "false"
-
-
-def pytest_unconfigure(config) -> None:
-    del config
-    os.environ.pop("YTP_FILE_LOGGING", None)
-    cleanup_test_run_root()

app/features/conditions/__init__.py

@@ -1 +0,0 @@
-"""Conditions Feature"""

app/features/conditions/deps.py

@@ -1,5 +0,0 @@
-from app.features.conditions.repository import ConditionsRepository
-
-
-def get_conditions_repo() -> ConditionsRepository:
-    return ConditionsRepository.get_instance()

app/features/conditions/migration.py

@@ -1,118 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
-
-from app.features.conditions.models import ConditionModel
-from app.features.core.migration import Migration as FeatureMigration
-from app.library.config import Config
-from app.library.log import get_logger
-
-if TYPE_CHECKING:
-    from app.features.conditions.repository import ConditionsRepository
-
-LOG = get_logger()
-
-
-class Migration(FeatureMigration):
-    name: str = "conditions"
-
-    def __init__(self, repo: ConditionsRepository, config: Config | None = None):
-        self._config: Config = config or Config.get_instance()
-        super().__init__(config=self._config)
-        self._repo: ConditionsRepository = repo
-        self._source_file: Path = Path(self._config.config_path) / "conditions.json"
-
-    async def should_run(self) -> bool:
-        return self._source_file.exists()
-
-    async def migrate(self) -> None:
-        if await self._repo.count() > 0:
-            LOG.warning("Conditions already exist in the database; skipping migration.")
-            await self._move_file(self._source_file)
-            return
-
-        try:
-            items: list[dict] | None = json.loads(self._source_file.read_text())
-        except Exception as exc:
-            LOG.exception(
-                "Failed to read conditions migration file '%s'. Ignoring.",
-                self._source_file,
-                extra={"file_path": str(self._source_file), "exception_type": type(exc).__name__},
-            )
-            await self._move_file(self._source_file)
-            return
-
-        if items is None:
-            LOG.warning("No conditions found in %s; skipping migration.", self._source_file)
-            await self._move_file(self._source_file)
-            return
-
-        inserted = 0
-        seen_names: dict[str, int] = {}
-        for index, item in enumerate(items):
-            if not (normalized := await self._normalize(item, index, seen_names)):
-                continue
-            try:
-                await self._repo.create(normalized)
-                inserted += 1
-            except Exception as exc:
-                LOG.exception(
-                    "Failed to insert condition '%s'.",
-                    normalized.name,
-                    extra={"condition_name": normalized.name, "exception_type": type(exc).__name__},
-                )
-
-        LOG.info("Migrated %s condition(s) from %s.", inserted, self._source_file)
-        await self._move_file(self._source_file)
-
-    async def _normalize(self, item: Any, index: int, seen_names: dict[str, int]) -> ConditionModel | None:
-        if not isinstance(item, dict):
-            LOG.warning("Skipping condition at index %s due to invalid type.", index)
-            return None
-
-        assert isinstance(item, dict)
-        name: str | None = item.get("name")
-        if not name or not isinstance(name, str):
-            LOG.warning("Skipping condition at index %s due to missing name.", index)
-            return None
-
-        normalized_name = name.strip()
-        if not normalized_name:
-            LOG.warning("Skipping condition at index %s due to empty name.", index)
-            return None
-
-        name = self._unique_name(normalized_name, seen_names)
-
-        extras = item.get("extras") if isinstance(item.get("extras"), dict) else {}
-        extras = cast("dict[str, Any]", extras)
-        filter_value: str | None = item.get("filter")
-        if (not filter_value or not isinstance(filter_value, str)) and len(extras) == 0:
-            LOG.warning("Skipping condition '%s' due to missing filter.", name)
-            return None
-
-        cli: str | None = item.get("cli")
-        if not isinstance(cli, str):
-            cli = ""
-
-        enabled_value = item.get("enabled")
-        enabled: bool = enabled_value if isinstance(enabled_value, bool) else True
-        priority_value = item.get("priority")
-        priority: int = priority_value if isinstance(priority_value, int) else 0
-        if isinstance(priority, bool) or 0 > priority:
-            priority = 0
-
-        description_value = item.get("description")
-        description: str = description_value if isinstance(description_value, str) else ""
-
-        return ConditionModel(
-            id=index,
-            name=name,
-            filter=filter_value,
-            cli=cli,
-            extras=extras,
-            enabled=bool(enabled),
-            priority=priority,
-            description=description,
-        )

app/features/conditions/models.py

@@ -1,28 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime  # noqa: TC003
-
-from sqlalchemy import JSON, Boolean, Index, Integer, String, Text
-from sqlalchemy.orm import Mapped, mapped_column
-
-from app.features.core.models import Base, UTCDateTime, utcnow
-
-
-class ConditionModel(Base):
-    __tablename__: str = "conditions"
-    __table_args__: tuple[Index, ...] = (
-        Index("ix_conditions_name", "name"),
-        Index("ix_conditions_enabled", "enabled"),
-        Index("ix_conditions_priority", "priority"),
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    filter: Mapped[str] = mapped_column(Text, nullable=False)
-    cli: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
-    priority: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
-    description: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    extras: Mapped[dict] = mapped_column(JSON, nullable=False, default=dict)
-    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, nullable=False)
-    updated_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, onupdate=utcnow, nullable=False)

app/features/conditions/repository.py

@@ -1,192 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from app.features.conditions.migration import Migration
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable
-    from contextlib import AbstractAsyncContextManager
-
-    from sqlalchemy.engine.result import Result
-    from sqlalchemy.ext.asyncio import AsyncSession
-    from sqlalchemy.sql.elements import ColumnElement
-    from sqlalchemy.sql.selectable import Select
-
-    SessionFactory = Callable[[], AbstractAsyncContextManager[AsyncSession]]
-
-from sqlalchemy import delete, func, or_, select
-
-from app.features.conditions.models import ConditionModel
-from app.features.core.deps import get_session
-from app.library.log import get_logger
-
-LOG = get_logger()
-
-
-def _model_from_payload(payload: dict[str, Any]) -> ConditionModel:
-    model = ConditionModel()
-    for key, value in payload.items():
-        if not hasattr(model, key):
-            msg = f"'{key}' is an invalid keyword argument for ConditionModel"
-            raise TypeError(msg)
-        setattr(model, key, value)
-    return model
-
-
-def _coerce_model(payload: ConditionModel | dict[str, Any]) -> ConditionModel:
-    if isinstance(payload, ConditionModel):
-        return payload
-    return _model_from_payload(payload)
-
-
-class ConditionsRepository(metaclass=Singleton):
-    def __init__(self, session: SessionFactory | None = None) -> None:
-        self._migrated = False
-        self.session: SessionFactory = session or get_session
-
-    async def run_migrations(self) -> None:
-        if self._migrated:
-            return
-
-        self._migrated = True
-        await Migration(repo=self, config=None).run()
-
-    @staticmethod
-    def get_instance() -> ConditionsRepository:
-        return ConditionsRepository()
-
-    async def all(self) -> list[ConditionModel]:
-        async with self.session() as session:
-            result: Result[tuple[ConditionModel]] = await session.execute(
-                select(ConditionModel).order_by(ConditionModel.priority.desc(), ConditionModel.name.asc())
-            )
-            return list(result.scalars().all())
-
-    async def list_paginated(self, page: int, per_page: int) -> tuple[list[ConditionModel], int, int, int]:
-        async with self.session() as session:
-            total: int = await self.count()
-            total_pages: int = (total + per_page - 1) // per_page if total > 0 else 1
-
-            if page > total_pages and total > 0:
-                page = total_pages
-
-            query: Select[tuple[ConditionModel]] = (
-                select(ConditionModel)
-                .order_by(ConditionModel.priority.desc(), ConditionModel.name.asc())
-                .limit(per_page)
-                .offset((page - 1) * per_page)
-            )
-            result: Result[tuple[ConditionModel]] = await session.execute(query)
-            return list(result.scalars().all()), total, page, total_pages
-
-    async def count(self) -> int:
-        async with self.session() as session:
-            result: Result[tuple[int]] = await session.execute(select(func.count()).select_from(ConditionModel))
-            return int(result.scalar_one())
-
-    async def get(self, identifier: int | str) -> ConditionModel | None:
-        async with self.session() as session:
-            if not identifier:
-                return None
-
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = ConditionModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause: ColumnElement[bool] = or_(
-                    ConditionModel.id == int(identifier), ConditionModel.name == identifier
-                )
-            else:
-                clause: ColumnElement[bool] = ConditionModel.name == identifier
-
-            result: Result[tuple[ConditionModel]] = await session.execute(select(ConditionModel).where(clause).limit(1))
-            return result.scalar_one_or_none()
-
-    async def get_by_name(self, name: str, exclude_id: int | None = None) -> ConditionModel | None:
-        async with self.session() as session:
-            query: Select[tuple[ConditionModel]] = select(ConditionModel).where(ConditionModel.name == name)
-            if exclude_id is not None:
-                query = query.where(ConditionModel.id != exclude_id)
-
-            result: Result[tuple[ConditionModel]] = await session.execute(query.limit(1))
-            return result.scalar_one_or_none()
-
-    async def create(self, payload: ConditionModel | dict[str, Any]) -> ConditionModel:
-        async with self.session() as session:
-            model = _coerce_model(payload)
-            if model.id is not None:
-                model.id = None  # ty: ignore
-
-            if await self.get_by_name(name=model.name) is not None:
-                msg: str = f"Condition with name '{model.name}' already exists."
-                raise ValueError(msg)
-
-            session.add(model)
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def update(self, identifier: int | str, payload: dict[str, Any]) -> ConditionModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = ConditionModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause: ColumnElement[bool] = or_(
-                    ConditionModel.id == int(identifier), ConditionModel.name == identifier
-                )
-            else:
-                clause: ColumnElement[bool] = ConditionModel.name == identifier
-
-            result: Result[tuple[ConditionModel]] = await session.execute(select(ConditionModel).where(clause).limit(1))
-            if not (model := result.scalar_one_or_none()):
-                msg: str = f"Condition '{identifier}' not found."
-                raise KeyError(msg)
-
-            payload.pop("id", None)
-            payload.pop("created_at", None)
-            payload.pop("updated_at", None)
-
-            if "name" in payload and await self.get_by_name(name=payload["name"], exclude_id=model.id) is not None:
-                msg: str = f"Condition with name '{payload['name']}' already exists."
-                raise ValueError(msg)
-
-            for key, value in payload.items():
-                if hasattr(model, key):
-                    setattr(model, key, value)
-
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def delete(self, identifier: int | str) -> ConditionModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = ConditionModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause: ColumnElement[bool] = or_(
-                    ConditionModel.id == int(identifier), ConditionModel.name == identifier
-                )
-            else:
-                clause: ColumnElement[bool] = ConditionModel.name == identifier
-
-            result: Result[tuple[ConditionModel]] = await session.execute(select(ConditionModel).where(clause).limit(1))
-            if not (model := result.scalar_one_or_none()):
-                msg: str = f"Condition '{identifier}' not found."
-                raise KeyError(msg)
-
-            await session.delete(model)
-            await session.commit()
-            return model
-
-    async def replace_all(self, items: Iterable[dict[str, Any] | ConditionModel]) -> list[ConditionModel]:
-        async with self.session() as session:
-            try:
-                await session.execute(delete(ConditionModel))
-                models: list[ConditionModel] = [_coerce_model(item) for item in items]
-                session.add_all(models)
-                await session.commit()
-            except Exception:
-                await session.rollback()
-                raise
-            return models

app/features/conditions/router.py

@@ -1,361 +0,0 @@
-import asyncio
-from collections import OrderedDict
-from typing import Any
-
-from aiohttp import web
-from aiohttp.web import Request, Response
-from pydantic import ValidationError
-
-from app.features.conditions.schemas import Condition, ConditionList, ConditionPatch
-from app.features.conditions.service import Conditions
-from app.features.core.schemas import CEAction, CEFeature, ConfigEvent, Pagination
-from app.features.core.utils import build_pagination, format_validation_errors, normalize_pagination
-from app.library.cache import Cache
-from app.library.config import Config
-from app.library.encoder import Encoder
-from app.library.Events import EventBus, Events
-from app.library.log import get_logger
-from app.library.router import route
-from app.library.Utils import validate_url
-
-LOG = get_logger()
-
-
-def _model(model: Any) -> Condition:
-    return Condition.model_validate(model)
-
-
-def _serialize(model: Any) -> dict:
-    return _model(model).model_dump()
-
-
-@route("GET", "api/conditions/", name="conditions_list")
-async def conditions_list(request: Request, encoder: Encoder) -> Response:
-    """
-    Get the conditions
-
-    Args:
-        request (Request): The request object.
-        encoder (Encoder): The encoder instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    repo = Conditions.get_instance()._repo
-
-    page, per_page = normalize_pagination(request)
-    items, total, current_page, total_pages = await repo.list_paginated(page, per_page)
-    return web.json_response(
-        data=ConditionList(
-            items=[_model(model) for model in items],
-            pagination=Pagination.model_validate(build_pagination(total, current_page, per_page, total_pages)),
-        ),
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("POST", "api/conditions/test/", name="condition_test")
-async def conditions_test(request: Request, encoder: Encoder, cache: Cache, config: Config) -> Response:
-    """
-    Test condition against URL.
-
-    Args:
-        request (Request): The request object.
-        encoder (Encoder): The encoder instance.
-        cache (Cache): The cache instance.
-        config (Config): The configuration instance.
-
-    Returns:
-        Response: The response object
-
-    """
-    params = await request.json()
-
-    if not isinstance(params, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if not (url := params.get("url")):
-        return web.json_response({"error": "url is required."}, status=web.HTTPBadRequest.status_code)
-
-    if not (cond := params.get("condition")):
-        return web.json_response({"error": "condition is required."}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        await asyncio.to_thread(validate_url, url, config.allow_internal_urls)
-    except ValueError as e:
-        return web.json_response({"error": str(e)}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        preset: str = params.get("preset", config.default_preset)
-        key: str = cache.hash(url + str(preset))
-        if not cache.has(key):
-            from app.features.ytdlp.extractor import fetch_info
-            from app.features.ytdlp.ytdlp_opts import YTDLPOpts
-
-            (data, _) = await fetch_info(
-                config=YTDLPOpts.get_instance().preset(name=preset).get_all(),
-                url=url,
-                debug=False,
-                no_archive=True,
-                follow_redirect=True,
-                sanitize_info=True,
-            )
-
-            if not data:
-                return web.json_response(
-                    data={"error": f"Failed to extract info from '{url!s}'."},
-                    status=web.HTTPBadRequest.status_code,
-                )
-            cache.set(key=key, value=data, ttl=600)
-        else:
-            data = cache.get(key)
-    except Exception as e:
-        LOG.exception(
-            "Failed to extract video info for condition check '%s'.",
-            cond,
-            extra={
-                "route": "conditions.match",
-                "condition": cond,
-                "url": url,
-                "preset": preset,
-                "exception_type": type(e).__name__,
-            },
-        )
-        return web.json_response(
-            data={"error": f"Failed to extract video info. '{e!s}'"},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            data={"error": "Failed to extract video info."},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-    try:
-        from app.features.ytdlp.mini_filter import match_str
-
-        status: bool = match_str(cond, data)
-    except Exception as e:
-        LOG.exception(
-            "Failed to evaluate condition '%s'.",
-            cond,
-            extra={
-                "route": "conditions.match",
-                "condition": cond,
-                "url": url,
-                "preset": preset,
-                "exception_type": type(e).__name__,
-            },
-        )
-        return web.json_response(
-            data={"error": str(e)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    return web.json_response(
-        data={
-            "status": status,
-            "condition": cond,
-            "data": OrderedDict(sorted(data.items(), key=lambda item: len(str(item[1])))),
-        },
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("POST", "api/conditions/", name="condition_add")
-async def conditions_add(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    """
-    Add Condition.
-
-    Args:
-        request (Request): The request object.
-        encoder (Encoder): The encoder instance.
-        notify (EventBus): The event bus instance.
-
-    Returns:
-        Response: The response object
-
-    """
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting list with dicts."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        item: Condition = Condition.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate condition.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        saved = _serialize(await Conditions.get_instance().save(item=item.model_dump()))
-    except ValueError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-
-    notify.emit(
-        Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.CONDITIONS, action=CEAction.CREATE, data=saved)
-    )
-    return web.json_response(data=saved, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("GET", r"api/conditions/{id:\d+}", name="condition_get")
-async def conditions_get(request: Request, encoder: Encoder) -> Response:
-    """
-    Get the conditions
-
-    Args:
-        request (Request): The request object.
-        encoder (Encoder): The encoder instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    if not (id := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await Conditions.get_instance().get(id)):
-        return web.json_response({"error": "Condition not found"}, status=web.HTTPNotFound.status_code)
-
-    return web.json_response(data=_serialize(model), status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("DELETE", r"api/conditions/{id:\d+}", name="condition_delete")
-async def conditions_delete(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    """
-    Delete Condition.
-
-    Args:
-        request (Request): The request object.
-        encoder (Encoder): The encoder instance.
-        notify (EventBus): The event bus instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    if not (id := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        deleted = _serialize(await Conditions.get_instance()._repo.delete(id))
-        notify.emit(
-            Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.CONDITIONS, action=CEAction.DELETE, data=deleted)
-        )
-        return web.json_response(data=deleted, status=web.HTTPOk.status_code, dumps=encoder.encode)
-    except KeyError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPNotFound.status_code)
-
-
-@route("PATCH", r"api/conditions/{id:\d+}", name="condition_patch")
-async def conditions_patch(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    """
-    Patch Condition.
-
-    Args:
-        request (Request): The request object.
-        encoder (Encoder): The encoder instance.
-        notify (EventBus): The event bus instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    if not (id := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await Conditions.get_instance().get(id)):
-        return web.json_response({"error": "Condition not found"}, status=web.HTTPNotFound.status_code)
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting list with dicts."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    service = Conditions.get_instance()
-
-    try:
-        validated = ConditionPatch.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate condition.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if validated.name and await service._repo.get_by_name(validated.name, exclude_id=model.id):
-        return web.json_response(
-            data={"error": f"Condition with name '{validated.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    updated = _serialize(await service._repo.update(model.id, validated.model_dump(exclude_unset=True)))
-    notify.emit(
-        Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.CONDITIONS, action=CEAction.UPDATE, data=updated)
-    )
-    return web.json_response(data=updated, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("PUT", r"api/conditions/{id:\d+}", name="condition_update")
-async def conditions_update(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    """
-    Update Condition.
-
-    Args:
-        request (Request): The request object.
-        encoder (Encoder): The encoder instance.
-        notify (EventBus): The event bus instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    if not (id := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await Conditions.get_instance().get(id)):
-        return web.json_response({"error": "Condition not found"}, status=web.HTTPNotFound.status_code)
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting list with dicts."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    service = Conditions.get_instance()
-
-    try:
-        validated = Condition.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate condition.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if validated.name and await service._repo.get_by_name(validated.name, exclude_id=model.id):
-        return web.json_response(
-            data={"error": f"Condition with name '{validated.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    updated = _serialize(await service._repo.update(model.id, validated.model_dump(exclude_unset=True)))
-    notify.emit(
-        Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.CONDITIONS, action=CEAction.UPDATE, data=updated)
-    )
-    return web.json_response(data=updated, status=web.HTTPOk.status_code, dumps=encoder.encode)

app/features/conditions/schemas.py

@@ -1,93 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
-
-from app.features.core.schemas import Pagination
-from app.features.core.utils import parse_int
-from app.features.ytdlp.mini_filter import match_str
-
-
-class Condition(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    id: int | None = None
-    name: str = Field(min_length=1)
-    filter: str = ""
-    cli: str = ""
-    extras: dict[str, Any] = Field(default_factory=dict)
-    enabled: bool = True
-    priority: int = 0
-    description: str = ""
-
-    @field_validator("filter")
-    @classmethod
-    def _validate_filter(cls, value: str) -> str:
-        try:
-            match_str(value, {})
-        except Exception as exc:
-            msg: str = f"Invalid filter. '{exc!s}'."
-            raise ValueError(msg) from exc
-        return value
-
-    @field_validator("cli")
-    @classmethod
-    def _validate_cli(cls, value: str) -> str:
-        if not value:
-            return ""
-        try:
-            from app.features.ytdlp.utils import arg_converter
-
-            arg_converter(args=value)
-        except ModuleNotFoundError:
-            return value
-        except Exception as exc:
-            msg: str = f"Invalid command options for yt-dlp. '{exc!s}'."
-            raise ValueError(msg) from exc
-        return value
-
-    @field_validator("priority", mode="before")
-    @classmethod
-    def _normalize_priority(cls, value: Any) -> int:
-        return parse_int(value, field="Priority", minimum=0)
-
-    @field_validator("enabled", mode="before")
-    @classmethod
-    def _validate_enabled(cls, value: Any) -> bool:
-        if not isinstance(value, bool):
-            msg: str = "Enabled must be a boolean."
-            raise ValueError(msg)
-        return value
-
-    @model_validator(mode="after")
-    def _validate_cli_or_extras(self) -> Condition:
-        if not self.cli and not self.extras:
-            msg: str = "Either cli or extras must be set."
-            raise ValueError(msg)
-        return self
-
-
-class ConditionPatch(Condition):
-    """
-    Model for patching Condition fields. All fields are optional.
-    """
-
-    name: str | None = None
-    filter: str | None = None
-    cli: str | None = None
-    extras: dict[str, Any] | None = None
-    enabled: bool | None = None
-    priority: int | None = None
-    description: str | None = None
-
-    @model_validator(mode="after")
-    def _validate_cli_or_extras(self) -> ConditionPatch:
-        return self
-
-
-class ConditionList(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    items: list[Condition] = Field(default_factory=list)
-    pagination: Pagination

app/features/conditions/service.py

@@ -1,195 +0,0 @@
-from collections.abc import Iterable
-
-from aiohttp import web
-
-from app.features.conditions.models import ConditionModel
-from app.features.conditions.repository import ConditionsRepository
-from app.features.conditions.schemas import Condition
-from app.features.ytdlp.mini_filter import match_str
-from app.library.Events import EventBus, Events
-from app.library.log import get_logger
-from app.library.Singleton import Singleton
-
-LOG = get_logger()
-
-
-def _ignored_identifiers(ignore_conditions: Iterable[str | int | float] | None) -> tuple[set[str], bool]:
-    ignored: set[str] = set()
-    ignore_all = False
-
-    if not ignore_conditions:
-        return ignored, ignore_all
-
-    for value in ignore_conditions:
-        if isinstance(value, bool) or not isinstance(value, (str, int, float)):
-            continue
-
-        identifier = str(value).strip()
-        if not identifier:
-            continue
-
-        if "*" == identifier:
-            ignore_all = True
-            continue
-
-        ignored.add(identifier)
-
-    return ignored, ignore_all
-
-
-class Conditions(metaclass=Singleton):
-    def __init__(self):
-        self._repo: ConditionsRepository = ConditionsRepository.get_instance()
-
-    @staticmethod
-    def get_instance() -> "Conditions":
-        return Conditions()
-
-    async def on_shutdown(self, _: web.Application):
-        pass
-
-    def attach(self, _: web.Application):
-        async def handle_event(_, __):
-            await self._repo.run_migrations()
-
-        EventBus.get_instance().subscribe(Events.STARTED, handle_event, "ConditionsRepository.run_migrations")
-
-    async def get_all(self) -> list[ConditionModel]:
-        return await self._repo.all()
-
-    async def save(self, item: ConditionModel | dict) -> ConditionModel:
-        """
-        Save the item.
-
-        Args:
-            item (Condition|dict): The items to save.
-
-        Returns:
-            ConditionModel: The current instance.
-
-        """
-        try:
-            if not isinstance(item, ConditionModel):
-                item: ConditionModel = ConditionModel(**item)
-        except Exception as exc:
-            msg: str = f"Failed to parse item. '{exc!s}'"
-            raise ValueError(msg) from exc
-
-        try:
-            repo = self._repo
-            if item.id is None or 0 == item.id:
-                model = await repo.create(item)
-            else:
-                model = await repo.update(item.id, Condition.model_validate(item).model_dump())
-        except KeyError as exc:
-            raise ValueError(str(exc)) from exc
-
-        return model
-
-    async def has(self, identifier: str) -> bool:
-        """
-        Check if the item exists by id or name.
-
-        Args:
-            identifier (str): The id or name of the preset.
-
-        Returns:
-            bool: True if the item exists, False otherwise.
-
-        """
-        return await self.get(identifier) is not None
-
-    async def get(self, identifier: str) -> ConditionModel | None:
-        """
-        Get the item by id or name.
-
-        Args:
-            identifier (str): The id or name of the preset.
-
-        Returns:
-            ConditionModel|None: The item if found, None otherwise.
-
-        """
-        repo = self._repo
-        return await repo.get(identifier)
-
-    async def match(
-        self, info: dict, ignore_conditions: Iterable[str | int | float] | None = None
-    ) -> ConditionModel | None:
-        """
-        Check if any condition matches the info dict.
-
-        Args:
-            info (dict): The info dict to check.
-            ignore_conditions (Iterable[str | int | float] | None): Condition ids or names to skip for this match.
-
-        Returns:
-            Condition|None: The condition if found, None otherwise.
-
-        """
-        if not info or not isinstance(info, dict) or len(info) < 1:
-            return None
-
-        ignored_identifiers, ignore_all = _ignored_identifiers(ignore_conditions)
-        if ignore_all:
-            return None
-
-        repo = self._repo
-        items: list[ConditionModel] = await repo.all()
-        if len(items) < 1:
-            return None
-
-        for item in sorted(items, key=lambda x: x.priority, reverse=True):
-            if not item.enabled:
-                continue
-
-            if str(item.id) in ignored_identifiers or item.name in ignored_identifiers:
-                continue
-
-            if not item.filter:
-                LOG.error(
-                    "Filter is empty for '%s'.", item.name, extra={"condition_id": item.id, "condition_name": item.name}
-                )
-                continue
-
-            try:
-                if not match_str(item.filter, info):
-                    continue
-
-                LOG.debug(
-                    "Matched '%s: %s' with filter '%s'.",
-                    item.id,
-                    item.name,
-                    item.filter,
-                    extra={"condition_id": item.id, "condition_name": item.name, "filter": item.filter},
-                )
-                return item
-            except Exception as e:
-                LOG.exception(
-                    "Failed to evaluate condition '%s'.",
-                    item.name,
-                    extra={"condition_id": item.id, "condition_name": item.name, "exception_type": type(e).__name__},
-                )
-                continue
-
-        return None
-
-    async def single_match(self, identifier: int | str, info: dict) -> ConditionModel | None:
-        """
-        Check if condition matches the info dict.
-
-        Args:
-            identifier (int|str): The id or name of the item.
-            info (dict): The info dict to check.
-
-        Returns:
-            ConditionModel|None: The condition if found, None otherwise.
-
-        """
-        if not info or not isinstance(info, dict) or len(info) < 1:
-            return None
-
-        if not (item := await self.get(str(identifier))) or not item.enabled or not item.filter:
-            return None
-
-        return item if match_str(item.filter, info) else None

app/features/conditions/tests/test_conditions.py

@@ -1,246 +0,0 @@
-"""Tests for ConditionsRepository."""
-
-from __future__ import annotations
-
-import pytest
-import pytest_asyncio
-from types import SimpleNamespace
-import pytest
-from typing import Any
-from aiohttp import web
-from aiohttp.test_utils import make_mocked_request
-
-from app.features.conditions.router import conditions_test
-from app.library.config import Config
-from app.library.encoder import Encoder
-from app.features.conditions.repository import ConditionsRepository
-from app.library.sqlite_store import SqliteStore
-from app.tests.helpers import make_in_memory_db_path
-
-
-@pytest_asyncio.fixture
-async def repo():
-    ConditionsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-    store = SqliteStore(db_path=make_in_memory_db_path("conditions-repository"))
-    await store.get_connection()
-
-    # Create repository
-    repository = ConditionsRepository.get_instance()
-
-    yield repository
-
-    # Cleanup - close connections properly
-    await store.close()
-
-    # Reset singletons
-    ConditionsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-
-def _json_request(path: str, payload: object) -> web.Request:
-    mock_request: Any = make_mocked_request("POST", path)
-
-    async def _json() -> object:
-        return payload
-
-    mock_request.json = _json
-    return mock_request
-
-
-class TestAllowInternalUrlsScope:
-    def setup_method(self) -> None:
-        Config._reset_singleton()
-
-    @pytest.mark.asyncio
-    async def test_rejects_internal_url(self) -> None:
-        config = Config.get_instance()
-        config.allow_internal_urls = False
-        encoder = Encoder()
-        cache = SimpleNamespace(hash=lambda value: value, has=lambda _key: False, set=lambda **_kwargs: None)
-
-        request = _json_request(
-            "/api/conditions/test/",
-            {"url": "http://127.0.0.1/test", "condition": "title", "preset": config.default_preset},
-        )
-
-        response = await conditions_test(request, encoder, cache, config)
-
-        assert response.status == web.HTTPBadRequest.status_code
-        body = response.body
-        assert isinstance(body, bytes)
-        assert b"internal urls" in body.lower()
-
-
-class TestConditionsRepository:
-    """Test suite for ConditionsRepository database operations."""
-
-    @pytest.mark.asyncio
-    async def test_create_condition(self, repo):
-        """Create condition with valid data."""
-        data = {
-            "name": "Test Condition",
-            "filter": "duration > 60",
-            "cli": "--format best",
-            "enabled": True,
-            "priority": 10,
-            "description": "Test description",
-            "extras": {"key": "value"},
-        }
-
-        model = await repo.create(data)
-
-        assert model.id is not None, "Should generate ID for new condition"
-        assert model.name == "Test Condition", "Should store name correctly"
-        assert model.filter == "duration > 60", "Should store filter correctly"
-        assert model.cli == "--format best", "Should store CLI correctly"
-        assert model.enabled is True, "Should store enabled flag correctly"
-        assert model.priority == 10, "Should store priority correctly"
-        assert model.description == "Test description", "Should store description correctly"
-        assert model.extras == {"key": "value"}, "Should store extras as dict"
-
-    @pytest.mark.asyncio
-    async def test_create_with_defaults(self, repo):
-        """Create condition with minimal data uses defaults."""
-        data = {
-            "name": "Minimal",
-            "filter": "duration > 30",
-        }
-
-        model = await repo.create(data)
-
-        assert model.cli == "", "Should default CLI to empty string"
-        assert model.enabled is True, "Should default enabled to True"
-        assert model.priority == 0, "Should default priority to 0"
-        assert model.description == "", "Should default description to empty"
-        assert model.extras == {}, "Should default extras to empty dict"
-
-    @pytest.mark.asyncio
-    async def test_get_by_id(self, repo):
-        """Get condition by integer ID."""
-        created = await repo.create({"name": "Get Test", "filter": "duration > 40"})
-
-        retrieved = await repo.get(created.id)
-
-        assert retrieved is not None, "Should retrieve created condition"
-        assert retrieved.id == created.id, "Should retrieve correct condition by ID"
-        assert retrieved.name == "Get Test", "Should match created condition name"
-
-    @pytest.mark.asyncio
-    async def test_get_by_name(self, repo):
-        """Get condition by string name."""
-        await repo.create({"name": "Named Test", "filter": "duration > 50"})
-
-        retrieved = await repo.get("Named Test")
-
-        assert retrieved is not None, "Should retrieve by name"
-        assert retrieved.name == "Named Test", "Should match condition name"
-
-    @pytest.mark.asyncio
-    async def test_get_nonexistent(self, repo):
-        """Get nonexistent condition returns None."""
-        result = await repo.get(99999)
-        assert result is None, "Should return None for nonexistent ID"
-
-        result = await repo.get("nonexistent")
-        assert result is None, "Should return None for nonexistent name"
-
-    @pytest.mark.asyncio
-    async def test_update_condition(self, repo):
-        """Update existing condition."""
-        created = await repo.create({"name": "Update Test", "filter": "duration > 60"})
-
-        updated = await repo.update(
-            created.id,
-            {
-                "name": "Updated Name",
-                "priority": 5,
-                "extras": {"updated": True},
-            },
-        )
-
-        assert updated.name == "Updated Name", "Should update name"
-        assert updated.priority == 5, "Should update priority"
-        assert updated.extras == {"updated": True}, "Should update extras"
-        assert updated.filter == "duration > 60", "Should preserve unchanged filter"
-
-    @pytest.mark.asyncio
-    async def test_update_nonexistent_raises(self, repo):
-        """Update nonexistent condition raises KeyError."""
-        with pytest.raises(KeyError, match="not found"):
-            await repo.update(99999, {"name": "Should Fail"})
-
-    @pytest.mark.asyncio
-    async def test_delete_condition(self, repo):
-        """Delete existing condition."""
-        created = await repo.create({"name": "Delete Test", "filter": "duration > 70"})
-
-        deleted = await repo.delete(created.id)
-
-        assert deleted.id == created.id, "Should return deleted condition"
-
-        result = await repo.get(created.id)
-        assert result is None, "Deleted condition should not be retrievable"
-
-    @pytest.mark.asyncio
-    async def test_delete_nonexistent_raises(self, repo):
-        """Delete nonexistent condition raises KeyError."""
-        with pytest.raises(KeyError, match="not found"):
-            await repo.delete(99999)
-
-    @pytest.mark.asyncio
-    async def test_list_paginated(self, repo):
-        """List paginated returns correct subset."""
-        for i in range(5):
-            await repo.create({"name": f"Item {i}", "filter": "duration > 10", "priority": i})
-
-        items, total, page, total_pages = await repo.list_paginated(page=1, per_page=2)
-
-        assert len(items) == 2, "Should return 2 items per page"
-        assert total == 5, "Should report total count of 5"
-        assert page == 1, "Should be on page 1"
-        assert total_pages == 3, "Should have 3 pages total"
-
-    @pytest.mark.asyncio
-    async def test_list_ordering(self, repo):
-        """List orders by priority desc then name asc."""
-        await repo.create({"name": "B", "filter": "test", "priority": 1})
-        await repo.create({"name": "A", "filter": "test", "priority": 1})
-        await repo.create({"name": "C", "filter": "test", "priority": 2})
-
-        items = await repo.all()
-
-        assert items[0].name == "C", "Highest priority should be first"
-        assert items[1].name == "A", "Same priority sorted alphabetically"
-        assert items[2].name == "B", "Same priority sorted alphabetically"
-
-    @pytest.mark.asyncio
-    async def test_get_by_name_excludes_id(self, repo):
-        """Get by name can exclude specific ID."""
-        first = await repo.create({"name": "Duplicate", "filter": "test"})
-
-        result = await repo.get_by_name("Duplicate", exclude_id=first.id)
-        assert result is None, "Should not find when excluding only match"
-
-        result = await repo.get_by_name("Duplicate", exclude_id=None)
-        assert result is not None, "Should find without exclusion"
-
-    @pytest.mark.asyncio
-    async def test_replace_all(self, repo):
-        """Replace all conditions atomically."""
-        await repo.create({"name": "Old 1", "filter": "test"})
-        await repo.create({"name": "Old 2", "filter": "test"})
-
-        new_items = [
-            {"name": "New 1", "filter": "duration > 10"},
-            {"name": "New 2", "filter": "duration > 20"},
-        ]
-
-        result = await repo.replace_all(new_items)
-
-        assert len(result) == 2, "Should create 2 new conditions"
-
-        all_items = await repo.all()
-        assert len(all_items) == 2, "Should only have new conditions"
-        assert all_items[0].name in ["New 1", "New 2"], "Should only have new items"

app/features/core/deps.py

@@ -1,12 +0,0 @@
-from collections.abc import AsyncGenerator
-from contextlib import asynccontextmanager
-
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.library.sqlite_store import SqliteStore
-
-
-@asynccontextmanager
-async def get_session() -> AsyncGenerator[AsyncSession]:
-    async with SqliteStore.get_instance().sessionmaker()() as session:
-        yield session

app/features/core/migration.py

@@ -1,71 +0,0 @@
-from __future__ import annotations
-
-import abc
-import time
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from app.library.log import get_logger
-
-if TYPE_CHECKING:
-    from app.library.config import Config
-
-LOG = get_logger()
-
-
-class Migration(abc.ABC):
-    name: str = ""
-
-    def __init__(self, config: Config):
-        self._migrated_dir: Path = Path(config.config_path) / "migrated"
-
-    async def run(self) -> bool:
-        if not await self.should_run():
-            return False
-
-        self._migrated_dir.mkdir(parents=True, exist_ok=True)
-        try:
-            await self.migrate()
-        except Exception as exc:
-            LOG.exception(
-                "Feature migration '%s' failed.",
-                self.name,
-                extra={"feature": self.name, "exception_type": type(exc).__name__},
-            )
-            return False
-
-        return True
-
-    @abc.abstractmethod
-    async def should_run(self) -> bool:
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    async def migrate(self) -> None:
-        raise NotImplementedError
-
-    async def _move_file(self, source: Path) -> Path:
-        destination: Path = self._migrated_dir / source.name
-        if destination.exists():
-            timestamp = int(time.time())
-            destination: Path = self._migrated_dir / f"{source.stem}_{timestamp}{source.suffix}"
-
-        source.rename(destination)
-        return destination
-
-    def _unique_name(self, name: str, seen_names: dict[str, int]) -> str:
-        base = name
-        count = seen_names.get(base, 0)
-        if count == 0:
-            seen_names[base] = 1
-            return base
-
-        suffix = count + 1
-        new_name = f"{base} ({suffix})"
-        while new_name in seen_names:
-            suffix += 1
-            new_name = f"{base} ({suffix})"
-
-        seen_names[base] = suffix
-        seen_names[new_name] = 1
-        return new_name

app/features/core/models.py

@@ -1,41 +0,0 @@
-from __future__ import annotations
-
-from datetime import UTC, datetime
-
-from sqlalchemy import DateTime as SQLADateTime
-from sqlalchemy import Dialect, TypeDecorator
-from sqlalchemy.orm import DeclarativeBase
-
-
-def utcnow() -> datetime:
-    """
-    Return current UTC time as timezone-aware datetime.
-
-    This is the canonical way to get current UTC time for database fields.
-    """
-    return datetime.now(tz=UTC)
-
-
-class UTCDateTime(TypeDecorator):
-    impl = SQLADateTime
-    cache_ok = True
-
-    def process_bind_param(self, value: datetime | None, dialect: Dialect) -> datetime | None:
-        """Convert datetime to UTC before storing."""
-        _ = dialect
-        if value is not None:
-            if value.tzinfo is None:
-                return value.replace(tzinfo=UTC)
-            return value.astimezone(UTC).replace(tzinfo=None)
-        return value
-
-    def process_result_value(self, value: datetime | None, dialect: Dialect) -> datetime | None:
-        """Ensure datetime is timezone-aware (UTC) when loading."""
-        _ = dialect
-        if value is not None and value.tzinfo is None:
-            return value.replace(tzinfo=UTC)
-        return value
-
-
-class Base(DeclarativeBase):
-    pass

app/features/core/schemas.py

@@ -1,44 +0,0 @@
-from __future__ import annotations
-
-from enum import Enum
-from typing import Any
-
-from pydantic import BaseModel, Field
-
-
-class Pagination(BaseModel):
-    page: int
-    per_page: int
-    total: int
-    total_pages: int
-    has_next: bool
-    has_prev: bool
-
-
-class CEFeature(str, Enum):
-    PRESETS = "presets"
-    DL_FIELDS = "dl_fields"
-    CONDITIONS = "conditions"
-    NOTIFICATIONS = "notifications"
-    TASKS = "tasks"
-    TASKS_DEFINITIONS = "tasks_definitions"
-
-    def __str__(self) -> str:
-        return self.value
-
-
-class CEAction(str, Enum):
-    CREATE = "create"
-    UPDATE = "update"
-    DELETE = "delete"
-    REPLACE = "replace"
-
-    def __str__(self) -> str:
-        return self.value
-
-
-class ConfigEvent(BaseModel):
-    feature: CEFeature
-    action: CEAction
-    data: dict[str, Any] | list[dict[str, Any]]
-    extras: dict[str, Any] = Field(default_factory=dict)

app/features/core/utils.py

@@ -1,98 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from aiohttp.web import Request
-    from pydantic import ValidationError
-
-
-def parse_int(value: Any, *, field: str, minimum: int | None = None) -> int:
-    try:
-        parsed = int(value)
-    except Exception as exc:
-        msg = f"{field} must be an integer."
-        raise ValueError(msg) from exc
-
-    if minimum is not None and parsed < minimum:
-        msg = f"{field} must be >= {minimum}."
-        raise ValueError(msg)
-
-    return parsed
-
-
-def normalize_pagination(request: Request, page: int | None = None, per_page: int | None = None) -> tuple[int, int]:
-    if page is None:
-        page = int(request.query.get("page", 1))
-
-    if per_page is None:
-        per_page = int(request.query.get("per_page", 0))
-
-    if 0 == per_page:
-        from app.library.config import Config
-
-        items_per_page: int = int(Config.get_instance().default_pagination)
-        per_page = items_per_page // 2 if items_per_page > 50 else items_per_page
-
-    if page < 1:
-        msg = "page must be >= 1."
-        raise ValueError(msg)
-
-    if per_page < 1 or per_page > 1000:
-        msg = "per_page must be between 1 and 1000."
-        raise ValueError(msg)
-
-    return int(page), int(per_page)
-
-
-def build_pagination(total: int, page: int, per_page: int, total_pages: int) -> dict:
-    return {
-        "page": page,
-        "per_page": per_page,
-        "total": total,
-        "total_pages": total_pages,
-        "has_next": page < total_pages,
-        "has_prev": page > 1,
-    }
-
-
-def format_validation_errors(exc: ValidationError) -> list[dict[str, Any]]:
-    """
-    Format Pydantic ValidationError.
-
-    Args:
-        exc: The ValidationError from Pydantic
-
-    Returns:
-        List of dicts with loc, msg, and type
-
-    """
-    return [
-        {
-            "loc": list(error.get("loc", [])),
-            "msg": error.get("msg", "Validation error"),
-            "type": error.get("type", "value_error"),
-        }
-        for error in exc.errors()
-    ]
-
-
-def gen_random(length: int = 16) -> str:
-    import secrets
-    import string
-
-    if length < 1:
-        msg = "length must be >= 1"
-        raise ValueError(msg)
-
-    middle_alphabet = string.ascii_letters + string.digits + "-_"
-    edge_alphabet = string.ascii_letters + string.digits
-
-    if 1 == length:
-        return secrets.choice(edge_alphabet)
-
-    return (
-        secrets.choice(edge_alphabet)
-        + "".join(secrets.choice(middle_alphabet) for _ in range(length - 2))
-        + secrets.choice(edge_alphabet)
-    )

app/features/dl_fields/__init__.py

@@ -1 +0,0 @@
-"""DL Fields Feature"""

app/features/dl_fields/deps.py

@@ -1,5 +0,0 @@
-from app.features.dl_fields.repository import DLFieldsRepository
-
-
-def get_dl_fields_repo() -> DLFieldsRepository:
-    return DLFieldsRepository.get_instance()

app/features/dl_fields/migration.py

@@ -1,121 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
-
-from app.features.core.migration import Migration as FeatureMigration
-from app.features.dl_fields.schemas import DLField
-from app.library.config import Config
-from app.library.log import get_logger
-
-if TYPE_CHECKING:
-    from app.features.dl_fields.repository import DLFieldsRepository
-
-LOG = get_logger()
-
-
-class Migration(FeatureMigration):
-    name: str = "dl_fields"
-
-    def __init__(self, repo: DLFieldsRepository, config: Config | None = None):
-        self._config: Config = config or Config.get_instance()
-        super().__init__(config=self._config)
-        self._repo: DLFieldsRepository = repo
-        self._source_file: Path = Path(self._config.config_path) / "dl_fields.json"
-
-    async def should_run(self) -> bool:
-        return self._source_file.exists()
-
-    async def migrate(self) -> None:
-        if await self._repo.count() > 0:
-            LOG.warning("DL fields already exist in the database; skipping migration.")
-            await self._move_file(self._source_file)
-            return
-
-        try:
-            items: list[dict[str, Any]] | None = json.loads(self._source_file.read_text())
-        except Exception as exc:
-            LOG.exception(
-                "Failed to read download fields migration file '%s'. Ignoring.",
-                self._source_file,
-                extra={"file_path": str(self._source_file), "exception_type": type(exc).__name__},
-            )
-            await self._move_file(self._source_file)
-            return
-
-        if items is None:
-            LOG.warning("No dl fields found in %s; skipping migration.", self._source_file)
-            await self._move_file(self._source_file)
-            return
-
-        inserted = 0
-        seen_names: dict[str, int] = {}
-        for index, item in enumerate(items):
-            if not (normalized := self._normalize(item, index, seen_names)):
-                continue
-            try:
-                await self._repo.create(normalized)
-                inserted += 1
-            except Exception as exc:
-                LOG.exception(
-                    "Failed to insert download field '%s'.",
-                    normalized["name"],
-                    extra={"field_name": normalized["name"], "exception_type": type(exc).__name__},
-                )
-
-        LOG.info("Migrated %s dl field(s) from %s.", inserted, self._source_file)
-        await self._move_file(self._source_file)
-
-    def _normalize(self, item: Any, index: int, seen_names: dict[str, int]) -> dict[str, Any] | None:
-        if not isinstance(item, dict):
-            LOG.warning("Skipping dl field at index %s due to invalid type.", index)
-            return None
-
-        assert isinstance(item, dict)
-
-        name: str | None = item.get("name")
-        if not name or not isinstance(name, str):
-            LOG.warning("Skipping dl field at index %s due to missing name.", index)
-            return None
-
-        normalized_name = name.strip()
-        if not normalized_name:
-            LOG.warning("Skipping dl field at index %s due to empty name.", index)
-            return None
-
-        name = self._unique_name(normalized_name, seen_names)
-        description: str = item.get("description") if isinstance(item.get("description"), str) else ""
-        field_value: str | None = item.get("field")
-        if not field_value or not isinstance(field_value, str):
-            LOG.warning("Skipping dl field '%s' due to missing field value.", name)
-            return None
-
-        kind: str = item.get("kind") if isinstance(item.get("kind"), str) else "text"
-        icon: str = item.get("icon") if isinstance(item.get("icon"), str) else ""
-        value: str = item.get("value") if isinstance(item.get("value"), str) else ""
-        extras = item.get("extras") if isinstance(item.get("extras"), dict) else {}
-        extras = cast("dict[str, Any]", extras)
-
-        order_value: int = 0
-        if isinstance(item.get("order"), int) and not isinstance(item.get("order"), bool):
-            order_value = item.get("order", 0)
-
-        payload = {
-            "name": name,
-            "description": description,
-            "field": field_value,
-            "kind": kind,
-            "icon": icon,
-            "order": order_value,
-            "value": value,
-            "extras": extras,
-        }
-
-        try:
-            DLField.model_validate(payload)
-        except Exception as exc:
-            LOG.warning("Skipping dl field '%s' due to validation error: %s", name, exc)
-            return None
-
-        return payload

app/features/dl_fields/models.py

@@ -1,29 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime  # noqa: TC003
-
-from sqlalchemy import JSON, Index, Integer, String, Text
-from sqlalchemy.orm import Mapped, mapped_column
-
-from app.features.core.models import Base, UTCDateTime, utcnow
-
-
-class DLFieldModel(Base):
-    __tablename__: str = "dl_fields"
-    __table_args__: tuple[Index, ...] = (
-        Index("ix_dl_fields_name", "name"),
-        Index("ix_dl_fields_order", "order"),
-        Index("ix_dl_fields_kind", "kind"),
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    description: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    field: Mapped[str] = mapped_column(String(255), nullable=False)
-    kind: Mapped[str] = mapped_column(String(50), nullable=False, default="text")
-    icon: Mapped[str] = mapped_column(String(255), nullable=False, default="")
-    order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
-    value: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    extras: Mapped[dict] = mapped_column(JSON, nullable=False, default=dict)
-    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, nullable=False)
-    updated_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, onupdate=utcnow, nullable=False)

app/features/dl_fields/repository.py

@@ -1,190 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any, cast
-
-from sqlalchemy import delete, func, or_, select
-
-from app.features.core.deps import get_session
-from app.features.dl_fields.migration import Migration
-from app.features.dl_fields.models import DLFieldModel
-from app.library.log import get_logger
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable
-    from contextlib import AbstractAsyncContextManager
-
-    from sqlalchemy.engine.result import Result
-    from sqlalchemy.ext.asyncio import AsyncSession
-    from sqlalchemy.sql.elements import ColumnElement
-    from sqlalchemy.sql.selectable import Select
-
-    SessionFactory = Callable[[], AbstractAsyncContextManager[AsyncSession]]
-
-LOG = get_logger()
-
-
-def _model_from_payload(payload: dict[str, Any]) -> DLFieldModel:
-    model = DLFieldModel()
-    for key, value in payload.items():
-        if not hasattr(model, key):
-            msg = f"'{key}' is an invalid keyword argument for DLFieldModel"
-            raise TypeError(msg)
-        setattr(model, key, value)
-    return model
-
-
-def _coerce_model(payload: DLFieldModel | dict[str, Any]) -> DLFieldModel:
-    if isinstance(payload, DLFieldModel):
-        return payload
-    return _model_from_payload(payload)
-
-
-class DLFieldsRepository(metaclass=Singleton):
-    def __init__(self, session: SessionFactory | None = None) -> None:
-        self._migrated = False
-        self.session: SessionFactory = session or get_session
-
-    async def run_migrations(self) -> None:
-        if self._migrated:
-            return
-
-        self._migrated = True
-        await Migration(repo=self).run()
-
-    @staticmethod
-    def get_instance() -> DLFieldsRepository:
-        return DLFieldsRepository()
-
-    async def all(self) -> list[DLFieldModel]:
-        async with self.session() as session:
-            result: Result[tuple[DLFieldModel]] = await session.execute(
-                select(DLFieldModel).order_by(DLFieldModel.order.asc(), DLFieldModel.name.asc())
-            )
-            return list(result.scalars().all())
-
-    async def list_paginated(self, page: int, per_page: int) -> tuple[list[DLFieldModel], int, int, int]:
-        async with self.session() as session:
-            total: int = await self.count()
-            total_pages: int = (total + per_page - 1) // per_page if total > 0 else 1
-
-            if page > total_pages and total > 0:
-                page = total_pages
-
-            query: Select[tuple[DLFieldModel]] = (
-                select(DLFieldModel)
-                .order_by(DLFieldModel.order.asc(), DLFieldModel.name.asc())
-                .limit(per_page)
-                .offset((page - 1) * per_page)
-            )
-            result: Result[tuple[DLFieldModel]] = await session.execute(query)
-            return list(result.scalars().all()), total, page, total_pages
-
-    async def count(self) -> int:
-        async with self.session() as session:
-            result: Result[tuple[int]] = await session.execute(select(func.count()).select_from(DLFieldModel))
-            return int(result.scalar_one())
-
-    async def get(self, identifier: int | str) -> DLFieldModel | None:
-        async with self.session() as session:
-            if not identifier:
-                return None
-
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = DLFieldModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(DLFieldModel.id == int(identifier), DLFieldModel.name == identifier)
-            else:
-                clause = DLFieldModel.name == identifier
-
-            result: Result[tuple[DLFieldModel]] = await session.execute(select(DLFieldModel).where(clause).limit(1))
-            return result.scalar_one_or_none()
-
-    async def get_by_name(self, name: str, exclude_id: int | None = None) -> DLFieldModel | None:
-        async with self.session() as session:
-            query: Select[tuple[DLFieldModel]] = select(DLFieldModel).where(DLFieldModel.name == name)
-            if exclude_id is not None:
-                query = query.where(DLFieldModel.id != exclude_id)
-
-            result: Result[tuple[DLFieldModel]] = await session.execute(query.limit(1))
-            return result.scalar_one_or_none()
-
-    async def create(self, payload: DLFieldModel | dict[str, Any]) -> DLFieldModel:
-        async with self.session() as session:
-            model = _coerce_model(payload)
-
-            if await self.get_by_name(name=model.name) is not None:
-                msg: str = f"DL field with name '{model.name}' already exists."
-                raise ValueError(msg)
-
-            session.add(model)
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def update(self, identifier: int | str, payload: dict[str, Any]) -> DLFieldModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = DLFieldModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(DLFieldModel.id == int(identifier), DLFieldModel.name == identifier)
-            else:
-                clause = DLFieldModel.name == identifier
-
-            result: Result[tuple[DLFieldModel]] = await session.execute(select(DLFieldModel).where(clause).limit(1))
-            model: DLFieldModel | None = result.scalar_one_or_none()
-
-            if not model:
-                msg: str = f"DL field '{identifier}' not found."
-                raise KeyError(msg)
-
-            payload.pop("id", None)
-
-            if "name" in payload and await self.get_by_name(name=payload["name"], exclude_id=model.id) is not None:
-                msg = f"DL field with name '{payload['name']}' already exists."
-                raise ValueError(msg)
-
-            for key, value in payload.items():
-                if hasattr(model, key):
-                    setattr(model, key, value)
-
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def delete(self, identifier: int | str) -> DLFieldModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = DLFieldModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(DLFieldModel.id == int(identifier), DLFieldModel.name == identifier)
-            else:
-                clause = DLFieldModel.name == identifier
-
-            result: Result[tuple[DLFieldModel]] = await session.execute(select(DLFieldModel).where(clause).limit(1))
-            model = result.scalar_one_or_none()
-
-            if not model:
-                msg: str = f"DL field '{identifier}' not found."
-                raise KeyError(msg)
-
-            await session.delete(model)
-            await session.commit()
-            return model
-
-    async def replace_all(self, items: Iterable[dict[str, Any] | DLFieldModel]) -> list[DLFieldModel]:
-        async with self.session() as session:
-            try:
-                await session.execute(delete(DLFieldModel))
-                models: list[DLFieldModel] = []
-                for item in items:
-                    if isinstance(item, dict):
-                        models.append(DLFieldModel(**cast("dict[str, Any]", item)))
-                    else:
-                        models.append(item)
-                session.add_all(models)
-                await session.commit()
-            except Exception:
-                await session.rollback()
-                raise
-            return models

app/features/dl_fields/router.py

@@ -1,176 +0,0 @@
-from typing import Any
-
-from aiohttp import web
-from aiohttp.web import Request, Response
-from pydantic import ValidationError
-
-from app.features.core.schemas import CEAction, CEFeature, ConfigEvent, Pagination
-from app.features.core.utils import build_pagination, format_validation_errors, normalize_pagination
-from app.features.dl_fields.schemas import DLField, DLFieldList, DLFieldPatch
-from app.features.dl_fields.service import DLFields
-from app.library.encoder import Encoder
-from app.library.Events import EventBus, Events
-from app.library.log import get_logger
-from app.library.router import route
-
-LOG = get_logger()
-
-
-def _model(model: Any) -> DLField:
-    return DLField.model_validate(model)
-
-
-def _serialize(model: Any) -> dict:
-    return _model(model).model_dump()
-
-
-@route("GET", "api/dl_fields/", "dl_fields")
-async def dl_fields_list(request: Request, encoder: Encoder) -> Response:
-    repo = DLFields.get_instance()._repo
-    page, per_page = normalize_pagination(request)
-    items, total, current_page, total_pages = await repo.list_paginated(page, per_page)
-    return web.json_response(
-        data=DLFieldList(
-            items=[_model(model) for model in items],
-            pagination=Pagination.model_validate(build_pagination(total, current_page, per_page, total_pages)),
-        ),
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("POST", "api/dl_fields/", "dl_fields_add")
-async def dl_fields_add(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        item: DLField = DLField.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate dl field.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        saved = _serialize(await DLFields.get_instance().save(item=item.model_dump()))
-    except ValueError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-
-    notify.emit(Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.DL_FIELDS, action=CEAction.CREATE, data=saved))
-
-    return web.json_response(data=saved, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("GET", r"api/dl_fields/{id:\d+}", "dl_fields_get")
-async def dl_fields_get(request: Request, encoder: Encoder) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await DLFields.get_instance().get(identifier)):
-        return web.json_response({"error": "DL field not found"}, status=web.HTTPNotFound.status_code)
-
-    return web.json_response(data=_serialize(model), status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("DELETE", r"api/dl_fields/{id:\d+}", "dl_fields_delete")
-async def dl_fields_delete(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        deleted = _serialize(await DLFields.get_instance()._repo.delete(identifier))
-        notify.emit(
-            Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.DL_FIELDS, action=CEAction.DELETE, data=deleted)
-        )
-        return web.json_response(
-            data=deleted,
-            status=web.HTTPOk.status_code,
-            dumps=encoder.encode,
-        )
-    except KeyError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPNotFound.status_code)
-
-
-@route("PATCH", r"api/dl_fields/{id:\d+}", "dl_fields_patch")
-async def dl_fields_patch(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await DLFields.get_instance().get(identifier)):
-        return web.json_response({"error": "DL field not found"}, status=web.HTTPNotFound.status_code)
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        validated = DLFieldPatch.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate dl field.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if validated.name and await DLFields.get_instance()._repo.get_by_name(validated.name, exclude_id=model.id):
-        return web.json_response(
-            data={"error": f"DL field with name '{validated.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    updated = _serialize(await DLFields.get_instance()._repo.update(model.id, validated.model_dump(exclude_unset=True)))
-    notify.emit(
-        Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.DL_FIELDS, action=CEAction.UPDATE, data=updated)
-    )
-    return web.json_response(
-        data=updated,
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("PUT", r"api/dl_fields/{id:\d+}", "dl_fields_update")
-async def dl_fields_update(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await DLFields.get_instance().get(identifier)):
-        return web.json_response({"error": "DL field not found"}, status=web.HTTPNotFound.status_code)
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        validated = DLField.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate dl field.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if validated.name and await DLFields.get_instance()._repo.get_by_name(validated.name, exclude_id=model.id):
-        return web.json_response(
-            data={"error": f"DL field with name '{validated.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    updated = _serialize(await DLFields.get_instance()._repo.update(model.id, validated.model_dump(exclude_unset=True)))
-    notify.emit(
-        Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.DL_FIELDS, action=CEAction.UPDATE, data=updated)
-    )
-
-    return web.json_response(data=updated, status=web.HTTPOk.status_code, dumps=encoder.encode)

app/features/dl_fields/schemas.py

@@ -1,101 +0,0 @@
-from __future__ import annotations
-
-from enum import Enum
-from typing import Any
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
-
-from app.features.core.schemas import Pagination
-from app.features.core.utils import parse_int
-
-
-class FieldType(str, Enum):
-    STRING = "string"
-    TEXT = "text"
-    BOOL = "bool"
-
-
-class DLField(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    id: int | None = None
-    name: str = Field(min_length=1)
-    description: str = ""
-    field: str = Field(min_length=1)
-    kind: FieldType = FieldType.TEXT
-    icon: str = ""
-    order: int = 0
-    value: str = ""
-    extras: dict[str, Any] = Field(default_factory=dict)
-
-    @field_validator("field")
-    @classmethod
-    def _validate_field(cls, value: str) -> str:
-        if not value.startswith("--"):
-            msg: str = "Field must start with '--'."
-            raise ValueError(msg)
-        if " " in value:
-            msg = "Field must not contain spaces."
-            raise ValueError(msg)
-        return value
-
-    @field_validator("order", mode="before")
-    @classmethod
-    def _normalize_order(cls, value: Any) -> int:
-        return parse_int(value, field="Order", minimum=0)
-
-    @model_validator(mode="after")
-    def _normalize_extras(self) -> DLField:
-        if not isinstance(self.extras, dict):
-            msg: str = "Extras must be a dictionary."
-            raise ValueError(msg)
-        return self
-
-
-class DLFieldPatch(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    name: str | None = None
-    description: str | None = None
-    field: str | None = None
-    kind: FieldType | None = None
-    icon: str | None = None
-    order: int | None = None
-    value: str | None = None
-    extras: dict[str, Any] | None = None
-
-    @field_validator("field")
-    @classmethod
-    def _validate_field(cls, value: str | None) -> str | None:
-        if value is None:
-            return value
-        if not value.startswith("--"):
-            msg: str = "Field must start with '--'."
-            raise ValueError(msg)
-        if " " in value:
-            msg = "Field must not contain spaces."
-            raise ValueError(msg)
-        return value
-
-    @field_validator("order", mode="before")
-    @classmethod
-    def _normalize_order(cls, value: Any) -> int | None:
-        if value is None:
-            return None
-        return parse_int(value, field="Order", minimum=0)
-
-    @model_validator(mode="after")
-    def _normalize_extras(self) -> DLFieldPatch:
-        if self.extras is None:
-            return self
-        if not isinstance(self.extras, dict):
-            msg: str = "Extras must be a dictionary."
-            raise ValueError(msg)
-        return self
-
-
-class DLFieldList(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    items: list[DLField] = Field(default_factory=list)
-    pagination: Pagination

app/features/dl_fields/service.py

@@ -1,62 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from app.features.dl_fields.models import DLFieldModel
-from app.features.dl_fields.repository import DLFieldsRepository
-from app.features.dl_fields.schemas import DLField
-from app.library.Events import EventBus, Events
-from app.library.log import get_logger
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from aiohttp import web
-
-LOG = get_logger()
-
-
-class DLFields(metaclass=Singleton):
-    def __init__(self):
-        self._repo: DLFieldsRepository = DLFieldsRepository.get_instance()
-
-    @staticmethod
-    def get_instance() -> DLFields:
-        return DLFields()
-
-    async def on_shutdown(self, _: web.Application) -> None:
-        pass
-
-    def attach(self, _: web.Application) -> None:
-        async def handle_event(_, __):
-            await self._repo.run_migrations()
-
-        EventBus.get_instance().subscribe(Events.STARTED, handle_event, "DLFieldsRepository.run_migrations")
-
-    async def get_all(self) -> list[DLFieldModel]:
-        return await self._repo.all()
-
-    async def get_all_serialized(self) -> list[dict[str, Any]]:
-        items = await self._repo.all()
-        return [DLField.model_validate(item).model_dump() for item in items]
-
-    async def save(self, item: DLField | dict) -> DLFieldModel:
-        try:
-            if not isinstance(item, DLField):
-                item = DLField.model_validate(item)
-        except Exception as exc:
-            msg: str = f"Failed to parse item. '{exc!s}'"
-            raise ValueError(msg) from exc
-
-        try:
-            repo = self._repo
-            if item.id is None or 0 == item.id:
-                model = await repo.create(item.model_dump(exclude_unset=True))
-            else:
-                model = await repo.update(item.id, item.model_dump(exclude_unset=True))
-        except KeyError as exc:
-            raise ValueError(str(exc)) from exc
-
-        return model
-
-    async def get(self, identifier: int | str) -> DLFieldModel | None:
-        return await self._repo.get(identifier)

app/features/dl_fields/tests/test_dl_fields.py

@@ -1,74 +0,0 @@
-"""Tests for dl_fields feature service."""
-
-from __future__ import annotations
-
-import pytest
-import pytest_asyncio
-
-from app.features.dl_fields.repository import DLFieldsRepository
-from app.features.dl_fields.service import DLFields
-from app.library.sqlite_store import SqliteStore
-from app.tests.helpers import make_in_memory_db_path
-
-
-@pytest_asyncio.fixture
-async def repo():
-    """Provide a fresh repository instance with initialized database for each test."""
-    DLFieldsRepository._reset_singleton()
-    DLFields._reset_singleton()
-    SqliteStore._reset_singleton()
-
-    store = SqliteStore(db_path=make_in_memory_db_path("dl-fields-service"))
-    await store.get_connection()
-
-    repository = DLFieldsRepository.get_instance()
-
-    yield repository
-
-    await store.close()
-
-    DLFieldsRepository._reset_singleton()
-    DLFields._reset_singleton()
-    SqliteStore._reset_singleton()
-
-
-class TestDLFieldsService:
-    """Test suite for DLFields service methods."""
-
-    @pytest.mark.asyncio
-    async def test_save_creates_field(self, repo):
-        """Save should create a new dl field when ID is missing."""
-        service = DLFields.get_instance()
-        payload = {
-            "name": "quality",
-            "description": "Video quality",
-            "field": "--format",
-            "kind": "string",
-            "order": 1,
-            "extras": {"options": ["best", "worst"]},
-        }
-
-        model = await service.save(payload)
-
-        assert model.id is not None, "Should create new dl field"
-        assert model.name == "quality", "Should store name correctly"
-
-    @pytest.mark.asyncio
-    async def test_get_all_serialized(self, repo):
-        """Get all serialized returns list of dictionaries."""
-        service = DLFields.get_instance()
-        await service.save(
-            {
-                "name": "audio_only",
-                "description": "Audio",
-                "field": "--extract-audio",
-                "kind": "bool",
-                "order": 2,
-            }
-        )
-
-        items = await service.get_all_serialized()
-
-        assert len(items) == 1, "Should return one dl field"
-        assert items[0]["name"] == "audio_only", "Should serialize name"
-        assert isinstance(items[0]["id"], int), "Should serialize integer ID"

app/features/dl_fields/tests/test_dl_fields_repository.py

@@ -1,248 +0,0 @@
-"""Tests for DLFieldsRepository."""
-
-from __future__ import annotations
-
-import pytest
-import pytest_asyncio
-
-from app.features.dl_fields.repository import DLFieldsRepository
-from app.library.sqlite_store import SqliteStore
-from app.tests.helpers import make_in_memory_db_path
-
-
-@pytest_asyncio.fixture
-async def repo():
-    """Provide a fresh repository instance with initialized database for each test."""
-    DLFieldsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-    store = SqliteStore(db_path=make_in_memory_db_path("dl-fields-repository"))
-    await store.get_connection()
-
-    repository = DLFieldsRepository.get_instance()
-
-    yield repository
-
-    await store.close()
-
-    DLFieldsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-
-class TestDLFieldsRepository:
-    """Test suite for DLFieldsRepository database operations."""
-
-    @pytest.mark.asyncio
-    async def test_create_field(self, repo):
-        """Create field with valid data."""
-        data = {
-            "name": "quality",
-            "description": "Video quality setting",
-            "field": "--format",
-            "kind": "string",
-            "icon": "fa-video",
-            "order": 1,
-            "value": "best",
-            "extras": {"options": ["best", "worst"]},
-        }
-
-        model = await repo.create(data)
-
-        assert model.id is not None, "Should generate ID for new field"
-        assert model.name == "quality", "Should store name correctly"
-        assert model.description == "Video quality setting", "Should store description correctly"
-        assert model.field == "--format", "Should store field correctly"
-        assert model.kind == "string", "Should store kind correctly"
-        assert model.icon == "fa-video", "Should store icon correctly"
-        assert model.order == 1, "Should store order correctly"
-        assert model.value == "best", "Should store value correctly"
-        assert model.extras == {"options": ["best", "worst"]}, "Should store extras as dict"
-
-    @pytest.mark.asyncio
-    async def test_create_with_defaults(self, repo):
-        """Create field with minimal data uses defaults."""
-        data = {
-            "name": "minimal",
-            "description": "Minimal",
-            "field": "--minimal",
-            "kind": "text",
-        }
-
-        model = await repo.create(data)
-
-        assert model.icon == "", "Should default icon to empty string"
-        assert model.order == 0, "Should default order to 0"
-        assert model.value == "", "Should default value to empty string"
-        assert model.extras == {}, "Should default extras to empty dict"
-
-    @pytest.mark.asyncio
-    async def test_get_by_id(self, repo):
-        """Get field by integer ID."""
-        created = await repo.create(
-            {
-                "name": "get_test",
-                "description": "Get test",
-                "field": "--get-test",
-                "kind": "text",
-            }
-        )
-
-        retrieved = await repo.get(created.id)
-
-        assert retrieved is not None, "Should retrieve created field"
-        assert retrieved.id == created.id, "Should retrieve correct field by ID"
-        assert retrieved.name == "get_test", "Should match created field name"
-
-    @pytest.mark.asyncio
-    async def test_get_by_name(self, repo):
-        """Get field by string name."""
-        await repo.create(
-            {
-                "name": "named_test",
-                "description": "Named test",
-                "field": "--named-test",
-                "kind": "text",
-            }
-        )
-
-        retrieved = await repo.get("named_test")
-
-        assert retrieved is not None, "Should retrieve by name"
-        assert retrieved.name == "named_test", "Should match field name"
-
-    @pytest.mark.asyncio
-    async def test_get_nonexistent(self, repo):
-        """Get nonexistent field returns None."""
-        result = await repo.get(99999)
-        assert result is None, "Should return None for nonexistent ID"
-
-        result = await repo.get("nonexistent")
-        assert result is None, "Should return None for nonexistent name"
-
-    @pytest.mark.asyncio
-    async def test_update_field(self, repo):
-        """Update existing field."""
-        created = await repo.create(
-            {
-                "name": "update_test",
-                "description": "Update test",
-                "field": "--update-test",
-                "kind": "text",
-            }
-        )
-
-        updated = await repo.update(
-            created.id,
-            {
-                "name": "updated_name",
-                "order": 5,
-                "extras": {"updated": True},
-            },
-        )
-
-        assert updated.name == "updated_name", "Should update name"
-        assert updated.order == 5, "Should update order"
-        assert updated.extras == {"updated": True}, "Should update extras"
-        assert updated.field == "--update-test", "Should preserve unchanged field"
-
-    @pytest.mark.asyncio
-    async def test_update_nonexistent_raises(self, repo):
-        """Update nonexistent field raises KeyError."""
-        with pytest.raises(KeyError, match="not found"):
-            await repo.update(99999, {"name": "should_fail"})
-
-    @pytest.mark.asyncio
-    async def test_delete_field(self, repo):
-        """Delete existing field."""
-        created = await repo.create(
-            {
-                "name": "delete_test",
-                "description": "Delete test",
-                "field": "--delete-test",
-                "kind": "text",
-            }
-        )
-
-        deleted = await repo.delete(created.id)
-
-        assert deleted.id == created.id, "Should return deleted field"
-
-        result = await repo.get(created.id)
-        assert result is None, "Deleted field should not be retrievable"
-
-    @pytest.mark.asyncio
-    async def test_delete_nonexistent_raises(self, repo):
-        """Delete nonexistent field raises KeyError."""
-        with pytest.raises(KeyError, match="not found"):
-            await repo.delete(99999)
-
-    @pytest.mark.asyncio
-    async def test_list_paginated(self, repo):
-        """List paginated returns correct subset."""
-        for i in range(5):
-            await repo.create(
-                {
-                    "name": f"item_{i}",
-                    "description": "desc",
-                    "field": f"--item-{i}",
-                    "kind": "text",
-                    "order": i,
-                }
-            )
-
-        items, total, page, total_pages = await repo.list_paginated(page=1, per_page=2)
-
-        assert len(items) == 2, "Should return 2 items per page"
-        assert total == 5, "Should report total count of 5"
-        assert page == 1, "Should be on page 1"
-        assert total_pages == 3, "Should have 3 pages total"
-
-    @pytest.mark.asyncio
-    async def test_list_ordering(self, repo):
-        """List orders by order asc then name asc."""
-        await repo.create({"name": "b", "description": "b", "field": "--b", "kind": "text", "order": 1})
-        await repo.create({"name": "a", "description": "a", "field": "--a", "kind": "text", "order": 1})
-        await repo.create({"name": "c", "description": "c", "field": "--c", "kind": "text", "order": 0})
-
-        items = await repo.all()
-
-        assert items[0].name == "c", "Lowest order should be first"
-        assert items[1].name == "a", "Same order sorted alphabetically"
-        assert items[2].name == "b", "Same order sorted alphabetically"
-
-    @pytest.mark.asyncio
-    async def test_get_by_name_excludes_id(self, repo):
-        """Get by name can exclude specific ID."""
-        first = await repo.create(
-            {
-                "name": "duplicate",
-                "description": "duplicate",
-                "field": "--duplicate",
-                "kind": "text",
-            }
-        )
-
-        result = await repo.get_by_name("duplicate", exclude_id=first.id)
-        assert result is None, "Should not find when excluding only match"
-
-        result = await repo.get_by_name("duplicate", exclude_id=None)
-        assert result is not None, "Should find without exclusion"
-
-    @pytest.mark.asyncio
-    async def test_replace_all(self, repo):
-        """Replace all fields atomically."""
-        await repo.create({"name": "old_1", "description": "old", "field": "--old-1", "kind": "text"})
-        await repo.create({"name": "old_2", "description": "old", "field": "--old-2", "kind": "text"})
-
-        new_items = [
-            {"name": "new_1", "description": "new", "field": "--new-1", "kind": "text"},
-            {"name": "new_2", "description": "new", "field": "--new-2", "kind": "text"},
-        ]
-
-        result = await repo.replace_all(new_items)
-
-        assert len(result) == 2, "Should create 2 new fields"
-
-        all_items = await repo.all()
-        assert len(all_items) == 2, "Should only have new fields"
-        assert {item.name for item in all_items} == {"new_1", "new_2"}, "Should only have new items"

app/features/notifications/deps.py

@@ -1,5 +0,0 @@
-from app.features.notifications.repository import NotificationsRepository
-
-
-def get_notifications_repo() -> NotificationsRepository:
-    return NotificationsRepository.get_instance()

app/features/notifications/migration.py

@@ -1,187 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
-
-from app.features.core.migration import Migration as FeatureMigration
-from app.features.notifications.schemas import NotificationEvents
-from app.features.presets.service import Presets
-from app.library.config import Config
-from app.library.log import get_logger
-
-if TYPE_CHECKING:
-    from app.features.notifications.repository import NotificationsRepository
-
-LOG = get_logger()
-
-
-class Migration(FeatureMigration):
-    name: str = "notifications"
-
-    def __init__(self, repo: NotificationsRepository, config: Config | None = None):
-        self._config: Config = config or Config.get_instance()
-        super().__init__(config=self._config)
-        self._repo: NotificationsRepository = repo
-        self._source_file: Path = Path(self._config.config_path) / "notifications.json"
-
-    async def should_run(self) -> bool:
-        return self._source_file.exists()
-
-    async def migrate(self) -> None:
-        if await self._repo.count() > 0:
-            LOG.warning("Notification targets already exist in the database; skipping migration.")
-            await self._move_file(self._source_file)
-            return
-
-        try:
-            items: list[dict] | None = json.loads(self._source_file.read_text())
-        except Exception as exc:
-            LOG.exception(
-                "Failed to read notifications migration file '%s'. Ignoring.",
-                self._source_file,
-                extra={"file_path": str(self._source_file), "exception_type": type(exc).__name__},
-            )
-            await self._move_file(self._source_file)
-            return
-
-        if items is None:
-            LOG.warning("No notification targets found in %s; skipping migration.", self._source_file)
-            await self._move_file(self._source_file)
-            return
-
-        inserted = 0
-        seen_names: dict[str, int] = {}
-        for index, item in enumerate(items):
-            normalized = self._normalize(item, index, seen_names)
-            if not normalized:
-                continue
-            try:
-                await self._repo.create(normalized)
-                inserted += 1
-            except Exception as exc:
-                LOG.exception(
-                    "Failed to insert notification target '%s'.",
-                    normalized.get("name"),
-                    extra={"target_name": normalized.get("name"), "exception_type": type(exc).__name__},
-                )
-
-        LOG.info("Migrated %s notification target(s) from %s.", inserted, self._source_file)
-        await self._move_file(self._source_file)
-
-    def _normalize(self, item: Any, index: int, seen_names: dict[str, int]) -> dict[str, Any] | None:
-        if not isinstance(item, dict):
-            LOG.warning("Skipping notification at index %s due to invalid type.", index)
-            return None
-
-        assert isinstance(item, dict)
-
-        name: str | None = item.get("name")
-        if not name or not isinstance(name, str):
-            LOG.warning("Skipping notification at index %s due to missing name.", index)
-            return None
-
-        normalized_name = name.strip()
-        if not normalized_name:
-            LOG.warning("Skipping notification at index %s due to empty name.", index)
-            return None
-
-        name = self._unique_name(normalized_name, seen_names)
-        request = item.get("request") if isinstance(item.get("request"), dict) else {}
-        request = cast("dict[str, Any]", request)
-        url: str | None = request.get("url")
-        if not url or not isinstance(url, str):
-            LOG.warning("Skipping notification '%s' due to missing request url.", name)
-            return None
-
-        raw_method = request.get("method")
-        method = raw_method.upper() if isinstance(raw_method, str) else "POST"
-        if method not in {"POST", "PUT"}:
-            LOG.warning("Skipping notification '%s' due to invalid method '%s'.", name, method)
-            return None
-
-        raw_type = request.get("type")
-        req_type = raw_type.lower() if isinstance(raw_type, str) else "json"
-        if req_type not in {"json", "form"}:
-            LOG.warning("Skipping notification '%s' due to invalid type '%s'.", name, req_type)
-            return None
-
-        data_key = request.get("data_key") if isinstance(request.get("data_key"), str) else "data"
-        if not data_key:
-            data_key = "data"
-
-        headers = self._normalize_headers(request.get("headers"))
-
-        enabled_value = item.get("enabled")
-        enabled: bool = enabled_value if isinstance(enabled_value, bool) else True
-        events = self._normalize_events(item.get("on"))
-        if events is None:
-            LOG.warning("Skipping notification '%s' due to invalid events.", name)
-            return None
-
-        presets = self._normalize_presets(item.get("presets"))
-        if presets is None:
-            LOG.warning("Skipping notification '%s' due to invalid presets.", name)
-            return None
-
-        return {
-            "name": name,
-            "on": events,
-            "presets": presets,
-            "enabled": enabled,
-            "request_url": url,
-            "request_method": method,
-            "request_type": req_type,
-            "request_data_key": data_key,
-            "request_headers": headers,
-        }
-
-    def _normalize_events(self, events: Any) -> list[str] | None:
-        if events is None:
-            return []
-        if not isinstance(events, list):
-            return []
-
-        allowed = set(NotificationEvents.get_events().values())
-        valid = [event for event in events if event in allowed]
-        invalid = [event for event in events if event not in allowed]
-
-        if len(invalid) > 0 and len(valid) < 1:
-            return None
-
-        if len(invalid) > 0:
-            LOG.warning("Dropping invalid notification events: %s", ", ".join(invalid))
-
-        return valid
-
-    def _normalize_presets(self, presets: Any) -> list[str] | None:
-        if presets is None:
-            return []
-        if not isinstance(presets, list):
-            return []
-
-        allowed = {preset.name for preset in Presets.get_instance().get_all()}
-        valid = [preset for preset in presets if preset in allowed]
-        invalid = [preset for preset in presets if preset not in allowed]
-
-        if len(invalid) > 0 and len(valid) < 1:
-            return None
-
-        if len(invalid) > 0:
-            LOG.warning("Dropping invalid notification presets: %s", ", ".join(invalid))
-
-        return valid
-
-    def _normalize_headers(self, headers: Any) -> list[dict[str, str]]:
-        if not isinstance(headers, list):
-            return []
-
-        normalized: list[dict[str, str]] = []
-        for header in headers:
-            if not isinstance(header, dict):
-                continue
-            key = str(header.get("key", "")).strip()
-            value = str(header.get("value", "")).strip()
-            if key and value:
-                normalized.append({"key": key, "value": value})
-        return normalized

app/features/notifications/models.py

@@ -1,39 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime  # noqa: TC003
-
-from sqlalchemy import JSON, Boolean, Index, Integer, String, Text
-from sqlalchemy import Enum as SQLAEnum
-from sqlalchemy.orm import Mapped, mapped_column
-
-from app.features.core.models import Base, UTCDateTime, utcnow
-from app.features.notifications.schemas import NotificationRequestMethod, NotificationRequestType
-
-
-class NotificationModel(Base):
-    __tablename__: str = "notifications"
-    __table_args__: tuple[Index, ...] = (
-        Index("ix_notifications_name", "name"),
-        Index("ix_notifications_enabled", "enabled"),
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    on: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
-    presets: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
-    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
-    request_url: Mapped[str] = mapped_column(Text, nullable=False)
-    request_method: Mapped[NotificationRequestMethod] = mapped_column(
-        SQLAEnum(NotificationRequestMethod, name="notification_request_method", native_enum=False),
-        nullable=False,
-        default=NotificationRequestMethod.POST,
-    )
-    request_type: Mapped[NotificationRequestType] = mapped_column(
-        SQLAEnum(NotificationRequestType, name="notification_request_type", native_enum=False),
-        nullable=False,
-        default=NotificationRequestType.JSON,
-    )
-    request_data_key: Mapped[str] = mapped_column(String(255), nullable=False, default="data")
-    request_headers: Mapped[list[dict]] = mapped_column(JSON, nullable=False, default=list)
-    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, nullable=False)
-    updated_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, onupdate=utcnow, nullable=False)

app/features/notifications/repository.py

@@ -1,181 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from sqlalchemy import func, or_, select
-
-from app.features.core.deps import get_session
-from app.features.notifications.migration import Migration
-from app.features.notifications.models import NotificationModel
-from app.library.log import get_logger
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-    from contextlib import AbstractAsyncContextManager
-
-    from sqlalchemy.engine.result import Result
-    from sqlalchemy.ext.asyncio import AsyncSession
-    from sqlalchemy.sql.elements import ColumnElement
-    from sqlalchemy.sql.selectable import Select
-
-    SessionFactory = Callable[[], AbstractAsyncContextManager[AsyncSession]]
-
-LOG = get_logger()
-
-
-def _model_from_payload(payload: dict[str, Any]) -> NotificationModel:
-    model = NotificationModel()
-    for key, value in payload.items():
-        if not hasattr(model, key):
-            msg = f"'{key}' is an invalid keyword argument for NotificationModel"
-            raise TypeError(msg)
-        setattr(model, key, value)
-    return model
-
-
-def _coerce_model(payload: NotificationModel | dict[str, Any]) -> NotificationModel:
-    if isinstance(payload, NotificationModel):
-        return payload
-    return _model_from_payload(payload)
-
-
-class NotificationsRepository(metaclass=Singleton):
-    def __init__(self, session: SessionFactory | None = None) -> None:
-        self._migrated = False
-        self.session: SessionFactory = session or get_session
-
-    async def run_migrations(self) -> None:
-        if self._migrated:
-            return
-
-        self._migrated = True
-        await Migration(repo=self, config=None).run()
-
-    @staticmethod
-    def get_instance() -> NotificationsRepository:
-        return NotificationsRepository()
-
-    async def all(self) -> list[NotificationModel]:
-        async with self.session() as session:
-            result: Result[tuple[NotificationModel]] = await session.execute(
-                select(NotificationModel).order_by(NotificationModel.name.asc())
-            )
-            return list(result.scalars().all())
-
-    async def list_paginated(self, page: int, per_page: int) -> tuple[list[NotificationModel], int, int, int]:
-        async with self.session() as session:
-            total: int = await self.count()
-            total_pages: int = (total + per_page - 1) // per_page if total > 0 else 1
-
-            if page > total_pages and total > 0:
-                page = total_pages
-
-            query: Select[tuple[NotificationModel]] = (
-                select(NotificationModel)
-                .order_by(NotificationModel.name.asc())
-                .limit(per_page)
-                .offset((page - 1) * per_page)
-            )
-            result: Result[tuple[NotificationModel]] = await session.execute(query)
-            return list(result.scalars().all()), total, page, total_pages
-
-    async def count(self) -> int:
-        async with self.session() as session:
-            result: Result[tuple[int]] = await session.execute(select(func.count()).select_from(NotificationModel))
-            return int(result.scalar_one())
-
-    async def get(self, identifier: int | str) -> NotificationModel | None:
-        async with self.session() as session:
-            if not identifier:
-                return None
-
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = NotificationModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(NotificationModel.id == int(identifier), NotificationModel.name == identifier)
-            else:
-                clause = NotificationModel.name == identifier
-
-            result: Result[tuple[NotificationModel]] = await session.execute(
-                select(NotificationModel).where(clause).limit(1)
-            )
-            return result.scalar_one_or_none()
-
-    async def get_by_name(self, name: str, exclude_id: int | None = None) -> NotificationModel | None:
-        async with self.session() as session:
-            query: Select[tuple[NotificationModel]] = select(NotificationModel).where(NotificationModel.name == name)
-            if exclude_id is not None:
-                query = query.where(NotificationModel.id != exclude_id)
-
-            result: Result[tuple[NotificationModel]] = await session.execute(query.limit(1))
-            return result.scalar_one_or_none()
-
-    async def create(self, payload: NotificationModel | dict[str, Any]) -> NotificationModel:
-        async with self.session() as session:
-            model = _coerce_model(payload)
-            if model.id is not None:
-                model.id = None  # ty: ignore
-
-            if await self.get_by_name(name=model.name) is not None:
-                msg: str = f"Notification target with name '{model.name}' already exists."
-                raise ValueError(msg)
-
-            session.add(model)
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def update(self, identifier: int | str, payload: dict[str, Any]) -> NotificationModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = NotificationModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(NotificationModel.id == int(identifier), NotificationModel.name == identifier)
-            else:
-                clause = NotificationModel.name == identifier
-
-            result: Result[tuple[NotificationModel]] = await session.execute(
-                select(NotificationModel).where(clause).limit(1)
-            )
-            model: NotificationModel | None = result.scalar_one_or_none()
-
-            if not model:
-                msg: str = f"Notification target '{identifier}' not found."
-                raise KeyError(msg)
-
-            payload.pop("id", None)
-
-            if "name" in payload and await self.get_by_name(name=payload["name"], exclude_id=model.id) is not None:
-                msg = f"Notification target with name '{payload['name']}' already exists."
-                raise ValueError(msg)
-
-            for key, value in payload.items():
-                if hasattr(model, key):
-                    setattr(model, key, value)
-
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def delete(self, identifier: int | str) -> NotificationModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = NotificationModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(NotificationModel.id == int(identifier), NotificationModel.name == identifier)
-            else:
-                clause = NotificationModel.name == identifier
-
-            result: Result[tuple[NotificationModel]] = await session.execute(
-                select(NotificationModel).where(clause).limit(1)
-            )
-            model = result.scalar_one_or_none()
-
-            if not model:
-                msg: str = f"Notification target '{identifier}' not found."
-                raise KeyError(msg)
-
-            await session.delete(model)
-            await session.commit()
-            return model

app/features/notifications/router.py

@@ -1,218 +0,0 @@
-from typing import Any
-
-from aiohttp import web
-from aiohttp.web import Request, Response
-from pydantic import ValidationError
-
-from app.features.core.schemas import CEAction, CEFeature, ConfigEvent, Pagination
-from app.features.core.utils import build_pagination, format_validation_errors, normalize_pagination
-from app.features.notifications.schemas import Notification, NotificationEvents, NotificationList, NotificationPatch
-from app.features.notifications.service import Notifications
-from app.library.encoder import Encoder
-from app.library.Events import EventBus, Events
-from app.library.log import get_logger
-from app.library.router import route
-
-LOG = get_logger()
-
-
-def _model(model: Any) -> Notification:
-    return Notifications.get_instance().model_to_schema(model)
-
-
-def _serialize(model: Any) -> dict:
-    return _model(model).model_dump()
-
-
-@route("GET", "api/notifications/", "notifications_list")
-async def notifications_list(request: Request, encoder: Encoder) -> Response:
-    page, per_page = normalize_pagination(request)
-    items, total, current_page, total_pages = await Notifications.get_instance().list_paginated(page, per_page)
-    return web.json_response(
-        data=NotificationList(
-            items=[_model(model) for model in items],
-            pagination=Pagination.model_validate(build_pagination(total, current_page, per_page, total_pages)),
-        ),
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("GET", "api/notifications/events/", "notifications_events")
-async def notifications_events(encoder: Encoder) -> Response:
-    return web.json_response(
-        data={"events": list(NotificationEvents.get_events().values())},
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("POST", "api/notifications/test/", "notification_test")
-async def notification_test(encoder: Encoder, notify: EventBus) -> Response:
-    notify.emit(Events.TEST, title="Test Notification", message="This is a test notification.")
-    return web.json_response(data={}, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("POST", "api/notifications/", "notification_add")
-async def notifications_add(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        item: Notification = Notification.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate notification.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        saved = _serialize(await Notifications.get_instance().create(item))
-    except ValueError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-
-    notify.emit(
-        Events.CONFIG_UPDATE,
-        data=ConfigEvent(feature=CEFeature.NOTIFICATIONS, action=CEAction.CREATE, data=saved),
-    )
-    return web.json_response(data=saved, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("GET", r"api/notifications/{id:\d+}", "notification_get")
-async def notifications_get(request: Request, encoder: Encoder) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await Notifications.get_instance().get(identifier)):
-        return web.json_response({"error": "Notification not found"}, status=web.HTTPNotFound.status_code)
-
-    return web.json_response(data=_serialize(model), status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("DELETE", r"api/notifications/{id:\d+}", "notification_delete")
-async def notifications_delete(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        deleted = _serialize(await Notifications.get_instance().delete(identifier))
-        notify.emit(
-            Events.CONFIG_UPDATE,
-            data=ConfigEvent(feature=CEFeature.NOTIFICATIONS, action=CEAction.DELETE, data=deleted),
-        )
-        return web.json_response(
-            data=deleted,
-            status=web.HTTPOk.status_code,
-            dumps=encoder.encode,
-        )
-    except KeyError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPNotFound.status_code)
-
-
-@route("PATCH", r"api/notifications/{id:\d+}", "notification_patch")
-async def notifications_patch(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await Notifications.get_instance().get(identifier)):
-        return web.json_response({"error": "Notification not found"}, status=web.HTTPNotFound.status_code)
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        validated = NotificationPatch.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate notification.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    current = _model(model).model_dump()
-    if validated.name is not None:
-        current["name"] = validated.name
-    if validated.on is not None:
-        current["on"] = validated.on
-    if validated.presets is not None:
-        current["presets"] = validated.presets
-    if validated.enabled is not None:
-        current["enabled"] = validated.enabled
-
-    if validated.request is not None:
-        request_payload = current.get("request", {})
-        if validated.request.url is not None:
-            request_payload["url"] = validated.request.url
-        if validated.request.method is not None:
-            request_payload["method"] = validated.request.method
-        if validated.request.type is not None:
-            request_payload["type"] = validated.request.type
-        if validated.request.headers is not None:
-            request_payload["headers"] = [header.model_dump() for header in validated.request.headers]
-        if validated.request.data_key is not None:
-            request_payload["data_key"] = validated.request.data_key
-        current["request"] = request_payload
-
-    try:
-        updated = _serialize(await Notifications.get_instance().update(model.id, current))
-    except ValueError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-    except KeyError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPNotFound.status_code)
-
-    notify.emit(
-        Events.CONFIG_UPDATE,
-        data=ConfigEvent(feature=CEFeature.NOTIFICATIONS, action=CEAction.UPDATE, data=updated),
-    )
-    return web.json_response(
-        data=updated,
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("PUT", r"api/notifications/{id:\d+}", "notification_update")
-async def notifications_update(request: Request, encoder: Encoder, notify: EventBus) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await Notifications.get_instance().get(identifier)):
-        return web.json_response({"error": "Notification not found"}, status=web.HTTPNotFound.status_code)
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        validated = Notification.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate notification.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        updated = _serialize(await Notifications.get_instance().update(model.id, validated))
-    except ValueError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-    except KeyError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPNotFound.status_code)
-
-    notify.emit(
-        Events.CONFIG_UPDATE,
-        data=ConfigEvent(feature=CEFeature.NOTIFICATIONS, action=CEAction.UPDATE, data=updated),
-    )
-    return web.json_response(data=updated, status=web.HTTPOk.status_code, dumps=encoder.encode)

app/features/notifications/schemas.py

@@ -1,146 +0,0 @@
-from __future__ import annotations
-
-from enum import Enum
-from typing import Any
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator
-
-from app.features.core.schemas import Pagination
-from app.library.Events import Events
-
-
-class NotificationEvents:
-    TEST: str = Events.TEST
-
-    ITEM_ADDED: str = Events.ITEM_ADDED
-    ITEM_COMPLETED: str = Events.ITEM_COMPLETED
-    ITEM_CANCELLED: str = Events.ITEM_CANCELLED
-    ITEM_DELETED: str = Events.ITEM_DELETED
-    ITEM_BULK_DELETED: str = Events.ITEM_BULK_DELETED
-    ITEM_PAUSED: str = Events.ITEM_PAUSED
-    ITEM_RESUMED: str = Events.ITEM_RESUMED
-    ITEM_MOVED: str = Events.ITEM_MOVED
-
-    PAUSED: str = Events.PAUSED
-    RESUMED: str = Events.RESUMED
-
-    LOG_INFO: str = Events.LOG_INFO
-    LOG_SUCCESS: str = Events.LOG_SUCCESS
-    LOG_WARNING: str = Events.LOG_WARNING
-    LOG_ERROR: str = Events.LOG_ERROR
-
-    TASK_DISPATCHED: str = Events.TASK_DISPATCHED
-
-    @staticmethod
-    def get_events() -> dict[str, str]:
-        return {k: v for k, v in vars(NotificationEvents).items() if not k.startswith("__") and not callable(v)}
-
-    @staticmethod
-    def events() -> list[str]:
-        return [
-            getattr(NotificationEvents, ev)
-            for ev in dir(NotificationEvents)
-            if not ev.startswith("_") and not callable(getattr(NotificationEvents, ev))
-        ]
-
-    @staticmethod
-    def is_valid(event: str) -> bool:
-        return event in NotificationEvents.get_events().values()
-
-
-class NotificationRequestType(str, Enum):
-    JSON = "json"
-    FORM = "form"
-
-    def __str__(self) -> str:
-        return self.value
-
-
-class NotificationRequestMethod(str, Enum):
-    POST = "POST"
-    PUT = "PUT"
-
-    def __str__(self) -> str:
-        return self.value
-
-
-class NotificationRequestHeader(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    key: str = Field(min_length=1)
-    value: str = Field(min_length=1)
-
-
-class NotificationRequest(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    type: NotificationRequestType = NotificationRequestType.JSON
-    method: NotificationRequestMethod = NotificationRequestMethod.POST
-    url: str = Field(min_length=1)
-    headers: list[NotificationRequestHeader] = Field(default_factory=list)
-    data_key: str = Field(default="data", min_length=1)
-
-    @field_validator("method", mode="before")
-    @classmethod
-    def _normalize_method(cls, value: Any) -> Any:
-        if value is None:
-            return value
-        if isinstance(value, NotificationRequestMethod):
-            return value
-        return str(value).upper()
-
-    @field_validator("type", mode="before")
-    @classmethod
-    def _normalize_type(cls, value: Any) -> Any:
-        if value is None:
-            return value
-        if isinstance(value, NotificationRequestType):
-            return value
-        return str(value).lower()
-
-
-class NotificationRequestPatch(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    type: NotificationRequestType | None = None
-    method: NotificationRequestMethod | None = None
-    url: str | None = None
-    headers: list[NotificationRequestHeader] | None = None
-    data_key: str | None = None
-
-
-class Notification(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    id: int | None = None
-    name: str = Field(min_length=1)
-    on: list[str] = Field(default_factory=list)
-    presets: list[str] = Field(default_factory=list)
-    enabled: bool = True
-    request: NotificationRequest
-
-    @field_validator("on", "presets", mode="before")
-    @classmethod
-    def _normalize_list(cls, value: Any) -> list[str]:
-        if value is None:
-            return []
-        if isinstance(value, list):
-            return [str(item).strip() for item in value if str(item).strip()]
-        return [str(value).strip()]
-
-
-class NotificationPatch(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    name: str | None = None
-    on: list[str] | None = None
-    presets: list[str] | None = None
-    enabled: bool | None = None
-    request: NotificationRequestPatch | None = None
-
-
-class NotificationList(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    items: list[Notification] = Field(default_factory=list)
-    pagination: Pagination

app/features/notifications/service.py

@@ -1,363 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
-
-from app.features.notifications.models import NotificationModel
-from app.features.notifications.repository import NotificationsRepository
-from app.features.notifications.schemas import (
-    Notification,
-    NotificationEvents,
-    NotificationRequest,
-    NotificationRequestHeader,
-    NotificationRequestType,
-)
-from app.features.presets.schemas import Preset
-from app.features.presets.service import Presets
-from app.library.BackgroundWorker import BackgroundWorker
-from app.library.config import Config
-from app.library.encoder import Encoder
-from app.library.Events import Event, EventBus, Events
-from app.library.httpx_client import async_client
-from app.library.ItemDTO import Item, ItemDTO
-from app.library.log import get_logger
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from collections.abc import Awaitable
-
-    import httpx
-    from aiohttp import web
-
-LOG = get_logger()
-
-
-class Notifications(metaclass=Singleton):
-    def __init__(
-        self,
-        repo: NotificationsRepository | None = None,
-        client: httpx.AsyncClient | None = None,
-        encoder: Encoder | None = None,
-        config: Config | None = None,
-        background_worker: BackgroundWorker | None = None,
-    ) -> None:
-        self._repo: NotificationsRepository = repo or NotificationsRepository.get_instance()
-
-        config = config or Config.get_instance()
-
-        self._debug: bool = config.debug
-        self._version: str = config.app_version
-        self._client: httpx.AsyncClient = client or async_client()
-        self._encoder: Encoder = encoder or Encoder()
-        self._offload: BackgroundWorker = background_worker or BackgroundWorker.get_instance()
-
-    @staticmethod
-    def get_instance() -> Notifications:
-        return Notifications()
-
-    async def on_shutdown(self, _: web.Application) -> None:
-        pass
-
-    def attach(self, _: web.Application) -> None:
-        async def handle_event(_, __):
-            await self._repo.run_migrations()
-
-        EventBus.get_instance().subscribe(Events.STARTED, handle_event, "NotificationsRepository.run_migrations")
-        EventBus.get_instance().subscribe(NotificationEvents.events(), self.emit, f"{type(self).__name__}.emit")
-
-    async def all(self) -> list[NotificationModel]:
-        return await self._repo.all()
-
-    async def list_paginated(self, page: int, per_page: int) -> tuple[list[NotificationModel], int, int, int]:
-        return await self._repo.list_paginated(page, per_page)
-
-    async def get(self, identifier: int | str) -> NotificationModel | None:
-        return await self._repo.get(identifier)
-
-    async def create(self, item: Notification | dict) -> NotificationModel:
-        if not isinstance(item, Notification):
-            item = Notification.model_validate(item)
-        normalized = self._normalize(item)
-        payload = self._payload_from_schema(normalized)
-        return await self._repo.create(payload)
-
-    async def update(self, identifier: int | str, payload: Notification | dict) -> NotificationModel:
-        if not isinstance(payload, Notification):
-            payload = Notification.model_validate(payload)
-        normalized = self._normalize(payload)
-        update_payload = self._payload_from_schema(normalized)
-        return await self._repo.update(identifier, update_payload)
-
-    async def delete(self, identifier: int | str) -> NotificationModel:
-        return await self._repo.delete(identifier)
-
-    async def send(self, ev: Event, wait: bool = True) -> list[dict | Awaitable[dict]]:
-        targets = await self._repo.all()
-        if len(targets) < 1:
-            return []
-
-        if not isinstance(ev.data, (ItemDTO, Item, dict)):
-            LOG.debug("Received invalid item type '%s' with event '%s'.", type(ev.data), ev.event)
-            return []
-
-        tasks: list[Awaitable[dict]] = []
-        apprise_targets: list[Notification] = []
-
-        for target_model in targets:
-            target = self.model_to_schema(target_model)
-            if not target.enabled:
-                continue
-
-            if len(target.on) > 0 and ev.event not in target.on and NotificationEvents.TEST != ev.event:
-                continue
-
-            if NotificationEvents.TEST != ev.event and not self._check_preset(target, ev):
-                continue
-
-            if not target.request.url.startswith("http"):
-                apprise_targets.append(target)
-            else:
-                tasks.append(self._send(target, ev))
-
-        if len(apprise_targets) > 0:
-            tasks.append(self._apprise(apprise_targets, ev))
-
-        if wait:
-            return await asyncio.gather(*tasks)
-
-        return cast("list[dict | Awaitable[dict]]", tasks)
-
-    def emit(self, e: Event, _, **__) -> None:
-        if not NotificationEvents.is_valid(e.event):
-            return
-
-        self._offload.submit(self.send, e)
-
-    def _normalize(self, item: Notification) -> Notification:
-        if item.enabled is not None and not isinstance(item.enabled, bool):
-            msg: str = "Enabled must be a boolean."
-            raise ValueError(msg)
-
-        item.on = self._filter_events(item.on)
-        item.presets = self._filter_presets(item.presets)
-        item.request.headers = [
-            NotificationRequestHeader(key=header.key, value=header.value)
-            for header in item.request.headers
-            if header.key and header.value
-        ]
-        return item
-
-    def _filter_events(self, events: list[str]) -> list[str]:
-        if not events:
-            return []
-
-        allowed = set(NotificationEvents.get_events().values())
-        valid = [event for event in events if event in allowed]
-        invalid = [event for event in events if event not in allowed]
-
-        if len(invalid) > 0 and len(valid) < 1:
-            msg: str = f"Invalid notification target. Invalid events '{', '.join(invalid)}' found."
-            raise ValueError(msg)
-
-        if len(invalid) > 0:
-            LOG.warning("Dropping invalid notification events: %s", ", ".join(invalid))
-
-        return valid
-
-    def _filter_presets(self, presets: list[str]) -> list[str]:
-        if not presets:
-            return []
-
-        all_presets: list[Preset] = Presets.get_instance().get_all()
-        allowed = {preset.name for preset in all_presets}
-        valid = [preset for preset in presets if preset in allowed]
-        invalid = [preset for preset in presets if preset not in allowed]
-
-        if len(invalid) > 0 and len(valid) < 1:
-            msg: str = f"Invalid notification target. Invalid presets '{', '.join(invalid)}' found."
-            raise ValueError(msg)
-
-        if len(invalid) > 0:
-            LOG.warning("Dropping invalid notification presets: %s", ", ".join(invalid))
-
-        return valid
-
-    def model_to_schema(self, model: NotificationModel) -> Notification:
-        headers: list[NotificationRequestHeader] = []
-        if isinstance(model.request_headers, list):
-            for header in model.request_headers:
-                if not isinstance(header, dict):
-                    continue
-                key = str(header.get("key", "")).strip()
-                value = str(header.get("value", "")).strip()
-                if key and value:
-                    headers.append(NotificationRequestHeader(key=key, value=value))
-
-        return Notification(
-            id=model.id,
-            name=model.name,
-            on=list(model.on or []),
-            presets=list(model.presets or []),
-            enabled=model.enabled,
-            request=NotificationRequest.model_validate(
-                {
-                    "type": model.request_type,
-                    "method": model.request_method,
-                    "url": model.request_url,
-                    "headers": headers,
-                    "data_key": model.request_data_key,
-                }
-            ),
-        )
-
-    def _payload_from_schema(self, item: Notification) -> dict[str, Any]:
-        return {
-            "name": item.name,
-            "on": list(item.on),
-            "presets": list(item.presets),
-            "enabled": item.enabled,
-            "request_url": item.request.url,
-            "request_method": str(item.request.method),
-            "request_type": str(item.request.type),
-            "request_data_key": item.request.data_key,
-            "request_headers": [header.model_dump() for header in item.request.headers],
-        }
-
-    def _check_preset(self, target: Notification, ev: Event) -> bool:
-        if len(target.presets) < 1:
-            return True
-
-        if not isinstance(ev.data, (Item, ItemDTO, dict)):
-            return False
-
-        preset_name: str | None = None
-
-        if isinstance(ev.data, Item):
-            preset_name = ev.data.preset
-
-        if isinstance(ev.data, ItemDTO):
-            preset_name = ev.data.preset
-
-        if isinstance(ev.data, dict):
-            preset_name = ev.data.get("preset", None)
-
-        if not preset_name:
-            return False
-
-        return preset_name in target.presets
-
-    async def _apprise(self, targets: list[Notification], ev: Event) -> dict:
-        if not targets:
-            return {}
-
-        import apprise
-
-        try:
-            notify = apprise.Apprise(debug=self._debug)
-            apr_config = Path(Config.get_instance().apprise_config)
-            if apr_config.exists():
-                apprise_file = apprise.AppriseConfig()
-                apprise_file.add(str(apr_config))
-                notify.add(apprise_file)
-
-            for target in targets:
-                notify.add(target.request.url)
-
-            status = await notify.async_notify(
-                body=ev.message or self._encoder.encode(ev.serialize()),
-                title=ev.title or f"YTPTube Event: {ev.event}",
-            )
-
-            if not status:
-                msg = "Apprise failed to send notification."
-                self._raise_apprise_error(msg)
-        except Exception as exc:
-            LOG.exception(
-                "Failed to send Apprise notification for event '%s'.",
-                ev.event,
-                extra={
-                    "event_id": ev.id,
-                    "event": ev.event,
-                    "target_count": len(targets),
-                    "targets": [t.name for t in targets],
-                    "exception_type": type(exc).__name__,
-                },
-            )
-            return {"error": str(exc), "event": ev.event, "id": ev.id, "targets": [t.name for t in targets]}
-
-        return {}
-
-    @staticmethod
-    def _raise_apprise_error(msg: str) -> None:
-        raise RuntimeError(msg)
-
-    async def _send(self, target: Notification, ev: Event) -> dict:
-        try:
-            LOG.info("Sending notification event '%s: %s' to '%s'.", ev.event, ev.id, target.name)
-
-            headers: dict[str, str] = {
-                "User-Agent": f"YTPTube/{self._version}",
-                "X-Event-Id": ev.id,
-                "X-Event": ev.event,
-                "Content-Type": "application/json"
-                if NotificationRequestType.JSON == target.request.type
-                else "application/x-www-form-urlencoded",
-            }
-
-            if len(target.request.headers) > 0:
-                headers.update({h.key: h.value for h in target.request.headers if h.key and h.value})
-
-            payload_data: dict[str, Any] = ev.serialize()
-
-            if "data" != target.request.data_key:
-                payload_data[target.request.data_key] = payload_data["data"]
-                payload_data.pop("data", None)
-
-            if NotificationRequestType.FORM == target.request.type:
-                payload_data[target.request.data_key] = self._encoder.encode(payload_data[target.request.data_key])
-                data_payload: dict[str, Any] | None = payload_data
-                content_payload: str | None = None
-            else:
-                data_payload = None
-                content_payload = self._encoder.encode(payload_data)
-
-            response = await self._client.request(
-                method=str(target.request.method).upper(),
-                url=target.request.url,
-                headers=headers,
-                data=data_payload,
-                content=content_payload,
-            )
-
-            resp_data: dict[str, Any] = {
-                "url": target.request.url,
-                "status": response.status_code,
-                "text": response.text,
-            }
-
-            msg: str = (
-                f"Notification target '{target.name}' Responded to event '{ev.event}: {ev.id}' "
-                f"with status '{response.status_code}'."
-            )
-            if self._debug and resp_data.get("text"):
-                msg += f" body '{resp_data.get('text', '??')}'."
-
-            LOG.info(msg)
-
-            return resp_data
-        except Exception as exc:
-            LOG.exception(
-                "Failed to send notification event '%s: %s' to '%s'.",
-                ev.event,
-                ev.id,
-                target.name,
-                extra={
-                    "event_id": ev.id,
-                    "event": ev.event,
-                    "target_name": target.name,
-                    "url": target.request.url,
-                    "exception_type": type(exc).__name__,
-                },
-            )
-            return {"url": target.request.url, "status": 500, "text": str(ev)}

app/features/notifications/tests/test_notifications_repository.py

@@ -1,152 +0,0 @@
-"""Tests for NotificationsRepository."""
-
-from __future__ import annotations
-
-import pytest
-import pytest_asyncio
-
-from app.features.notifications.repository import NotificationsRepository
-from app.library.sqlite_store import SqliteStore
-from app.tests.helpers import make_in_memory_db_path
-
-
-@pytest_asyncio.fixture
-async def repo():
-    """Provide a fresh repository instance with initialized database for each test."""
-    NotificationsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-    store = SqliteStore(db_path=make_in_memory_db_path("notifications-repository"))
-    await store.get_connection()
-
-    repository = NotificationsRepository.get_instance()
-
-    yield repository
-
-    await store.close()
-
-    NotificationsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-
-class TestNotificationsRepository:
-    """Test suite for NotificationsRepository database operations."""
-
-    @pytest.mark.asyncio
-    async def test_list_empty(self, repo):
-        """List returns empty when no notifications exist."""
-        notifications = await repo.all()
-        assert notifications == [], "Should return empty list when no notifications exist"
-
-    @pytest.mark.asyncio
-    async def test_create_notification(self, repo):
-        """Create notification with valid data."""
-        payload = {
-            "name": "Webhook",
-            "on": ["item_completed"],
-            "presets": [],
-            "enabled": True,
-            "request_url": "https://example.com/webhook",
-            "request_method": "POST",
-            "request_type": "json",
-            "request_data_key": "data",
-            "request_headers": [{"key": "Authorization", "value": "Bearer token"}],
-        }
-
-        model = await repo.create(payload)
-
-        assert model.id is not None, "Should generate ID for new notification"
-        assert model.name == "Webhook", "Should store name correctly"
-        assert model.request_url == "https://example.com/webhook", "Should store request url"
-        assert model.request_method == "POST", "Should store request method"
-
-    @pytest.mark.asyncio
-    async def test_get_by_id(self, repo):
-        """Get notification by integer ID."""
-        created = await repo.create(
-            {
-                "name": "Get Test",
-                "on": [],
-                "presets": [],
-                "enabled": True,
-                "request_url": "https://example.com",
-                "request_method": "POST",
-                "request_type": "json",
-                "request_data_key": "data",
-                "request_headers": [],
-            }
-        )
-
-        retrieved = await repo.get(created.id)
-
-        assert retrieved is not None, "Should retrieve created notification"
-        assert retrieved.id == created.id, "Should match created notification id"
-
-    @pytest.mark.asyncio
-    async def test_update_notification(self, repo):
-        """Update existing notification."""
-        created = await repo.create(
-            {
-                "name": "Update Test",
-                "on": [],
-                "presets": [],
-                "enabled": True,
-                "request_url": "https://example.com",
-                "request_method": "POST",
-                "request_type": "json",
-                "request_data_key": "data",
-                "request_headers": [],
-            }
-        )
-
-        updated = await repo.update(created.id, {"name": "Updated Name", "enabled": False})
-
-        assert updated.name == "Updated Name", "Should update name"
-        assert updated.enabled is False, "Should update enabled flag"
-
-    @pytest.mark.asyncio
-    async def test_delete_notification(self, repo):
-        """Delete existing notification."""
-        created = await repo.create(
-            {
-                "name": "Delete Test",
-                "on": [],
-                "presets": [],
-                "enabled": True,
-                "request_url": "https://example.com",
-                "request_method": "POST",
-                "request_type": "json",
-                "request_data_key": "data",
-                "request_headers": [],
-            }
-        )
-
-        deleted = await repo.delete(created.id)
-
-        assert deleted.id == created.id, "Should return deleted notification"
-        assert await repo.get(created.id) is None, "Deleted notification should not be retrievable"
-
-    @pytest.mark.asyncio
-    async def test_list_paginated(self, repo):
-        """List paginated returns correct subset."""
-        for i in range(4):
-            await repo.create(
-                {
-                    "name": f"Item {i}",
-                    "on": [],
-                    "presets": [],
-                    "enabled": True,
-                    "request_url": "https://example.com",
-                    "request_method": "POST",
-                    "request_type": "json",
-                    "request_data_key": "data",
-                    "request_headers": [],
-                }
-            )
-
-        items, total, page, total_pages = await repo.list_paginated(page=1, per_page=2)
-
-        assert len(items) == 2, "Should return 2 items per page"
-        assert total == 4, "Should report total count of 4"
-        assert page == 1, "Should be on page 1"
-        assert total_pages == 2, "Should have 2 pages total"

app/features/presets/__init__.py

@@ -1 +0,0 @@
-"""Presets feature module."""

app/features/presets/defaults.py

@@ -1,94 +0,0 @@
-from datetime import UTC, datetime
-
-DEFAULT_PRESET_UPDATED_AT: datetime = datetime(2026, 1, 25, tzinfo=UTC)
-
-DEFAULT_PRESETS: list[dict[str, object]] = [
-    {
-        "name": "default",
-        "default": True,
-        "cli": "--socket-timeout 30 --download-archive %(archive_file)s",
-        "description": "Default preset for yt-dlp. It will download whatever yt-dlp decides is the best quality for the video and audio.",
-        "folder": "",
-        "template": "",
-        "cookies": "",
-        "priority": 0,
-        "updated_at": DEFAULT_PRESET_UPDATED_AT,
-    },
-    {
-        "name": "mobile",
-        "cli": '--socket-timeout 30 --download-archive %(archive_file)s\n-t mp4 --merge-output-format mp4 --add-chapters --remux-video mp4 \n--embed-metadata --embed-thumbnail \n--postprocessor-args "-movflags +faststart"',
-        "default": True,
-        "description": "This preset is designed for mobile devices. It will download the best quality video and audio in mp4 format, merge them, and add chapters, metadata, and thumbnail.",
-        "folder": "",
-        "template": "",
-        "cookies": "",
-        "priority": 0,
-        "updated_at": DEFAULT_PRESET_UPDATED_AT,
-    },
-    {
-        "name": "1080p",
-        "cli": "--socket-timeout 30 --download-archive %(archive_file)s\n-S vcodec:h264 --format 'bv[height<=1080][ext=mp4]+ba[ext=m4a]/b[ext=mp4]/b[ext=webm]'",
-        "default": True,
-        "description": "Download the best quality video and audio in mp4 format for 1080p resolution.",
-        "folder": "",
-        "template": "",
-        "cookies": "",
-        "priority": 0,
-        "updated_at": DEFAULT_PRESET_UPDATED_AT,
-    },
-    {
-        "name": "720p",
-        "cli": "--socket-timeout 30 --download-archive %(archive_file)s\n-S vcodec:h264 --format 'bv[height<=720][ext=mp4]+ba[ext=m4a]/b[ext=mp4]/b[ext=webm]'",
-        "default": True,
-        "description": "Download the best quality video and audio in mp4 format for 720p resolution.",
-        "folder": "",
-        "template": "",
-        "cookies": "",
-        "priority": 0,
-        "updated_at": DEFAULT_PRESET_UPDATED_AT,
-    },
-    {
-        "name": "audio_only",
-        "cli": "--socket-timeout 30 --download-archive %(archive_file)s\n--extract-audio --add-chapters --embed-metadata --embed-thumbnail --format 'bestaudio/best'",
-        "default": True,
-        "description": "This preset is designed to download only the audio of the video. It will extract the audio, add chapters, metadata, and thumbnail.",
-        "folder": "",
-        "template": "",
-        "cookies": "",
-        "priority": 0,
-        "updated_at": DEFAULT_PRESET_UPDATED_AT,
-    },
-    {
-        "name": "info_reader_plugin",
-        "description": 'This preset generate specific filename format and metadata to work with yt-dlp info reader plugins for jellyfin/emby and plex and to make play state sync work for WatchState.\n\nThere is one more step you need to do via Other > Terminal if you have it enabled or directly from container shell\n\nyt-dlp -I0 --write-info-json --write-thumbnail --convert-thumbnails jpg --paths /downloads/youtube -o "%(channel|Unknown_title)s [%(channel_id|Unknown_id)s]/%(title).180B [%(channel_id|Unknown_id)s].%(ext)s" -- https://www.youtube.com/channel/UCClfFsWcT3N2I7VTXXyt84A\n\nChange the url to the channel you want to download.\n\nFor more information please visit \nhttps://github.com/arabcoders/watchstate/blob/master/FAQ.md#how-to-get-watchstate-working-with-youtube-contentlibrary',
-        "folder": "",
-        "template": "%(channel)s [%(channel_id|Unknown_id)s]/Season %(release_date>%Y,upload_date>%Y|Unknown)s/%(release_date>%Y%m%d,upload_date>%Y%m%d)s - %(title).180B [%(id)s].%(ext)s",
-        "cli": "--socket-timeout 30 --download-archive %(archive_file)s\n--windows-filenames --write-info-json --embed-info-json \n--convert-thumbnails jpg --write-thumbnail --embed-metadata",
-        "cookies": "",
-        "default": True,
-        "priority": 0,
-        "updated_at": DEFAULT_PRESET_UPDATED_AT,
-    },
-    {
-        "name": "nfo_maker_tv",
-        "description": "This preset generate specific filename format and metadata to work with media servers like jellyfin/emby and plex for episodes.",
-        "folder": "",
-        "template": "%(channel)s [%(channel_id|Unknown_id)s]/Season %(release_date>%Y,upload_date>%Y|Unknown)s/S%(release_date>%Y,upload_date>%Y)sE%(release_date>%m%d,upload_date>%m%d)s - %(title).100B [%(id)s].%(ext)s",
-        "cli": '--socket-timeout 30 --download-archive %(archive_file)s\n--use-postprocessor "NFOMakerPP:when=after_move" \n--windows-filenames --convert-thumbnails jpg --write-thumbnail',
-        "cookies": "",
-        "default": True,
-        "priority": 0,
-        "updated_at": DEFAULT_PRESET_UPDATED_AT,
-    },
-    {
-        "name": "nfo_maker_movie",
-        "description": "This preset generate specific filename format and metadata to work with media servers like jellyfin/emby and plex for movies.",
-        "folder": "",
-        "template": "%(channel)s [%(channel_id|Unknown_id)s]/Season %(release_date>%Y,upload_date>%Y|Unknown)s/S%(release_date>%Y,upload_date>%Y)sE%(release_date>%m%d,upload_date>%m%d)s - %(title).100B [%(id)s].%(ext)s",
-        "cli": '--socket-timeout 30 --download-archive %(archive_file)s\n--use-postprocessor "NFOMakerPP:when=after_move;mode=movie" \n--windows-filenames --convert-thumbnails jpg --write-thumbnail',
-        "cookies": "",
-        "default": True,
-        "priority": 0,
-        "updated_at": DEFAULT_PRESET_UPDATED_AT,
-    },
-]

app/features/presets/deps.py

@@ -1,10 +0,0 @@
-from app.features.presets.repository import PresetsRepository
-from app.features.presets.service import Presets
-
-
-def get_presets_repo() -> PresetsRepository:
-    return PresetsRepository.get_instance()
-
-
-def get_presets_service() -> Presets:
-    return Presets.get_instance()

app/features/presets/migration.py

@@ -1,121 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-from app.features.core.migration import Migration as FeatureMigration
-from app.features.presets.schemas import Preset
-from app.features.presets.utils import preset_name
-from app.library.config import Config
-from app.library.log import get_logger
-
-if TYPE_CHECKING:
-    from app.features.presets.repository import PresetsRepository
-
-LOG = get_logger()
-
-
-class Migration(FeatureMigration):
-    name: str = "presets"
-
-    def __init__(self, repo: PresetsRepository, config: Config | None = None) -> None:
-        self._config: Config = config or Config.get_instance()
-        super().__init__(config=self._config)
-        self._repo: PresetsRepository = repo
-        self._source_file: Path = Path(self._config.config_path) / "presets.json"
-
-    async def should_run(self) -> bool:
-        return self._source_file.exists()
-
-    async def migrate(self) -> None:
-        try:
-            items: list[dict[str, Any]] | None = json.loads(self._source_file.read_text())
-        except Exception as exc:
-            LOG.exception(
-                "Failed to read presets migration file '%s'. Ignoring.",
-                self._source_file,
-                extra={"file_path": str(self._source_file), "exception_type": type(exc).__name__},
-            )
-            await self._move_file(self._source_file)
-            return
-
-        if not items:
-            LOG.warning("No presets found in %s; skipping migration.", self._source_file)
-            await self._move_file(self._source_file)
-            return
-
-        inserted = 0
-        seen_names: dict[str, int] = {preset_name(preset.name): 1 for preset in await self._repo.all()}
-
-        for index, item in enumerate(items):
-            if not (normalized := self._normalize(item, index, seen_names)):
-                continue
-            try:
-                await self._repo.create(normalized)
-                inserted += 1
-            except Exception as exc:
-                LOG.exception(
-                    "Failed to insert preset '%s'.",
-                    normalized["name"],
-                    extra={"preset": normalized["name"], "exception_type": type(exc).__name__},
-                )
-
-        LOG.info("Migrated %s preset(s) from %s.", inserted, self._source_file)
-        await self._move_file(self._source_file)
-
-    def _normalize(self, item: Any, index: int, seen_names: dict[str, int]) -> dict[str, Any] | None:
-        if not isinstance(item, dict):
-            LOG.warning("Skipping preset at index %s due to invalid type.", index)
-            return None
-
-        name: str | None = item.get("name")
-        if not name or not isinstance(name, str):
-            LOG.warning("Skipping preset at index %s due to missing name.", index)
-            return None
-
-        if not (name := preset_name(name)):
-            LOG.warning("Skipping preset at index %s due to empty name.", index)
-            return None
-
-        name = self._unique_name(name, seen_names)
-
-        description: str = item.get("description") if isinstance(item.get("description"), str) else ""
-        folder: str = item.get("folder") if isinstance(item.get("folder"), str) else ""
-        template: str = item.get("template") if isinstance(item.get("template"), str) else ""
-        cookies: str = item.get("cookies") if isinstance(item.get("cookies"), str) else ""
-        cli: str = item.get("cli") if isinstance(item.get("cli"), str) else ""
-        priority = 0
-        if isinstance(item.get("priority"), int) and not isinstance(item.get("priority"), bool):
-            priority = int(item.get("priority"))
-
-        if not cli and isinstance(item.get("format"), str):
-            cli = f"--format {item.get('format')}"
-
-        if cli:
-            try:
-                from app.features.ytdlp.utils import arg_converter
-
-                arg_converter(args=cli, level=True)
-            except Exception as exc:
-                LOG.warning("Skipping preset '%s' due to invalid CLI: %s", name, exc)
-                return None
-
-        payload = {
-            "name": name,
-            "description": description,
-            "folder": folder,
-            "template": template,
-            "cookies": cookies,
-            "cli": cli,
-            "default": False,
-            "priority": priority,
-        }
-
-        try:
-            Preset.model_validate(payload)
-        except Exception as exc:
-            LOG.warning("Skipping preset '%s' due to validation error: %s", name, exc)
-            return None
-
-        return payload

app/features/presets/models.py

@@ -1,27 +0,0 @@
-from datetime import datetime
-
-from sqlalchemy import Boolean, Index, Integer, String, Text
-from sqlalchemy.orm import Mapped, mapped_column
-
-from app.features.core.models import Base, UTCDateTime, utcnow
-
-
-class PresetModel(Base):
-    __tablename__: str = "presets"
-    __table_args__: tuple[Index, ...] = (
-        Index("ix_presets_name", "name"),
-        Index("ix_presets_is_default", "is_default"),
-        Index("ix_presets_priority", "priority"),
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    description: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    folder: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    template: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    cookies: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    cli: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    default: Mapped[bool] = mapped_column("is_default", Boolean, nullable=False, default=False)
-    priority: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
-    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, nullable=False)
-    updated_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, onupdate=utcnow, nullable=False)

app/features/presets/repository.py

@@ -1,334 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from sqlalchemy import func, or_, select
-
-from app.features.core.deps import get_session
-from app.features.core.schemas import CEFeature, ConfigEvent
-from app.features.presets.migration import Migration
-from app.features.presets.models import PresetModel
-from app.features.presets.utils import preset_name, seed_defaults
-from app.library.config import Config
-from app.library.Events import Event, EventBus, Events
-from app.library.log import get_logger
-from app.library.Services import Services
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-    from contextlib import AbstractAsyncContextManager
-
-    from aiohttp import web
-    from sqlalchemy.engine.result import Result
-    from sqlalchemy.ext.asyncio import AsyncSession
-    from sqlalchemy.sql.elements import ColumnElement
-    from sqlalchemy.sql.selectable import Select
-
-    SessionFactory = Callable[[], AbstractAsyncContextManager[AsyncSession]]
-
-LOG = get_logger()
-
-
-def _payload_data(payload: PresetModel | dict[str, Any]) -> dict[str, Any]:
-    if isinstance(payload, dict):
-        data: dict[str, Any] = {}
-        for key, value in payload.items():
-            if not isinstance(key, str):
-                msg = "Preset payload keys must be strings."
-                raise TypeError(msg)
-            data[key] = value
-        return data
-
-    return {
-        "name": payload.name,
-        "description": payload.description,
-        "folder": payload.folder,
-        "template": payload.template,
-        "cookies": payload.cookies,
-        "cli": payload.cli,
-        "default": payload.default,
-        "priority": payload.priority,
-        "created_at": payload.created_at,
-        "updated_at": payload.updated_at,
-    }
-
-
-class PresetsRepository(metaclass=Singleton):
-    SORT_FIELDS: dict[str, Any] = {
-        "id": PresetModel.id,
-        "name": PresetModel.name,
-        "priority": PresetModel.priority,
-        "default": PresetModel.default,
-        "created_at": PresetModel.created_at,
-        "updated_at": PresetModel.updated_at,
-    }
-    SORT_DIRECTIONS: tuple[str, str] = ("asc", "desc")
-    DEFAULT_SORT_ORDER: tuple[tuple[str, str], ...] = (("priority", "desc"), ("name", "asc"))
-    FIELD_DEFAULT_DIRECTIONS: dict[str, str] = {
-        "id": "asc",
-        "name": "asc",
-        "priority": "desc",
-        "default": "desc",
-        "created_at": "desc",
-        "updated_at": "desc",
-    }
-
-    def __init__(self, session: SessionFactory | None = None) -> None:
-        self._migrated = False
-        self.session: SessionFactory = session or get_session
-
-    async def run_migrations(self) -> None:
-        if self._migrated:
-            return
-
-        self._migrated = True
-        await Migration(repo=self).run()
-
-    def attach(self, _: web.Application) -> None:
-        async def handle_event(_, __):
-            await seed_defaults(self)
-            await self.run_migrations()
-            await self._update_cache()
-            await self._ensure_default_preset()
-
-        async def handler(e: Event, __):
-            if isinstance(e.data, ConfigEvent) and CEFeature.PRESETS == e.data.feature:
-                LOG.debug("Refreshing presets cache due to configuration update.")
-                await self._update_cache()
-
-        Services.get_instance().add(PresetsRepository.__name__, self)
-        EventBus.get_instance().subscribe(
-            Events.STARTED, handle_event, f"{PresetsRepository.__name__}.run_migrations"
-        ).subscribe(Events.CONFIG_UPDATE, handler, "Presets.refresh_cache")
-
-    async def _update_cache(self) -> None:
-        from app.features.presets.service import Presets
-
-        await Presets.get_instance().refresh_cache(await self.all())
-
-    @staticmethod
-    def get_instance() -> PresetsRepository:
-        return PresetsRepository()
-
-    async def _ensure_default_preset(self) -> None:
-        config = Config.get_instance()
-        if not (default_name := preset_name(config.default_preset)):
-            config.default_preset = "default"
-            default_name = config.default_preset
-
-        if await self.get_by_name(default_name) is None:
-            LOG.error("Default preset '%s' not found, using 'default' preset.", default_name)
-            config.default_preset = "default"
-
-    async def all(self) -> list[PresetModel]:
-        async with self.session() as session:
-            result: Result[tuple[PresetModel]] = await session.execute(
-                select(PresetModel).order_by(PresetModel.priority.desc(), PresetModel.name.asc())
-            )
-            return list(result.scalars().all())
-
-    @classmethod
-    def parse_sorting(cls, sort: str | None = None, order: str | None = None) -> tuple[tuple[str, str], ...]:
-        sort_value = (sort or "").strip()
-        order_value = (order or "").strip()
-
-        if not sort_value and not order_value:
-            return cls.DEFAULT_SORT_ORDER
-
-        if order_value and not sort_value:
-            msg = "sort is required when order is provided."
-            raise ValueError(msg)
-
-        fields: list[str] = []
-        for raw_field in sort_value.split(","):
-            field = raw_field.strip().lower()
-            if not field:
-                continue
-            if field not in cls.SORT_FIELDS:
-                msg = f"sort must use supported fields: {', '.join(cls.SORT_FIELDS)}."
-                raise ValueError(msg)
-            if field not in fields:
-                fields.append(field)
-
-        if not fields:
-            msg = "sort must include at least one field."
-            raise ValueError(msg)
-
-        directions: list[str] = []
-        if order_value:
-            for raw_direction in order_value.split(","):
-                direction = raw_direction.strip().lower()
-                if not direction:
-                    continue
-                if direction not in cls.SORT_DIRECTIONS:
-                    msg = "order must be 'asc' or 'desc'."
-                    raise ValueError(msg)
-                directions.append(direction)
-
-            if not directions:
-                msg = "order must include at least one direction."
-                raise ValueError(msg)
-
-            if len(directions) not in {1, len(fields)}:
-                msg = "order must provide one direction or match the number of sort fields."
-                raise ValueError(msg)
-
-        if not directions:
-            return tuple((field, cls.FIELD_DEFAULT_DIRECTIONS.get(field, "asc")) for field in fields)
-
-        if len(directions) == 1:
-            return tuple((field, directions[0]) for field in fields)
-
-        return tuple((field, directions[index]) for index, field in enumerate(fields))
-
-    @classmethod
-    def _apply_sort_direction(cls, field: str, direction: str) -> Any:
-        column = cls.SORT_FIELDS[field]
-        return column.asc() if direction == "asc" else column.desc()
-
-    @classmethod
-    def _build_order_by(cls, sort: str | None = None, order: str | None = None) -> list[Any]:
-        sorting = cls.parse_sorting(sort, order)
-
-        order_by: list[Any] = [cls._apply_sort_direction(field, direction) for field, direction in sorting]
-
-        if all(field != "id" for field, _ in sorting):
-            order_by.append(PresetModel.id.asc())
-
-        return order_by
-
-    async def list_paginated(
-        self,
-        page: int,
-        per_page: int,
-        sort: str | None = None,
-        order: str | None = None,
-        exclude_defaults: bool = False,
-    ) -> tuple[list[PresetModel], int, int, int]:
-        order_by = self._build_order_by(sort, order)
-
-        async with self.session() as session:
-            total: int = await self.count(exclude_defaults=exclude_defaults)
-            total_pages: int = (total + per_page - 1) // per_page if total > 0 else 1
-
-            if page > total_pages and total > 0:
-                page = total_pages
-
-            query: Select[tuple[PresetModel]] = select(PresetModel)
-            if exclude_defaults:
-                query = query.where(PresetModel.default.is_(False))
-
-            query = query.order_by(*order_by).limit(per_page).offset((page - 1) * per_page)
-            result: Result[tuple[PresetModel]] = await session.execute(query)
-            return list(result.scalars().all()), total, page, total_pages
-
-    async def count(self, exclude_defaults: bool = False) -> int:
-        async with self.session() as session:
-            query = select(func.count()).select_from(PresetModel)
-            if exclude_defaults:
-                query = query.where(PresetModel.default.is_(False))
-
-            result: Result[tuple[int]] = await session.execute(query)
-            return int(result.scalar_one())
-
-    async def get(self, identifier: int | str) -> PresetModel | None:
-        async with self.session() as session:
-            if not identifier:
-                return None
-
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = PresetModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(PresetModel.id == int(identifier), PresetModel.name == identifier)
-            else:
-                name = preset_name(identifier) if isinstance(identifier, str) else identifier
-                if not name:
-                    return None
-                clause = PresetModel.name == name
-
-            result: Result[tuple[PresetModel]] = await session.execute(select(PresetModel).where(clause).limit(1))
-            return result.scalar_one_or_none()
-
-    async def get_by_name(self, name: str, exclude_id: int | None = None) -> PresetModel | None:
-        async with self.session() as session:
-            if not (name := preset_name(name)):
-                return None
-
-            query: Select[tuple[PresetModel]] = select(PresetModel).where(PresetModel.name == name)
-            if None is not exclude_id:
-                query = query.where(PresetModel.id != exclude_id)
-
-            result: Result[tuple[PresetModel]] = await session.execute(query.limit(1))
-            return result.scalar_one_or_none()
-
-    async def create(self, payload: PresetModel | dict[str, Any]) -> PresetModel:
-        async with self.session() as session:
-            data = _payload_data(payload)
-
-            data.pop("id", None)
-            model = PresetModel(**data)
-
-            model.name = preset_name(model.name)
-
-            if await self.get_by_name(name=model.name) is not None:
-                msg: str = f"Preset with name '{model.name}' already exists."
-                raise ValueError(msg)
-
-            session.add(model)
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def update(self, identifier: int | str, payload: dict[str, Any]) -> PresetModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = PresetModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(PresetModel.id == int(identifier), PresetModel.name == identifier)
-            else:
-                clause = PresetModel.name == identifier
-
-            result: Result[tuple[PresetModel]] = await session.execute(select(PresetModel).where(clause).limit(1))
-            model: PresetModel | None = result.scalar_one_or_none()
-
-            if model is None:
-                msg: str = f"Preset '{identifier}' not found."
-                raise KeyError(msg)
-
-            payload.pop("id", None)
-            payload.pop("created_at", None)
-            payload.pop("updated_at", None)
-
-            for key, value in payload.items():
-                if hasattr(model, key):
-                    setattr(model, key, value)
-
-            normalized_name = preset_name(model.name)
-            model.name = normalized_name
-            if await self.get_by_name(name=normalized_name, exclude_id=model.id) is not None:
-                msg = f"Preset with name '{normalized_name}' already exists."
-                raise ValueError(msg)
-
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def delete(self, identifier: int | str) -> PresetModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = PresetModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(PresetModel.id == int(identifier), PresetModel.name == identifier)
-            else:
-                clause = PresetModel.name == preset_name(identifier)
-
-            result: Result[tuple[PresetModel]] = await session.execute(select(PresetModel).where(clause).limit(1))
-            model: PresetModel | None = result.scalar_one_or_none()
-            if model is None:
-                msg: str = f"Preset '{identifier}' not found."
-                raise KeyError(msg)
-
-            await session.delete(model)
-            await session.commit()
-            return model

app/features/presets/router.py

@@ -1,200 +0,0 @@
-from typing import Any
-
-from aiohttp import web
-from aiohttp.web import Request, Response
-from pydantic import ValidationError
-
-from app.features.core.schemas import CEAction, CEFeature, ConfigEvent, Pagination
-from app.features.core.utils import build_pagination, format_validation_errors, normalize_pagination
-from app.features.presets.repository import PresetsRepository
-from app.features.presets.schemas import Preset, PresetList, PresetPatch
-from app.library.encoder import Encoder
-from app.library.Events import EventBus, Events
-from app.library.router import route
-
-
-def _model(model: Any) -> Preset:
-    return Preset.model_validate(model)
-
-
-def _serialize(model: Any) -> dict:
-    return _model(model).model_dump()
-
-
-@route("GET", "api/presets/", "presets")
-async def presets_list(request: Request, encoder: Encoder, repo: PresetsRepository) -> Response:
-    try:
-        page, per_page = normalize_pagination(request)
-        items, total, current_page, total_pages = await repo.list_paginated(
-            page=page,
-            per_page=per_page,
-            sort=request.query.get("sort"),
-            order=request.query.get("order"),
-            exclude_defaults=bool(request.query.get("exclude_defaults", False)),
-        )
-    except ValueError as exc:
-        return web.json_response(data={"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-
-    return web.json_response(
-        data=PresetList(
-            items=[_model(model) for model in items],
-            pagination=Pagination.model_validate(build_pagination(total, current_page, per_page, total_pages)),
-        ),
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("GET", r"api/presets/{id:\d+}", "presets_get")
-async def presets_get(request: Request, encoder: Encoder, repo: PresetsRepository) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await repo.get(identifier)):
-        return web.json_response({"error": "Preset not found"}, status=web.HTTPNotFound.status_code)
-
-    return web.json_response(data=_serialize(model), status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("POST", "api/presets/", "presets_add")
-async def presets_add(request: Request, encoder: Encoder, notify: EventBus, repo: PresetsRepository) -> Response:
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        item: Preset = Preset.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate preset.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    payload = item.model_dump(exclude_unset=True)
-    payload.pop("id", None)
-    payload["default"] = False
-
-    try:
-        saved = _serialize(await repo.create(payload))
-    except ValueError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-
-    notify.emit(
-        Events.CONFIG_UPDATE,
-        data=ConfigEvent(feature=CEFeature.PRESETS, action=CEAction.CREATE, data=saved),
-    )
-    return web.json_response(data=saved, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("PATCH", r"api/presets/{id:\d+}", "presets_patch")
-async def presets_patch(request: Request, encoder: Encoder, notify: EventBus, repo: PresetsRepository) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await repo.get(identifier)):
-        return web.json_response({"error": "Preset not found"}, status=web.HTTPNotFound.status_code)
-
-    if model.default:
-        return web.json_response(
-            {"error": "Default presets cannot be modified."}, status=web.HTTPBadRequest.status_code
-        )
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        validated = PresetPatch.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate preset.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if validated.name and await repo.get_by_name(validated.name, exclude_id=model.id):
-        return web.json_response(
-            data={"error": f"Preset with name '{validated.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    payload = validated.model_dump(exclude_unset=True)
-    payload.pop("default", None)
-    updated = _serialize(await repo.update(model.id, payload))
-    notify.emit(
-        Events.CONFIG_UPDATE,
-        data=ConfigEvent(feature=CEFeature.PRESETS, action=CEAction.UPDATE, data=updated),
-    )
-    return web.json_response(data=updated, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("PUT", r"api/presets/{id:\d+}", "presets_update")
-async def presets_update(request: Request, encoder: Encoder, notify: EventBus, repo: PresetsRepository) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await repo.get(identifier)):
-        return web.json_response({"error": "Preset not found"}, status=web.HTTPNotFound.status_code)
-
-    if model.default:
-        return web.json_response(
-            {"error": "Default presets cannot be modified."}, status=web.HTTPBadRequest.status_code
-        )
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        validated = Preset.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate preset.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if validated.name and await repo.get_by_name(validated.name, exclude_id=model.id):
-        return web.json_response(
-            data={"error": f"Preset with name '{validated.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    payload = validated.model_dump(exclude_unset=True)
-    payload.pop("default", None)
-    payload.pop("id", None)
-    updated = _serialize(await repo.update(model.id, payload))
-    notify.emit(
-        Events.CONFIG_UPDATE,
-        data=ConfigEvent(feature=CEFeature.PRESETS, action=CEAction.UPDATE, data=updated),
-    )
-    return web.json_response(data=updated, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("DELETE", r"api/presets/{id:\d+}", "presets_delete")
-async def presets_delete(request: Request, encoder: Encoder, notify: EventBus, repo: PresetsRepository) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    if not (model := await repo.get(identifier)):
-        return web.json_response({"error": "Preset not found"}, status=web.HTTPNotFound.status_code)
-
-    if model.default:
-        return web.json_response({"error": "Default presets cannot be deleted."}, status=web.HTTPBadRequest.status_code)
-
-    deleted = _serialize(await repo.delete(model.id))
-    notify.emit(
-        Events.CONFIG_UPDATE,
-        data=ConfigEvent(feature=CEFeature.PRESETS, action=CEAction.DELETE, data=deleted),
-    )
-    return web.json_response(data=deleted, status=web.HTTPOk.status_code, dumps=encoder.encode)

app/features/presets/schemas.py

@@ -1,97 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any
-
-from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, field_validator
-
-from app.features.core.schemas import Pagination
-from app.features.core.utils import parse_int
-from app.features.presets.utils import preset_name
-from app.library.config import Config
-from app.library.Utils import create_cookies_file
-
-
-class Preset(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    id: int | None = None
-    name: str = Field(min_length=1)
-    description: str = ""
-    folder: str = ""
-    template: str = ""
-    cookies: str = ""
-    cli: str = ""
-    default: bool = False
-    priority: int = 0
-
-    _cookies_file: Path | None = PrivateAttr(default=None)
-
-    @field_validator("name", mode="before")
-    @classmethod
-    def _normalize_name(cls, value: Any) -> str:
-        if not isinstance(value, str):
-            msg: str = "Name must be a string."
-            raise ValueError(msg)
-
-        if not (value := preset_name(value)):
-            msg = "Name cannot be empty."
-            raise ValueError(msg)
-        return value
-
-    @field_validator("priority", mode="before")
-    @classmethod
-    def _normalize_priority(cls, value: Any) -> int:
-        return parse_int(value, field="Priority", minimum=0)
-
-    @field_validator("cli", mode="before")
-    @classmethod
-    def _validate_cli(cls, value: Any) -> str:
-        if not value:
-            return ""
-        if not isinstance(value, str):
-            msg: str = "CLI must be a string."
-            raise ValueError(msg)
-
-        value = value.strip()
-        if not value:
-            return ""
-
-        try:
-            from app.features.ytdlp.utils import arg_converter
-
-            arg_converter(args=value, level=True)
-        except Exception as e:
-            msg = f"Invalid command options for yt-dlp: {e!s}"
-            raise ValueError(msg) from e
-        return value
-
-    def get_cookies_file(self, config: Config | None = None) -> Path | None:
-        if None is not self._cookies_file:
-            return self._cookies_file
-
-        if not self.cookies or self.id is None:
-            return None
-
-        config = config or Config.get_instance()
-        self._cookies_file = create_cookies_file(self.cookies, Path(config.config_path) / "cookies" / f"{self.id}.txt")
-        return self._cookies_file
-
-
-class PresetPatch(Preset):
-    model_config = ConfigDict(str_strip_whitespace=True, from_attributes=True)
-
-    name: str | None = None
-    description: str | None = None
-    folder: str | None = None
-    template: str | None = None
-    cookies: str | None = None
-    cli: str | None = None
-    priority: int | None = None
-
-
-class PresetList(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    items: list[Preset] = Field(default_factory=list)
-    pagination: Pagination

app/features/presets/service.py

@@ -1,44 +0,0 @@
-from __future__ import annotations
-
-from app.features.presets.models import PresetModel
-from app.features.presets.repository import PresetsRepository
-from app.features.presets.schemas import Preset
-from app.features.presets.utils import preset_name
-from app.library.Services import Services
-from app.library.Singleton import Singleton
-
-
-class Presets(metaclass=Singleton):
-    def __init__(self, repo: PresetsRepository | None = None) -> None:
-        self._repo: PresetsRepository = repo or PresetsRepository.get_instance()
-        self._cache: list[tuple[int, str, Preset]] = []
-        Services.get_instance().add(type(self).__name__, self)
-
-    @staticmethod
-    def get_instance() -> Presets:
-        return Presets()
-
-    async def refresh_cache(self, items: list[PresetModel]) -> None:
-        presets = [Preset.model_validate(item) for item in items]
-        self._cache = [(preset.id if preset.id is not None else -1, preset.name, preset) for preset in presets]
-
-    def get_all(self) -> list[Preset]:
-        return [preset for _, _, preset in self._cache]
-
-    def get(self, identifier: int | str) -> Preset | None:
-        if not identifier:
-            return None
-
-        if isinstance(identifier, str) and not (identifier := preset_name(identifier)):
-            return None
-
-        for id, name, preset in self._cache:
-            if isinstance(identifier, int) and id == identifier:
-                return preset
-            if isinstance(identifier, str) and name == identifier:
-                return preset
-
-        return None
-
-    def has(self, identifier: int | str) -> bool:
-        return self.get(identifier) is not None

app/features/presets/tests/test_presets_repository.py

@@ -1,179 +0,0 @@
-from __future__ import annotations
-
-import json
-from unittest.mock import MagicMock
-
-import pytest
-import pytest_asyncio
-from aiohttp import web
-from aiohttp.web import Request
-
-from app.features.presets.repository import PresetsRepository
-from app.features.presets.router import presets_list
-from app.library.encoder import Encoder
-from app.library.sqlite_store import SqliteStore
-from app.tests.helpers import make_in_memory_db_path
-
-
-@pytest_asyncio.fixture
-async def repo():
-    PresetsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-    store = SqliteStore(db_path=make_in_memory_db_path("presets-repository"))
-    await store.get_connection()
-
-    repository = PresetsRepository.get_instance()
-    yield repository
-
-    await store.close()
-
-    PresetsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-
-class TestPresetsRepository:
-    @pytest.mark.asyncio
-    async def test_create_and_get(self, repo):
-        preset = await repo.create({"name": "Custom", "cli": "--format best"})
-
-        assert preset.id is not None, "Should generate ID for new preset"
-        assert preset.name == "custom", "Should normalize preset name"
-        assert preset.cli == "--format best", "Should store preset cli"
-
-        fetched = await repo.get(preset.id)
-        assert fetched is not None, "Should fetch preset by id"
-        assert fetched.name == "custom", "Should return matching preset"
-
-    @pytest.mark.asyncio
-    async def test_create_normalizes_spaces(self, repo):
-        preset = await repo.create({"name": "My Preset"})
-
-        assert preset.name == "my_preset", "Should normalize spaces to underscores"
-
-    @pytest.mark.asyncio
-    async def test_list_orders_by_priority_then_name(self, repo):
-        await repo.create({"name": "B", "priority": 1})
-        await repo.create({"name": "A", "priority": 1})
-        await repo.create({"name": "C", "priority": 2})
-
-        items = await repo.all()
-
-        assert items[0].name == "c", "Highest priority should be first"
-        assert items[1].name == "a", "Same priority should sort by name"
-        assert items[2].name == "b", "Same priority should sort by name"
-
-    @pytest.mark.asyncio
-    async def test_list_paginated(self, repo):
-        for i in range(5):
-            await repo.create({"name": f"Item {i}", "priority": i})
-
-        items, total, page, total_pages = await repo.list_paginated(page=1, per_page=2)
-
-        assert len(items) == 2, "Should return 2 items per page"
-        assert total == 5, "Should report total count"
-        assert page == 1, "Should be on page 1"
-        assert total_pages == 3, "Should have 3 pages total"
-        assert [item.priority for item in items] == [4, 3], "Should keep default priority-desc order"
-
-    @pytest.mark.asyncio
-    async def test_list_paginated_sorts_by_name_desc(self, repo):
-        await repo.create({"name": "Alpha", "priority": 1})
-        await repo.create({"name": "Gamma", "priority": 3})
-        await repo.create({"name": "Beta", "priority": 2})
-
-        items, _, _, _ = await repo.list_paginated(page=1, per_page=10, sort="name", order="desc")
-
-        assert [item.name for item in items] == ["gamma", "beta", "alpha"], "Should sort by requested field"
-
-    @pytest.mark.asyncio
-    async def test_list_paginated_excludes_defaults(self, repo):
-        await repo.create({"name": "System Default", "default": True, "priority": 10})
-        await repo.create({"name": "Custom Preset", "priority": 1})
-
-        items, total, page, total_pages = await repo.list_paginated(page=1, per_page=10, exclude_defaults=True)
-
-        assert [item.name for item in items] == ["custom_preset"], "Should exclude default presets"
-        assert total == 1, "Should count only custom presets"
-        assert page == 1, "Should keep current page when filtered results exist"
-        assert total_pages == 1, "Should compute pages from the filtered total"
-
-    @pytest.mark.asyncio
-    async def test_list_paginated_multi_sort(self, repo):
-        await repo.create({"name": "Charlie", "priority": 2})
-        await repo.create({"name": "Alpha", "priority": 1})
-        await repo.create({"name": "Bravo", "priority": 1})
-
-        items, _, _, _ = await repo.list_paginated(page=1, per_page=10, sort="priority,name", order="asc,desc")
-
-        assert [(item.priority, item.name) for item in items] == [
-            (1, "bravo"),
-            (1, "alpha"),
-            (2, "charlie"),
-        ], "Should support multiple sort fields and directions"
-
-    @pytest.mark.asyncio
-    async def test_list_paginated_bad_sort(self, repo):
-        with pytest.raises(ValueError, match="sort must use supported fields"):
-            await repo.list_paginated(page=1, per_page=10, sort="cli", order="asc")
-
-    @pytest.mark.asyncio
-    async def test_list_paginated_bad_order(self, repo):
-        with pytest.raises(ValueError, match="order must be 'asc' or 'desc'"):
-            await repo.list_paginated(page=1, per_page=10, sort="name", order="sideways")
-
-    @pytest.mark.asyncio
-    async def test_list_paginated_mismatched_order(self, repo):
-        with pytest.raises(ValueError, match="order must provide one direction or match the number of sort fields"):
-            await repo.list_paginated(page=1, per_page=10, sort="priority,name", order="asc,desc,asc")
-
-
-@pytest.mark.asyncio
-class TestPresetRoutes:
-    async def test_list_route_sort(self, repo):
-        await repo.create({"name": "Alpha", "priority": 1})
-        await repo.create({"name": "Bravo", "priority": 1})
-        await repo.create({"name": "Charlie", "priority": 2})
-
-        request = MagicMock(spec=Request)
-        request.query = {"page": "1", "per_page": "10", "sort": "priority,name", "order": "asc,desc"}
-
-        response = await presets_list(request, Encoder(), repo)
-        payload = json.loads(response.text)
-
-        assert response.status == web.HTTPOk.status_code, "Should return 200 for valid sorting"
-        assert [item["name"] for item in payload["items"]] == ["bravo", "alpha", "charlie"], "Should sort response"
-
-    async def test_list_route_bad_sort(self, repo):
-        request = MagicMock(spec=Request)
-        request.query = {"sort": "cli", "order": "asc"}
-
-        response = await presets_list(request, Encoder(), repo)
-        payload = json.loads(response.text)
-
-        assert response.status == web.HTTPBadRequest.status_code, "Should reject unsupported sort field"
-        assert "sort" in payload["error"], "Should explain invalid sort field"
-
-    async def test_list_route_bad_order(self, repo):
-        request = MagicMock(spec=Request)
-        request.query = {"sort": "name", "order": "sideways"}
-
-        response = await presets_list(request, Encoder(), repo)
-        payload = json.loads(response.text)
-
-        assert response.status == web.HTTPBadRequest.status_code, "Should reject unsupported sort direction"
-        assert "order" in payload["error"], "Should explain invalid sort direction"
-
-    async def test_list_route_exclude_defaults(self, repo):
-        await repo.create({"name": "System Default", "default": True, "priority": 10})
-        await repo.create({"name": "Custom Preset", "priority": 1})
-
-        request = MagicMock(spec=Request)
-        request.query = {"page": "1", "per_page": "10", "exclude_defaults": "true"}
-
-        response = await presets_list(request, Encoder(), repo)
-        payload = json.loads(response.text)
-
-        assert response.status == web.HTTPOk.status_code, "Should return 200 for valid default exclusion"
-        assert [item["name"] for item in payload["items"]] == ["custom_preset"], "Should exclude default presets"
-        assert payload["pagination"]["total"] == 1, "Should report filtered total"

app/features/presets/utils.py

@@ -1,60 +0,0 @@
-import re
-from datetime import UTC, datetime
-
-from app.library.log import get_logger
-
-NAME_WHITESPACE_PATTERN = re.compile(r"\s+")
-
-LOG = get_logger()
-
-
-async def seed_defaults(repo) -> None:
-    from .defaults import DEFAULT_PRESETS
-
-    for preset in DEFAULT_PRESETS:
-        try:
-            name = preset.get("name")
-            if not name or not isinstance(name, str):
-                LOG.warning("Skipping default preset with invalid name: %s", preset)
-                continue
-
-            if not (name := preset_name(name)):
-                LOG.warning("Skipping default preset with empty normalized name: %s", name)
-                continue
-
-            payload = {**preset}
-            payload.pop("id", None)
-            payload["default"] = True
-            payload["name"] = name
-
-            updated_at_value: datetime | None = None
-            updated_at_raw = payload.get("updated_at")
-            if isinstance(updated_at_raw, str):
-                updated_at_value = datetime.fromisoformat(updated_at_raw)
-            elif isinstance(updated_at_raw, datetime):
-                updated_at_value = updated_at_raw
-            if isinstance(updated_at_value, datetime) and updated_at_value.tzinfo is None:
-                updated_at_value = updated_at_value.replace(tzinfo=UTC)
-            payload["updated_at"] = updated_at_value
-
-            existing = await repo.get_by_name(name)
-            if None is existing:
-                await repo.create(payload)
-                continue
-
-            if existing.updated_at and updated_at_value and existing.updated_at >= updated_at_value:
-                if False is existing.default:
-                    await repo.update(existing.id, {"default": True})
-                continue
-
-            await repo.update(existing.id, payload)
-        except Exception as exc:
-            LOG.exception(
-                "Failed to seed default preset '%s'.",
-                preset.get("name"),
-                extra={"preset": preset.get("name"), "exception_type": type(exc).__name__},
-            )
-
-
-def preset_name(value: str) -> str:
-    return NAME_WHITESPACE_PATTERN.sub("_", value.strip().lower())

app/features/streaming/library/subtitle.py

@@ -1,155 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-import anyio
-import pysubs2
-from pysubs2.formats.substation import SubstationFormat
-from pysubs2.time import ms_to_times
-
-from app.library.log import get_logger
-from app.library.Utils import ALLOWED_SUBS_EXTENSIONS, get_file_sidecar
-
-LOG = get_logger()
-
-SOURCE_FORMATS: tuple[str, ...] = ("vtt", "srt", "ass")
-DELIVERY_FORMATS: dict[str, str] = {
-    "vtt": "vtt",
-    "srt": "vtt",
-    "ass": "ass",
-}
-RENDERERS: dict[str, str] = {
-    "vtt": "native",
-    "srt": "native",
-    "ass": "assjs",
-}
-MEDIA_TYPES: dict[str, str] = {
-    "vtt": "text/vtt; charset=UTF-8",
-    "ass": "text/x-ssa; charset=UTF-8",
-}
-TEXT_ENCODINGS: tuple[str, ...] = ("utf-8-sig", "utf-16", "utf-16-le", "utf-16-be", "cp1252")
-
-
-@dataclass(frozen=True, slots=True)
-class SubtitleTrack:
-    file: Path
-    lang: str
-    name: str
-    source_format: str
-    delivery_format: str
-    renderer: str
-
-
-def ms_to_timestamp(ms: int) -> str:
-    ms = max(0, ms)
-    h, m, s, ms = ms_to_times(ms)
-    cs: int = ms // 10
-    return f"{h:01d}:{m:02d}:{s:02d}.{cs:02d}"
-
-
-_substation_format: Any = SubstationFormat
-_substation_format.ms_to_timestamp = ms_to_timestamp
-
-
-class Subtitle:
-    @staticmethod
-    def normalize_format(source_format: str) -> str | None:
-        fmt = source_format.strip().lower().removeprefix(".")
-        if fmt not in SOURCE_FORMATS:
-            return None
-
-        return fmt
-
-    async def read_text(self, file: Path) -> str:
-        async with await anyio.open_file(file, "rb") as f:
-            subtitle_bytes = await f.read()
-
-        return self.decode_bytes(subtitle_bytes)
-
-    @staticmethod
-    def decode_bytes(subtitle_bytes: bytes) -> str:
-        for encoding in TEXT_ENCODINGS:
-            try:
-                return subtitle_bytes.decode(encoding)
-            except UnicodeDecodeError:
-                continue
-
-        return subtitle_bytes.decode("utf-8", errors="replace")
-
-    def media_type(self, file: Path) -> str:
-        fmt = self.normalize_format(file.suffix)
-        if fmt is None:
-            msg = f"File '{file}' subtitle type is not supported."
-            raise Exception(msg)
-
-        return MEDIA_TYPES[DELIVERY_FORMATS[fmt]]
-
-    async def make(self, file: Path) -> str:
-        fmt = self.normalize_format(file.suffix)
-        if fmt is None or file.suffix not in ALLOWED_SUBS_EXTENSIONS:
-            msg: str = f"File '{file}' subtitle type is not supported."
-            raise Exception(msg)
-
-        if fmt == "vtt":
-            return await self.read_text(file)
-
-        subs: pysubs2.SSAFile = pysubs2.load(path=str(file))
-
-        if len(subs.events) < 1:
-            msg = f"No subtitle events were found in '{file}'."
-            raise Exception(msg)
-
-        if len(subs.events) < 2:
-            return subs.to_string("vtt")
-
-        try:
-            if subs.events[0].end == subs.events[len(subs.events) - 1].end:
-                subs.events.pop(0)
-        except Exception:
-            pass
-
-        return subs.to_string("vtt")
-
-    async def make_delivery(self, file: Path) -> tuple[str, str]:
-        fmt = self.normalize_format(file.suffix)
-        if fmt is None or file.suffix not in ALLOWED_SUBS_EXTENSIONS:
-            msg: str = f"File '{file}' subtitle type is not supported."
-            raise Exception(msg)
-
-        if fmt == "ass":
-            return await self.read_text(file), self.media_type(file)
-
-        return await self.make(file), self.media_type(file)
-
-
-def get_subtitle_tracks(file: Path) -> list[SubtitleTrack]:
-    sidecars = get_file_sidecar(file).get("subtitle", [])
-    indexed_tracks: list[tuple[int, SubtitleTrack]] = []
-
-    for index, item in enumerate(sidecars):
-        track_file = item.get("file")
-        if not isinstance(track_file, Path):
-            continue
-
-        fmt = Subtitle.normalize_format(track_file.suffix)
-        if fmt is None:
-            continue
-
-        indexed_tracks.append(
-            (
-                index,
-                SubtitleTrack(
-                    file=track_file,
-                    lang=str(item.get("lang") or "und"),
-                    name=str(item.get("name") or track_file.name),
-                    source_format=fmt,
-                    delivery_format=DELIVERY_FORMATS[fmt],
-                    renderer=RENDERERS[fmt],
-                ),
-            )
-        )
-
-    indexed_tracks.sort(key=lambda item: (SOURCE_FORMATS.index(item[1].source_format), item[0]))
-    return [track for _, track in indexed_tracks]

app/features/streaming/library/thumbnail.py

@@ -1,284 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import os
-import subprocess
-from pathlib import Path
-
-from app.features.streaming.library.ffprobe import ffprobe
-from app.library.cache import Cache
-from app.library.config import Config
-from app.library.log import get_logger
-from app.library.Utils import FILES_TYPE, get_file_sidecar
-
-LOG = get_logger()
-
-IMAGE_TYPES: tuple[str, ...] = (".jpg", ".jpeg", ".png", ".webp")
-FOLDER_IMAGE_ORDER: tuple[str, ...] = ("thumbnail", "poster", "artwork", "cover", "fanart")
-THUMBNAIL_SAMPLE_FRAMES = 200
-THUMBNAIL_DEFAULT_SEEK_SECONDS = 3.0
-THUMBNAIL_MIN_SEEK_SECONDS = 1.0
-THUMBNAIL_MAX_SEEK_SECONDS = 15.0
-THUMBNAIL_END_MARGIN_SECONDS = 0.1
-THUMBNAIL_MISS_TTL = 3600.0
-
-_LOCK = asyncio.Lock()
-_IN_PROCESS: dict[str, asyncio.Task[Path | None]] = {}
-
-
-_SEM: asyncio.Semaphore | None = None
-_SEM_LIMIT: int | None = None
-
-
-def _get_semaphore() -> asyncio.Semaphore:
-    global _SEM, _SEM_LIMIT  # noqa: PLW0603
-
-    limit: int = max(1, int(Config.get_instance().thumb_concurrency))
-    if _SEM is None or _SEM_LIMIT != limit:
-        _SEM = asyncio.Semaphore(limit)
-        _SEM_LIMIT = limit
-        LOG.info("Configured thumbnail generation to run %s job(s) at a time.", limit, extra={"limit": limit})
-
-    return _SEM
-
-
-def _is_same_stem_image(media_file: Path, image_file: Path) -> bool:
-    if image_file.parent != media_file.parent:
-        return False
-
-    for image_type in FILES_TYPE:
-        if "image" != image_type.get("type"):
-            continue
-
-        rx = image_type.get("rx")
-        if rx and rx.search(image_file.name):
-            break
-    else:
-        return False
-
-    return image_file.stem == media_file.stem
-
-
-def pick_local_thumb(media_file: Path) -> Path | None:
-    sidecar: dict[str, list[dict[str, str]]] = get_file_sidecar(media_file)
-    images: list[dict[str, str]] = sidecar.get("image", [])
-    local_images: list[Path] = [Path(item["file"]) for item in images if isinstance(item.get("file"), Path)]
-
-    for image_file in local_images:
-        if image_file.suffix.lower() in IMAGE_TYPES and _is_same_stem_image(media_file, image_file):
-            return image_file
-
-    by_name: dict[str, Path] = {
-        image_file.stem.lower(): image_file for image_file in local_images if image_file.suffix.lower() in IMAGE_TYPES
-    }
-    for name in FOLDER_IMAGE_ORDER:
-        if image_file := by_name.get(name):
-            return image_file
-
-    return None
-
-
-def _seek_seconds(ff_info) -> float | None:
-    duration: float = 0.0
-    try:
-        duration = float(ff_info.metadata.get("duration") or 0.0)
-    except (TypeError, ValueError):
-        duration = 0.0
-
-    if duration <= 0:
-        return THUMBNAIL_DEFAULT_SEEK_SECONDS
-
-    if duration <= THUMBNAIL_END_MARGIN_SECONDS:
-        return None
-
-    return min(
-        max(duration * 0.10, THUMBNAIL_MIN_SEEK_SECONDS),
-        THUMBNAIL_MAX_SEEK_SECONDS,
-        duration - THUMBNAIL_END_MARGIN_SECONDS,
-    )
-
-
-def _build_ffmpeg_args(media_file: Path, output_file: Path, *, seek_seconds: float | None) -> list[str]:
-    args: list[str] = [
-        "ffmpeg",
-        "-nostdin",
-        "-hide_banner",
-        "-loglevel",
-        "error",
-        "-y",
-    ]
-
-    if seek_seconds is not None and seek_seconds > 0:
-        args.extend(["-ss", f"{seek_seconds:.3f}"])
-
-    args.extend(
-        [
-            "-i",
-            str(media_file),
-            "-vf",
-            f"thumbnail={THUMBNAIL_SAMPLE_FRAMES},scale=1280:-1:force_original_aspect_ratio=decrease",
-            "-frames:v",
-            "1",
-            "-q:v",
-            "3",
-            "-an",
-            str(output_file),
-        ]
-    )
-    return args
-
-
-async def _run_ffmpeg(media_file: Path, output_file: Path) -> Path | None:
-    ff_info = await ffprobe(media_file)
-    if not ff_info.has_video():
-        LOG.debug(
-            "Skipping thumbnail generation for '%s' because no video stream exists.",
-            media_file,
-            extra={"media_file": str(media_file)},
-        )
-        return None
-
-    output_file.parent.mkdir(parents=True, exist_ok=True)
-    temp_file = output_file.with_suffix(".tmp.jpg")
-
-    if temp_file.exists():
-        temp_file.unlink(missing_ok=True)
-
-    seek_seconds: float | None = _seek_seconds(ff_info)
-    attempts: list[float | None] = [seek_seconds]
-    if seek_seconds is not None and seek_seconds > 0:
-        attempts.append(None)
-
-    sem = _get_semaphore()
-    if sem.locked():
-        limit = _SEM_LIMIT or 1
-        LOG.debug(
-            "Waiting for a thumbnail generation slot for '%s' (limit=%s).",
-            media_file,
-            limit,
-            extra={"media_file": str(media_file), "limit": limit},
-        )
-
-    async with sem:
-        last_error: str = "ffmpeg produced an empty thumbnail file"
-        for idx, attempt_seek in enumerate(attempts, start=1):
-            temp_file.unlink(missing_ok=True)
-            args: list[str] = _build_ffmpeg_args(media_file, temp_file, seek_seconds=attempt_seek)
-            LOG.debug(
-                "Generating thumbnail for '%s'. attempt=%s/%s seek=%s",
-                media_file,
-                idx,
-                len(attempts),
-                "none" if attempt_seek is None else f"{attempt_seek:.3f}s",
-                extra={
-                    "media_file": str(media_file),
-                    "attempt": idx,
-                    "attempt_count": len(attempts),
-                    "seek": "none" if attempt_seek is None else f"{attempt_seek:.3f}s",
-                },
-            )
-
-            try:
-                proc = await asyncio.create_subprocess_exec(
-                    *args,
-                    stdout=asyncio.subprocess.PIPE,
-                    stderr=asyncio.subprocess.PIPE,
-                    creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0,
-                )
-            except FileNotFoundError as exc:
-                msg = "ffmpeg not found."
-                raise OSError(msg) from exc
-
-            stdout, stderr = await proc.communicate()
-            if 0 == proc.returncode and temp_file.exists() and temp_file.stat().st_size > 0:
-                temp_file.replace(output_file)
-                LOG.info(
-                    "Generated thumbnail '%s' for '%s'.",
-                    output_file,
-                    media_file,
-                    extra={"media_file": str(media_file), "output_file": str(output_file)},
-                )
-                return output_file
-
-            if 0 != proc.returncode:
-                last_error: str = (
-                    f"ffmpeg thumbnail generation failed (rc={proc.returncode}).\n"
-                    f"stdout:\n{stdout.decode('utf-8', errors='replace')}\n"
-                    f"stderr:\n{stderr.decode('utf-8', errors='replace')}"
-                )
-            else:
-                last_error: str = "ffmpeg produced an empty thumbnail file"
-
-            LOG.debug(
-                "Thumbnail generation attempt failed for '%s'. seek=%s",
-                media_file,
-                "none" if attempt_seek is None else f"{attempt_seek:.3f}s",
-                extra={
-                    "media_file": str(media_file),
-                    "seek": "none" if attempt_seek is None else f"{attempt_seek:.3f}s",
-                },
-            )
-
-    temp_file.unlink(missing_ok=True)
-    raise OSError(last_error)
-
-
-async def ensure_thumb(media_file: Path, cache_root: Path, item_id: str | None = None) -> Path | None:
-    config: Config = Config.get_instance()
-    cache: Cache = Cache.get_instance()
-    if bool(config.thumb_generate) is not True:
-        return None
-
-    sidecar: bool = bool(config.thumb_sidecar)
-    if not sidecar and not item_id:
-        msg = "item_id is required when thumbnail sidecar is disabled."
-        raise ValueError(msg)
-
-    thumb_id: str = str(media_file.resolve()) if sidecar else str(item_id)
-    cache_file: Path = media_file.with_name(f"{media_file.name}.jpg") if sidecar else cache_root / f"{item_id}.jpg"
-
-    miss_key: str = f"thumbnail-miss:{thumb_id}"
-
-    if cache_file.exists() and cache_file.stat().st_size > 0:
-        cache.delete(miss_key)
-        return cache_file
-
-    if cache.has(miss_key):
-        return None
-
-    async with _LOCK:
-        if cache_file.exists() and cache_file.stat().st_size > 0:
-            cache.delete(miss_key)
-            return cache_file
-
-        if cache.has(miss_key):
-            return None
-
-        task = _IN_PROCESS.get(thumb_id)
-        if task is not None and not task.done():
-            LOG.debug("Waiting for thumbnail generation for '%s'.", media_file, extra={"media_file": str(media_file)})
-        else:
-            task = asyncio.create_task(_run_ffmpeg(media_file, cache_file), name=f"thumb-{item_id or media_file.stem}")
-            _IN_PROCESS[thumb_id] = task
-            LOG.debug(
-                "Starting thumbnail generation for '%s' -> '%s'.",
-                media_file,
-                cache_file,
-                extra={"media_file": str(media_file), "cache_file": str(cache_file)},
-            )
-
-    try:
-        result: Path | None = await task
-        if result is None:
-            cache.set(miss_key, value=True, ttl=THUMBNAIL_MISS_TTL)
-        else:
-            cache.delete(miss_key)
-        return result
-    except OSError:
-        cache.set(miss_key, value=True, ttl=THUMBNAIL_MISS_TTL)
-        raise
-    finally:
-        async with _LOCK:
-            current = _IN_PROCESS.get(thumb_id)
-            if current is task and task.done():
-                _IN_PROCESS.pop(thumb_id, None)

app/features/streaming/router.py

@@ -1,420 +0,0 @@
-import time
-from datetime import UTC, datetime
-from pathlib import Path
-
-from aiohttp import web
-from aiohttp.web import Request, Response
-from aiohttp.web_response import StreamResponse
-
-from app.features.streaming.library.m3u8 import M3u8
-from app.features.streaming.library.playlist import Playlist
-from app.features.streaming.library.segments import Segments
-from app.features.streaming.library.subtitle import Subtitle, get_subtitle_tracks
-from app.features.streaming.types import StreamingError
-from app.library.config import Config
-from app.library.log import get_logger
-from app.library.router import route
-from app.library.Utils import get_file
-
-LOG = get_logger()
-
-
-@route("GET", "api/player/playlist/{file:.*}.m3u8", "playlist_create")
-async def playlist_create(request: Request, config: Config, app: web.Application) -> Response:
-    """
-    Get the playlist.
-
-    Args:
-        request (Request): The request object.
-        config (Config): The configuration instance.
-        app (web.Application): The aiohttp application instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    file: str | None = request.match_info.get("file")
-
-    if not file:
-        return web.json_response(data={"error": "file is required"}, status=web.HTTPBadRequest.status_code)
-
-    base_path: str = config.base_path.rstrip("/")
-
-    try:
-        realFile, status = get_file(download_path=config.download_path, file=file)
-        if web.HTTPFound.status_code == status:
-            return Response(
-                status=web.HTTPFound.status_code,
-                headers={
-                    "Location": str(
-                        app.router["playlist_create"].url_for(
-                            file=str(realFile).replace(config.download_path, "").strip("/")
-                        )
-                    ),
-                },
-            )
-
-        if web.HTTPNotFound.status_code == status:
-            return web.json_response(data={"error": f"File '{file}' does not exist."}, status=status)
-
-        return web.Response(
-            text=await Playlist(download_path=Path(config.download_path), url=f"{base_path}/").make(file=realFile),
-            headers={
-                "Content-Type": "application/x-mpegURL",
-                "Cache-Control": "no-cache",
-                "Access-Control-Max-Age": "300",
-            },
-            status=web.HTTPOk.status_code,
-        )
-    except StreamingError as e:
-        return web.json_response(data={"error": str(e)}, status=web.HTTPNotFound.status_code)
-
-
-@route("GET", "api/player/m3u8/{mode}/{file:.*}.m3u8", "m3u8_create")
-async def m3u8_create(request: Request, config: Config, app: web.Application) -> Response:
-    """
-    Get the m3u8 file.
-
-    Args:
-        request (Request): The request object.
-        config (Config): The configuration instance.
-        app (web.Application): The aiohttp application instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    file: str | None = request.match_info.get("file")
-    mode: str | None = request.match_info.get("mode")
-
-    if mode not in ["video", "subtitle"]:
-        return web.json_response(
-            data={"error": "Only video and subtitle modes are supported."}, status=web.HTTPBadRequest.status_code
-        )
-
-    if not file:
-        return web.json_response(data={"error": "file is required"}, status=web.HTTPBadRequest.status_code)
-
-    duration: float | None = None
-    duration_arg = request.query.get("duration", None)
-
-    if "subtitle" in mode:
-        if not duration_arg:
-            return web.json_response(data={"error": "duration is required."}, status=web.HTTPBadRequest.status_code)
-
-        duration = float(duration_arg)
-
-    base_path: str = config.base_path.rstrip("/")
-
-    try:
-        cls = M3u8(download_path=Path(config.download_path), url=f"{base_path}/")
-
-        realFile, status = get_file(download_path=config.download_path, file=file)
-        if web.HTTPFound.status_code == status:
-            return Response(
-                status=status,
-                headers={
-                    "Location": str(
-                        app.router["m3u8_create"].url_for(
-                            mode=mode, file=str(realFile).replace(config.download_path, "").strip("/")
-                        )
-                    ),
-                },
-            )
-
-        if web.HTTPNotFound.status_code == status:
-            return web.json_response(data={"error": f"File '{file}' does not exist."}, status=status)
-
-        if "subtitle" in mode:
-            if duration is None:
-                return web.json_response(data={"error": "duration is required."}, status=web.HTTPBadRequest.status_code)
-            text = await cls.make_subtitle(file=realFile, duration=duration)
-        else:
-            text = await cls.make_stream(file=realFile)
-    except StreamingError as e:
-        LOG.exception(
-            "Failed to create %s streaming playlist for '%s': %s.",
-            mode,
-            file,
-            e,
-            extra={"route": "streaming.playlist", "file_path": file, "mode": mode, "exception_type": type(e).__name__},
-        )
-        return web.json_response(data={"error": str(e)}, status=web.HTTPNotFound.status_code)
-
-    return web.Response(
-        text=text,
-        headers={
-            "Content-Type": "application/x-mpegURL",
-            "Cache-Control": "no-cache",
-            "Access-Control-Max-Age": "300",
-        },
-        status=web.HTTPOk.status_code,
-    )
-
-
-@route("GET", r"api/player/segments/{segment:\d+}/{file:.*}.ts", "segments_stream")
-async def segments_stream(request: Request, config: Config, app: web.Application) -> StreamResponse:
-    """
-    Get the segments.
-
-    Args:
-        request (Request): The request object.
-        config (Config): The configuration instance.
-        app (web.Application): The aiohttp application instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    file: str | None = request.match_info.get("file")
-    segment: str | None = request.match_info.get("segment")
-    sd: str | None = request.query.get("sd")
-    vc: int = int(request.query.get("vc", 0))
-    ac: int = int(request.query.get("ac", 0))
-
-    if not file:
-        return web.json_response(data={"error": "file is required"}, status=web.HTTPBadRequest.status_code)
-
-    if not segment:
-        return web.json_response(data={"error": "segment id is required."}, status=web.HTTPBadRequest.status_code)
-
-    realFile, status = get_file(download_path=config.download_path, file=file)
-    if web.HTTPFound.status_code == status:
-        return Response(
-            status=status,
-            headers={
-                "Location": str(
-                    app.router["segments_stream"].url_for(
-                        segment=segment,
-                        file=str(realFile).replace(config.download_path, "").strip("/"),
-                    )
-                ),
-            },
-        )
-
-    if web.HTTPNotFound.status_code == status:
-        return web.json_response(data={"error": f"File '{file}' does not exist."}, status=status)
-
-    mtime = realFile.stat().st_mtime
-
-    if request.if_modified_since and request.if_modified_since.timestamp() == mtime:
-        lastMod = time.strftime("%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(mtime, tz=UTC).timetuple())
-        return web.Response(status=web.HTTPNotModified.status_code, headers={"Last-Modified": lastMod})
-
-    resp = web.StreamResponse(
-        status=web.HTTPOk.status_code,
-        headers={
-            "Content-Type": "video/mpegts",
-            "X-Accel-Buffering": "no",
-            "Access-Control-Allow-Origin": "*",
-            "Pragma": "public",
-            "Cache-Control": f"public, max-age={time.time() + 31536000}",
-            "Last-Modified": time.strftime(
-                "%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(mtime, tz=UTC).timetuple()
-            ),
-            "Expires": time.strftime(
-                "%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(time.time() + 31536000, tz=UTC).timetuple()
-            ),
-        },
-    )
-
-    await resp.prepare(request)
-
-    await Segments(
-        download_path=config.download_path,
-        index=int(segment),
-        duration=float(f"{float(sd or M3u8.duration):.6f}"),
-        vconvert=vc == 1,
-        aconvert=ac == 1,
-    ).stream(realFile, resp)
-
-    return resp
-
-
-@route("GET", "api/player/subtitle/{file:.*}.vtt", "subtitles_get")
-async def subtitles_get(request: Request, config: Config, app: web.Application) -> Response:
-    """
-    Get the subtitles.
-
-    Args:
-        request (Request): The request object.
-        config (Config): The configuration instance.
-        app (web.Application): The aiohttp application instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    file: str | None = request.match_info.get("file")
-
-    if not file:
-        return web.json_response(data={"error": "file is required"}, status=web.HTTPBadRequest.status_code)
-
-    realFile, status = get_file(download_path=config.download_path, file=file)
-    if web.HTTPFound.status_code == status:
-        return Response(
-            status=status,
-            headers={
-                "Location": str(
-                    app.router["subtitles_get"].url_for(file=str(realFile).replace(config.download_path, "").strip("/"))
-                ),
-            },
-        )
-
-    if web.HTTPNotFound.status_code == status:
-        return web.json_response(data={"error": f"File '{file}' does not exist."}, status=status)
-
-    mtime = realFile.stat().st_mtime
-
-    if request.if_modified_since and request.if_modified_since.timestamp() == mtime:
-        lastMod = time.strftime("%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(mtime, tz=UTC).timetuple())
-        return web.Response(status=web.HTTPNotModified.status_code, headers={"Last-Modified": lastMod})
-
-    return web.Response(
-        body=await Subtitle().make(file=realFile),
-        headers={
-            "Content-Type": "text/vtt; charset=UTF-8",
-            "X-Accel-Buffering": "no",
-            "Access-Control-Allow-Origin": "*",
-            "Pragma": "public",
-            "Cache-Control": f"public, max-age={time.time() + 31536000}",
-            "Last-Modified": time.strftime(
-                "%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(mtime, tz=UTC).timetuple()
-            ),
-            "Expires": time.strftime(
-                "%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(time.time() + 31536000, tz=UTC).timetuple()
-            ),
-        },
-        status=web.HTTPOk.status_code,
-    )
-
-
-@route("GET", "api/player/subtitles/manifest/{file:.*}", "subtitles_manifest_get")
-async def subtitles_manifest_get(request: Request, config: Config, app: web.Application) -> Response:
-    """
-    Get subtitle track metadata for a media file.
-
-    Args:
-        request (Request): The request object.
-        config (Config): The configuration instance.
-        app (web.Application): The aiohttp application instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    file: str | None = request.match_info.get("file")
-
-    if not file:
-        return web.json_response(data={"error": "file is required"}, status=web.HTTPBadRequest.status_code)
-
-    realFile, status = get_file(download_path=config.download_path, file=file)
-    if web.HTTPFound.status_code == status:
-        return Response(
-            status=status,
-            headers={
-                "Location": str(
-                    app.router["subtitles_manifest_get"].url_for(
-                        file=str(realFile).replace(config.download_path, "").strip("/")
-                    )
-                ),
-            },
-        )
-
-    if web.HTTPNotFound.status_code == status:
-        return web.json_response(data={"error": f"File '{file}' does not exist."}, status=status)
-
-    tracks = [
-        {
-            "lang": track.lang,
-            "name": track.name,
-            "source_format": track.source_format,
-            "delivery_format": track.delivery_format,
-            "renderer": track.renderer,
-            "url": str(
-                app.router["subtitles_track_get"].url_for(
-                    source_format=track.source_format,
-                    file=str(track.file).replace(config.download_path, "").strip("/"),
-                )
-            ),
-        }
-        for track in get_subtitle_tracks(realFile)
-    ]
-
-    return web.json_response(data={"subtitles": tracks}, status=web.HTTPOk.status_code)
-
-
-@route("GET", "api/player/subtitles/{source_format}/{file:.*}", "subtitles_track_get")
-async def subtitles_track_get(request: Request, config: Config, app: web.Application) -> Response:
-    """
-    Get a subtitle file using its preferred delivery format.
-
-    Args:
-        request (Request): The request object.
-        config (Config): The configuration instance.
-        app (web.Application): The aiohttp application instance.
-
-    Returns:
-        Response: The response object.
-
-    """
-    file: str | None = request.match_info.get("file")
-    source_format: str | None = request.match_info.get("source_format")
-
-    if not file:
-        return web.json_response(data={"error": "file is required"}, status=web.HTTPBadRequest.status_code)
-
-    fmt = Subtitle.normalize_format(source_format or "")
-    if fmt is None:
-        return web.json_response(
-            data={"error": "Only vtt, srt, and ass subtitle formats are supported."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    realFile, status = get_file(download_path=config.download_path, file=file)
-    if web.HTTPFound.status_code == status:
-        return Response(
-            status=status,
-            headers={
-                "Location": str(
-                    app.router["subtitles_track_get"].url_for(
-                        source_format=fmt,
-                        file=str(realFile).replace(config.download_path, "").strip("/"),
-                    )
-                ),
-            },
-        )
-
-    if web.HTTPNotFound.status_code == status:
-        return web.json_response(data={"error": f"File '{file}' does not exist."}, status=status)
-
-    if Subtitle.normalize_format(realFile.suffix) != fmt:
-        return web.json_response(
-            data={"error": f"Subtitle file '{file}' does not match requested source format '{fmt}'."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    mtime = realFile.stat().st_mtime
-
-    if request.if_modified_since and request.if_modified_since.timestamp() == mtime:
-        lastMod = time.strftime("%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(mtime, tz=UTC).timetuple())
-        return web.Response(status=web.HTTPNotModified.status_code, headers={"Last-Modified": lastMod})
-
-    body, content_type = await Subtitle().make_delivery(file=realFile)
-    return web.Response(
-        body=body,
-        headers={
-            "Content-Type": content_type,
-            "X-Accel-Buffering": "no",
-            "Access-Control-Allow-Origin": "*",
-            "Pragma": "public",
-            "Cache-Control": f"public, max-age={time.time() + 31536000}",
-            "Last-Modified": time.strftime(
-                "%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(mtime, tz=UTC).timetuple()
-            ),
-            "Expires": time.strftime(
-                "%a, %d %b %Y %H:%M:%S GMT", datetime.fromtimestamp(time.time() + 31536000, tz=UTC).timetuple()
-            ),
-        },
-        status=web.HTTPOk.status_code,
-    )

app/features/streaming/tests/test_subtitle.py

@@ -1,153 +0,0 @@
-from pathlib import Path
-from types import SimpleNamespace
-from unittest.mock import patch
-
-import pytest
-
-from app.features.streaming.library.subtitle import Subtitle, get_subtitle_tracks, ms_to_timestamp
-
-
-class TestMsToTimestamp:
-    def test_ms_to_timestamp_basic(self) -> None:
-        assert ms_to_timestamp(0) == "0:00:00.00"
-        assert ms_to_timestamp(9) == "0:00:00.00"
-        assert ms_to_timestamp(10) == "0:00:00.01"
-        assert ms_to_timestamp(12345) == "0:00:12.34"
-        assert ms_to_timestamp(3600000 + 120000 + 3000) == "1:02:03.00", "1 hour, 2 minutes, 3 seconds"
-        assert ms_to_timestamp(12 * 3600000 + 34 * 60000 + 56 * 1000 + 780) == "12:34:56.78", (
-            "Over 10 hours (SubStation limit is < 10h, our override must exceed)"
-        )
-        assert ms_to_timestamp(37 * 3600000 + 12 * 60000 + 34 * 1000 + 560) == "37:12:34.56", (
-            "Well over 36 hours to ensure no clamping at 9:59:59.99"
-        )
-
-
-@pytest.mark.asyncio
-async def test_make_unsupported_extension(tmp_path: Path) -> None:
-    file = tmp_path / "sub.txt"
-    file.write_text("not a subtitle")
-
-    subtitle = Subtitle()
-    with pytest.raises(Exception, match="subtitle type is not supported"):
-        await subtitle.make(file)
-
-
-@pytest.mark.asyncio
-async def test_make_vtt_reads_file(tmp_path: Path) -> None:
-    vtt = tmp_path / "file.vtt"
-    content = "WEBVTT\n\n00:00:00.00 --> 00:00:01.00\nHello"
-    vtt.write_text(content)
-
-    subtitle = Subtitle()
-    out = await subtitle.make(vtt)
-    assert out == content
-
-
-@pytest.mark.asyncio
-async def test_make_delivery_ass(tmp_path: Path) -> None:
-    ass = tmp_path / "file.ass"
-    content = "[Script Info]\nTitle: Demo\n"
-    ass.write_text(content, encoding="utf-8")
-
-    subtitle = Subtitle()
-    out, media_type = await subtitle.make_delivery(ass)
-    assert out == content
-    assert media_type == "text/x-ssa; charset=UTF-8"
-
-
-def test_tracks_order(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    media = tmp_path / "video.mkv"
-    media.write_text("x", encoding="utf-8")
-    ass_file = tmp_path / "video.ass"
-    ass_file.write_text("ass", encoding="utf-8")
-    vtt_file = tmp_path / "video.vtt"
-    vtt_file.write_text("WEBVTT\n\n", encoding="utf-8")
-    srt_file = tmp_path / "video.en.srt"
-    srt_file.write_text("1\n00:00:00,000 --> 00:00:01,000\nHello\n", encoding="utf-8")
-
-    monkeypatch.setattr(
-        "app.features.streaming.library.subtitle.get_file_sidecar",
-        lambda _file: {
-            "subtitle": [
-                {"file": ass_file, "lang": "en", "name": "ASS"},
-                {"file": srt_file, "lang": "en", "name": "SRT"},
-                {"file": vtt_file, "lang": "en", "name": "VTT"},
-            ]
-        },
-    )
-
-    tracks = get_subtitle_tracks(media)
-
-    assert [track.source_format for track in tracks] == ["vtt", "srt", "ass"]
-    assert [track.delivery_format for track in tracks] == ["vtt", "vtt", "ass"]
-    assert [track.renderer for track in tracks] == ["native", "native", "assjs"]
-
-
-class _DummySubs:
-    def __init__(self, events):
-        self.events = events
-        self.snapshot = None
-
-    def to_string(self, fmt: str) -> str:  # noqa: ARG002
-        # Record end times to verify pop behavior
-        self.snapshot = [e.end for e in self.events]
-        return "OUT"
-
-
-@pytest.mark.asyncio
-async def test_make_no_events_raises(tmp_path: Path) -> None:
-    srt = tmp_path / "sub.srt"
-    srt.write_text("dummy")
-
-    with patch("app.features.streaming.library.subtitle.pysubs2.load") as mock_load:
-        mock_load.return_value = _DummySubs(events=[])
-        subtitle = Subtitle()
-        with pytest.raises(Exception, match="No subtitle events were found"):
-            await subtitle.make(srt)
-
-
-@pytest.mark.asyncio
-async def test_make_single_vtt(tmp_path: Path) -> None:
-    srt = tmp_path / "sub.ass"
-    srt.write_text("dummy")
-
-    single = SimpleNamespace(end=1000)
-    d = _DummySubs(events=[single])
-
-    with patch("app.features.streaming.library.subtitle.pysubs2.load", return_value=d):
-        subtitle = Subtitle()
-        out = await subtitle.make(srt)
-        assert out == "OUT"
-        assert d.snapshot == [1000], "Snapshot should contain the single event"
-
-
-@pytest.mark.asyncio
-async def test_make_two_events_same_end(tmp_path: Path) -> None:
-    srt = tmp_path / "sub.srt"
-    srt.write_text("dummy")
-
-    e1 = SimpleNamespace(end=5000)
-    e2 = SimpleNamespace(end=5000)
-    d = _DummySubs(events=[e1, e2])
-
-    with patch("app.features.streaming.library.subtitle.pysubs2.load", return_value=d):
-        subtitle = Subtitle()
-        out = await subtitle.make(srt)
-        assert out == "OUT"
-        assert d.snapshot == [5000], "Since ends are equal, first should be popped => only last remains"
-
-
-@pytest.mark.asyncio
-async def test_make_two_events_keep_both(tmp_path: Path) -> None:
-    srt = tmp_path / "sub.srt"
-    srt.write_text("dummy")
-
-    e1 = SimpleNamespace(end=5000)
-    e2 = SimpleNamespace(end=6000)
-    d = _DummySubs(events=[e1, e2])
-
-    with patch("app.features.streaming.library.subtitle.pysubs2.load", return_value=d):
-        subtitle = Subtitle()
-        out = await subtitle.make(srt)
-        assert out == "OUT"
-        assert d.snapshot == [5000, 6000], "Both remain since ends differ"

app/features/streaming/tests/test_subtitle_routes.py

@@ -1,132 +0,0 @@
-from pathlib import Path
-from types import SimpleNamespace
-
-import pytest
-from aiohttp import web
-from aiohttp.test_utils import make_mocked_request
-
-from app.features.streaming import router
-from app.library.config import Config
-
-
-class _DummyRoute:
-    def __init__(self, pattern: str) -> None:
-        self.pattern = pattern
-
-    def url_for(self, **params: str) -> str:
-        path = self.pattern
-        for key, value in params.items():
-            path = path.replace(f"{{{key}:.*}}", value)
-            path = path.replace(f"{{{key}}}", value)
-        return path
-
-
-class _DummyRouter(dict[str, _DummyRoute]):
-    def __init__(self) -> None:
-        super().__init__(
-            {
-                "subtitles_manifest_get": _DummyRoute("/api/player/subtitles/manifest/{file:.*}"),
-                "subtitles_track_get": _DummyRoute("/api/player/subtitles/{source_format}/{file:.*}"),
-                "subtitles_get": _DummyRoute("/api/player/subtitle/{file:.*}.vtt"),
-            }
-        )
-
-
-def _make_request(path: str, *, match_info: dict[str, str]) -> web.Request:
-    return make_mocked_request("GET", path, app=SimpleNamespace(router=_DummyRouter()), match_info=match_info)
-
-
-@pytest.mark.asyncio
-async def test_subtitles_manifest_order(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    config = Config.get_instance()
-    config.download_path = str(tmp_path)
-
-    media = tmp_path / "video.mp4"
-    media.write_text("x", encoding="utf-8")
-
-    monkeypatch.setattr(
-        "app.features.streaming.router.get_file",
-        lambda **_kwargs: (media, web.HTTPOk.status_code),
-    )
-    monkeypatch.setattr(
-        "app.features.streaming.router.get_subtitle_tracks",
-        lambda _file: [
-            SimpleNamespace(
-                lang="en",
-                name="English VTT",
-                source_format="vtt",
-                delivery_format="vtt",
-                renderer="native",
-                file=tmp_path / "video.vtt",
-            ),
-            SimpleNamespace(
-                lang="en",
-                name="English ASS",
-                source_format="ass",
-                delivery_format="ass",
-                renderer="assjs",
-                file=tmp_path / "video.ass",
-            ),
-        ],
-    )
-
-    req = _make_request(
-        "/api/player/subtitles/manifest/video.mp4",
-        match_info={"file": "video.mp4"},
-    )
-    response = await router.subtitles_manifest_get(req, config, req.app)
-
-    assert response.status == web.HTTPOk.status_code
-    body = response.text
-    assert '"source_format": "vtt"' in body
-    assert '"renderer": "native"' in body
-    assert '"source_format": "ass"' in body
-    assert '"renderer": "assjs"' in body
-    assert body.index('"source_format": "vtt"') < body.index('"source_format": "ass"')
-
-
-@pytest.mark.asyncio
-async def test_subtitles_track_get_ass(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    config = Config.get_instance()
-    config.download_path = str(tmp_path)
-
-    subtitle = tmp_path / "video.ass"
-    subtitle.write_text("[Script Info]\nTitle: Demo\n", encoding="utf-8")
-
-    monkeypatch.setattr(
-        "app.features.streaming.router.get_file",
-        lambda **_kwargs: (subtitle, web.HTTPOk.status_code),
-    )
-
-    req = _make_request(
-        "/api/player/subtitles/ass/video.ass",
-        match_info={"source_format": "ass", "file": "video.ass"},
-    )
-    response = await router.subtitles_track_get(req, config, req.app)
-
-    assert response.status == web.HTTPOk.status_code
-    assert response.text == "[Script Info]\nTitle: Demo\n"
-    assert response.headers["Content-Type"] == "text/x-ssa; charset=UTF-8"
-
-
-@pytest.mark.asyncio
-async def test_subtitles_track_bad_format(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    config = Config.get_instance()
-    config.download_path = str(tmp_path)
-
-    subtitle = tmp_path / "video.ass"
-    subtitle.write_text("[Script Info]\nTitle: Demo\n", encoding="utf-8")
-
-    monkeypatch.setattr(
-        "app.features.streaming.router.get_file",
-        lambda **_kwargs: (subtitle, web.HTTPOk.status_code),
-    )
-
-    req = _make_request(
-        "/api/player/subtitles/vtt/video.ass",
-        match_info={"source_format": "vtt", "file": "video.ass"},
-    )
-    response = await router.subtitles_track_get(req, config, req.app)
-
-    assert response.status == web.HTTPBadRequest.status_code
-    assert b"does not match requested source format" in response.body

app/features/streaming/tests/test_thumbnail.py

@@ -1,358 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-from pathlib import Path
-from typing import Any
-from unittest.mock import AsyncMock
-
-import pytest
-
-from app.tests.helpers import temporary_test_dir
-
-
-@pytest.mark.asyncio
-async def test_pick_same_stem() -> None:
-    from app.features.streaming.library.thumbnail import pick_local_thumb
-
-    with temporary_test_dir("thumb-local") as temp_dir:
-        media = temp_dir / "video.mp4"
-        poster = temp_dir / "poster.jpg"
-        thumb = temp_dir / "video.jpg"
-
-        media.write_text("video")
-        poster.write_text("poster")
-        thumb.write_text("thumb")
-
-        assert pick_local_thumb(media) == thumb
-
-
-@pytest.mark.asyncio
-async def test_singleflight(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library import thumbnail
-
-    thumbnail._IN_PROCESS.clear()
-    thumbnail.Cache.get_instance().clear()
-
-    with temporary_test_dir("thumb-singleflight") as temp_dir:
-        media = temp_dir / "video.mp4"
-        cache_root = temp_dir / "cache"
-        media.write_text("video")
-        item_id = "item-1"
-
-        calls = {"count": 0}
-
-        async def fake_run_ffmpeg(_file: Path, output_file: Path) -> Path:
-            calls["count"] += 1
-            await asyncio.sleep(0.01)
-            output_file.parent.mkdir(parents=True, exist_ok=True)
-            output_file.write_text("image")
-            return output_file
-
-        monkeypatch.setattr(thumbnail, "_run_ffmpeg", fake_run_ffmpeg)
-
-        first, second = await asyncio.gather(
-            thumbnail.ensure_thumb(media, cache_root, item_id=item_id),
-            thumbnail.ensure_thumb(media, cache_root, item_id=item_id),
-        )
-
-        assert first == second
-        assert first is not None
-        assert calls["count"] == 1
-        assert thumbnail._IN_PROCESS == {}
-
-
-@pytest.mark.asyncio
-async def test_cache_hit(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library import thumbnail
-
-    thumbnail._IN_PROCESS.clear()
-    thumbnail.Cache.get_instance().clear()
-
-    with temporary_test_dir("thumb-cache") as temp_dir:
-        media = temp_dir / "video.mp4"
-        cache_root = temp_dir / "cache"
-        media.write_text("video")
-        item_id = "item-1"
-
-        cache_file = cache_root / f"{item_id}.jpg"
-        cache_file.parent.mkdir(parents=True, exist_ok=True)
-        cache_file.write_text("image")
-
-        async def fake_run_ffmpeg(_file: Path, _output_file: Path) -> Path:
-            raise AssertionError("ffmpeg should not run when cache exists")
-
-        monkeypatch.setattr(thumbnail, "_run_ffmpeg", fake_run_ffmpeg)
-
-        result = await thumbnail.ensure_thumb(media, cache_root, item_id=item_id)
-
-        assert result == cache_file
-
-
-@pytest.mark.asyncio
-async def test_disabled(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library import thumbnail
-
-    thumbnail._IN_PROCESS.clear()
-    thumbnail.Cache.get_instance().clear()
-
-    with temporary_test_dir("thumb-disabled") as temp_dir:
-        media = temp_dir / "video.mp4"
-        media.write_text("video")
-
-        monkeypatch.setattr(
-            thumbnail.Config,
-            "get_instance",
-            staticmethod(lambda: type("Cfg", (), {"thumb_generate": False, "thumb_sidecar": False})()),
-        )
-
-        result = await thumbnail.ensure_thumb(media, temp_dir / "cache", item_id="item-1")
-
-        assert result is None
-
-
-@pytest.mark.asyncio
-async def test_sidecar_mode(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library import thumbnail
-
-    thumbnail._IN_PROCESS.clear()
-    thumbnail._SEM = None
-    thumbnail._SEM_LIMIT = None
-    thumbnail.Cache.get_instance().clear()
-
-    with temporary_test_dir("thumb-sidecar") as temp_dir:
-        media = temp_dir / "video.mp4"
-        media.write_text("video")
-
-        sidecar = media.with_name(f"{media.name}.jpg")
-
-        monkeypatch.setattr(
-            thumbnail.Config,
-            "get_instance",
-            staticmethod(
-                lambda: type(
-                    "Cfg",
-                    (),
-                    {"thumb_generate": True, "thumb_sidecar": True, "thumb_concurrency": 1},
-                )()
-            ),
-        )
-
-        async def fake_run_ffmpeg(_file: Path, out_file: Path) -> Path:
-            out_file.write_text("image")
-            return out_file
-
-        monkeypatch.setattr(thumbnail, "_run_ffmpeg", fake_run_ffmpeg)
-
-        result = await thumbnail.ensure_thumb(media, temp_dir / "cache")
-
-        assert result == sidecar
-        assert sidecar.exists()
-
-
-@pytest.mark.asyncio
-async def test_miss_cache(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library import thumbnail
-
-    thumbnail._IN_PROCESS.clear()
-    thumbnail.Cache.get_instance().clear()
-
-    with temporary_test_dir("thumb-miss") as temp_dir:
-        media = temp_dir / "video.mp4"
-        media.write_text("video")
-        item_id = "item-1"
-
-        monkeypatch.setattr(
-            thumbnail.Config,
-            "get_instance",
-            staticmethod(
-                lambda: type(
-                    "Cfg",
-                    (),
-                    {"thumb_generate": True, "thumb_sidecar": False, "thumb_concurrency": 1},
-                )()
-            ),
-        )
-
-        calls = {"count": 0}
-
-        async def fake_run_ffmpeg(_file: Path, _out_file: Path) -> Path | None:
-            calls["count"] += 1
-            return None
-
-        monkeypatch.setattr(thumbnail, "_run_ffmpeg", fake_run_ffmpeg)
-
-        first = await thumbnail.ensure_thumb(media, temp_dir / "cache", item_id=item_id)
-        second = await thumbnail.ensure_thumb(media, temp_dir / "cache", item_id=item_id)
-
-        assert first is None
-        assert second is None
-        assert calls["count"] == 1
-
-
-def test_sem_limit(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library import thumbnail
-
-    thumbnail._SEM = None
-    thumbnail._SEM_LIMIT = None
-
-    monkeypatch.setattr(
-        thumbnail.Config,
-        "get_instance",
-        staticmethod(
-            lambda: type("Cfg", (), {"thumb_concurrency": 3, "thumb_generate": True, "thumb_sidecar": False})()
-        ),
-    )
-
-    sem = thumbnail._get_semaphore()
-
-    assert sem._value == 3
-    assert thumbnail._SEM_LIMIT == 3
-
-
-def test_seek_bounds() -> None:
-    from app.features.streaming.library.ffprobe import FFProbeResult
-    from app.features.streaming.library.thumbnail import _seek_seconds
-
-    ff_info = FFProbeResult()
-    ff_info.metadata = {"duration": "120.0"}
-    assert _seek_seconds(ff_info) == 12.0
-
-    ff_info.metadata = {"duration": "2.0"}
-    assert _seek_seconds(ff_info) == 1.0
-
-    ff_info.metadata = {"duration": "0.05"}
-    assert _seek_seconds(ff_info) is None
-
-    ff_info.metadata = {}
-    assert _seek_seconds(ff_info) == 3.0
-
-
-@pytest.mark.asyncio
-async def test_cache_name_uses_item_id(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library import thumbnail
-
-    thumbnail._IN_PROCESS.clear()
-    thumbnail.Cache.get_instance().clear()
-
-    with temporary_test_dir("thumb-id-name") as temp_dir:
-        media = temp_dir / "video.mp4"
-        cache_root = temp_dir / "cache"
-        media.write_text("video")
-
-        async def fake_run_ffmpeg(_file: Path, output_file: Path) -> Path:
-            output_file.parent.mkdir(parents=True, exist_ok=True)
-            output_file.write_text("image")
-            return output_file
-
-        monkeypatch.setattr(thumbnail, "_run_ffmpeg", fake_run_ffmpeg)
-
-        result = await thumbnail.ensure_thumb(media, cache_root, item_id="item-1")
-
-        assert result == cache_root / "item-1.jpg"
-
-
-@pytest.mark.asyncio
-async def test_retry_no_seek(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library.ffprobe import FFProbeResult
-    from app.features.streaming.library import thumbnail
-
-    with temporary_test_dir("thumb-retry") as temp_dir:
-        media = temp_dir / "video.mp4"
-        output = temp_dir / ".jpg"
-        media.write_text("video")
-
-        ff_info: Any = FFProbeResult()
-        ff_info.metadata = {"duration": "120.0"}
-        ff_info.video = [type("Video", (), {"codec_type": "video", "codec_name": "h264"})()]
-
-        monkeypatch.setattr(thumbnail, "ffprobe", AsyncMock(return_value=ff_info))
-
-        calls: list[list[str]] = []
-
-        class DummyProc:
-            def __init__(self, attempt: int, out_path: Path) -> None:
-                self.returncode = 1 if attempt == 1 else 0
-                self._out_path = out_path
-
-            async def communicate(self) -> tuple[bytes, bytes]:
-                if self.returncode == 0:
-                    self._out_path.write_text("image")
-                    return b"", b""
-                return b"", b"seek failed"
-
-        async def fake_create_subprocess_exec(*args, **kwargs):
-            del kwargs
-            calls.append([str(arg) for arg in args])
-            return DummyProc(len(calls), Path(str(args[-1])))
-
-        monkeypatch.setattr(thumbnail.asyncio, "create_subprocess_exec", fake_create_subprocess_exec)
-
-        result = await thumbnail._run_ffmpeg(media, output)
-
-        assert result == output
-        assert len(calls) == 2
-        assert "-ss" in calls[0]
-        assert calls[0][calls[0].index("-ss") + 1] == "12.000"
-        assert "-ss" not in calls[1]
-        assert calls[0][calls[0].index("-vf") + 1] == "thumbnail=200,scale=1280:-1:force_original_aspect_ratio=decrease"
-        assert calls[0][-1].endswith(".tmp.jpg")
-
-
-@pytest.mark.asyncio
-async def test_limit_wait(monkeypatch: pytest.MonkeyPatch) -> None:
-    from app.features.streaming.library import thumbnail
-    from app.features.streaming.library.ffprobe import FFProbeResult
-
-    thumbnail._SEM = None
-    thumbnail._SEM_LIMIT = None
-    thumbnail._IN_PROCESS.clear()
-    monkeypatch.setattr(
-        thumbnail.Config,
-        "get_instance",
-        staticmethod(
-            lambda: type("Cfg", (), {"thumb_concurrency": 1, "thumb_generate": True, "thumb_sidecar": False})()
-        ),
-    )
-
-    with temporary_test_dir("thumb-limit") as temp_dir:
-        media1 = temp_dir / "video1.mp4"
-        media2 = temp_dir / "video2.mp4"
-        out1 = temp_dir / "out1.jpg"
-        out2 = temp_dir / "out2.jpg"
-        media1.write_text("video")
-        media2.write_text("video")
-
-        ff_info: Any = FFProbeResult()
-        ff_info.metadata = {"duration": "60.0"}
-        ff_info.video = [type("Video", (), {"codec_type": "video", "codec_name": "h264"})()]
-        monkeypatch.setattr(thumbnail, "ffprobe", AsyncMock(return_value=ff_info))
-
-        active = {"count": 0, "max": 0}
-
-        class DummyProc:
-            def __init__(self, out_path: Path) -> None:
-                self.returncode = 0
-                self._out_path = out_path
-
-            async def communicate(self) -> tuple[bytes, bytes]:
-                active["count"] += 1
-                active["max"] = max(active["max"], active["count"])
-                await asyncio.sleep(0.01)
-                self._out_path.write_text("image")
-                active["count"] -= 1
-                return b"", b""
-
-        async def fake_create_subprocess_exec(*args, **kwargs):
-            del kwargs
-            return DummyProc(Path(str(args[-1])))
-
-        monkeypatch.setattr(thumbnail.asyncio, "create_subprocess_exec", fake_create_subprocess_exec)
-
-        first, second = await asyncio.gather(
-            thumbnail._run_ffmpeg(media1, out1),
-            thumbnail._run_ffmpeg(media2, out2),
-        )
-
-        assert first == out1
-        assert second == out2
-        assert active["max"] == 1

app/features/streaming/types.py

@@ -1,6 +0,0 @@
-class StreamingError(Exception):
-    """Raised when an error occurs during streaming."""
-
-
-class FFProbeError(Exception):
-    """Raised when an error occurs during FFProbe processing."""

app/features/tasks/__init__.py

@@ -1 +0,0 @@
-"""Tasks Feature."""

app/features/tasks/definitions/__init__.py

@@ -1 +0,0 @@
-"""Tasks Definitions Feature."""

app/features/tasks/definitions/deps.py

@@ -1,5 +0,0 @@
-from app.features.tasks.definitions.repository import TaskDefinitionsRepository
-
-
-def get_task_definitions_repo() -> TaskDefinitionsRepository:
-    return TaskDefinitionsRepository.get_instance()

app/features/tasks/definitions/handlers/__init__.py

@@ -1 +0,0 @@
-"""Handlers package for task definitions."""

app/features/tasks/definitions/handlers/_base_handler.py

@@ -1,71 +0,0 @@
-from typing import TYPE_CHECKING, Any
-
-from app.features.tasks.definitions.results import HandleTask, TaskFailure, TaskResult
-from app.library.config import Config
-from app.library.httpx_client import Globals, build_request_headers, get_async_client, resolve_curl_transport
-
-if TYPE_CHECKING:
-    import httpx
-
-
-class BaseHandler:
-    @staticmethod
-    async def can_handle(task: HandleTask) -> bool:
-        _ = task
-        return False
-
-    @staticmethod
-    async def extract(task: HandleTask, config: Config | None = None) -> TaskResult | TaskFailure:
-        raise NotImplementedError
-
-    @classmethod
-    async def inspect(cls, task: HandleTask, config: Config | None = None) -> TaskResult | TaskFailure:
-        return await cls.extract(task=task, config=config)
-
-    @staticmethod
-    def parse(url: str) -> Any | None:
-        _ = url
-        return None
-
-    @staticmethod
-    def tests() -> list[tuple[str, bool]]:
-        return []
-
-    @staticmethod
-    async def request(
-        url: str, headers: dict | None = None, ytdlp_opts: dict | None = None, **kwargs
-    ) -> "httpx.Response":
-        """
-        Make an HTTP request.
-
-        Args:
-            url (str): The URL to request.
-            headers (dict | None): Additional headers to include in the request.
-            ytdlp_opts (dict | None): yt-dlp options that may affect the request.
-            **kwargs: Additional arguments to pass to httpx request.
-
-        Returns:
-            httpx.Response: The HTTP response.
-
-        """
-        headers = {} if not isinstance(headers, dict) else headers
-        ytdlp_opts = {} if not isinstance(ytdlp_opts, dict) else ytdlp_opts
-
-        use_curl = resolve_curl_transport()
-        request_headers = build_request_headers(
-            base_headers=headers,
-            user_agent=Globals.get_random_agent(),
-            use_curl=use_curl,
-        )
-
-        proxy = ytdlp_opts.get("proxy", None)
-        client = get_async_client(proxy=proxy, use_curl=use_curl)
-        method = kwargs.pop("method", "GET").upper()
-        timeout = ytdlp_opts.get("timeout", ytdlp_opts.get("socket_timeout", 120))
-        return await client.request(
-            method=method,
-            url=url,
-            headers=request_headers,
-            timeout=timeout,
-            **kwargs,
-        )

app/features/tasks/definitions/handlers/generic.py

@@ -1,925 +0,0 @@
-"""Generic task handler driven by JSON definitions."""
-
-from __future__ import annotations
-
-import asyncio
-import fnmatch
-import hashlib
-import json
-import re
-from collections.abc import Mapping
-from typing import TYPE_CHECKING, Any
-from urllib.parse import urljoin
-
-import httpx
-import jmespath
-from parsel import Selector
-
-from app.features.tasks.definitions.results import HandleTask, TaskFailure, TaskItem, TaskResult
-from app.features.tasks.definitions.schemas import (
-    ExtractionRule,
-    TaskDefinition,
-)
-from app.features.ytdlp.extractor import fetch_info
-from app.features.ytdlp.utils import get_archive_id
-from app.library.cache import Cache
-from app.library.config import Config
-from app.library.httpx_client import Globals, build_request_headers, get_async_client, resolve_curl_transport
-from app.library.log import get_logger
-
-from ._base_handler import BaseHandler
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-    from parsel.selector import SelectorList
-
-LOG = get_logger()
-CACHE: Cache = Cache()
-
-
-class GenericTaskHandler(BaseHandler):
-    """Handler that scrapes arbitrary web pages based on JSON task definitions."""
-
-    _definitions: list[TaskDefinition] = []
-    """Cached loaded task definitions."""
-
-    _sources_mtime: dict[Path, float] = {}
-    """Modification times of source files to detect changes."""
-
-    @classmethod
-    async def refresh_definitions(cls, force: bool = False) -> list[TaskDefinition]:
-        """
-        Refresh the cached task definitions if source files have changed.
-
-        Args:
-            force (bool): If True, force reload even if no changes detected.
-
-        """
-        if cls._definitions and not force:
-            return cls._definitions
-
-        try:
-            from app.features.tasks.definitions.repository import TaskDefinitionsRepository
-            from app.features.tasks.definitions.utils import model_to_schema
-
-            repo = TaskDefinitionsRepository.get_instance()
-            models = await repo.all()
-
-            cls._definitions = [model_to_schema(model) for model in models]
-            return cls._definitions
-        except Exception as exc:
-            LOG.exception(
-                "Failed to load generic task definitions.",
-                extra={"error": str(exc), "exception_type": type(exc).__name__},
-            )
-            return []
-
-    @classmethod
-    async def _find_definition(cls, url: str) -> TaskDefinition | None:
-        """
-        Find a task definition that matches the given URL.
-
-        Args:
-            url (str): The URL to match.
-
-        Returns:
-            (TaskDefinition|None): A matching TaskDefinition if found, None otherwise.
-
-        """
-        await cls.refresh_definitions()
-
-        for definition in cls._definitions:
-            if not definition.enabled:
-                continue
-
-            try:
-                for matcher in definition.match_url:
-                    pattern_str: str | None = None
-
-                    if matcher.startswith("/") and matcher.endswith("/") and len(matcher) > 2:
-                        pattern_str = matcher[1:-1]
-                    else:
-                        pattern_str = fnmatch.translate(matcher)
-
-                    if pattern_str and re.match(pattern_str, url):
-                        return definition
-            except Exception as exc:
-                LOG.exception(
-                    "Failed to match a generic task definition.",
-                    extra={
-                        "definition": definition.name,
-                        "url": url,
-                        "error": str(exc),
-                        "exception_type": type(exc).__name__,
-                    },
-                )
-
-        return None
-
-    @staticmethod
-    async def can_handle(task: HandleTask) -> bool:
-        """
-        Determine if this handler can process the given task.
-
-        Args:
-            task (Task): The task to check.
-
-        Returns:
-            (bool): True if the handler can process the task, False otherwise.
-
-        """
-        definition: TaskDefinition | None = await GenericTaskHandler._find_definition(task.url)
-        if definition:
-            LOG.debug(
-                "Task '%s' matched a generic task definition.",
-                task.name,
-                extra={"task_name": task.name, "url": task.url, "definition": definition.name},
-            )
-            return True
-
-        return False
-
-    @staticmethod
-    async def extract(task: HandleTask, config: Config | None = None) -> TaskResult | TaskFailure:
-        _ = config
-        definition: TaskDefinition | None = await GenericTaskHandler._find_definition(task.url)
-        if not definition:
-            return TaskFailure(message="No generic task definition matched the provided URL.")
-
-        ytdlp_opts: dict[str, Any] = task.get_ytdlp_opts().get_all()
-        target_url: str = definition.definition.request.url or task.url
-
-        LOG.debug(
-            "Fetching content for task '%s'.",
-            task.name,
-            extra={
-                "task_name": task.name,
-                "definition": definition.name,
-                "url": target_url,
-                "engine": definition.definition.engine.type,
-            },
-        )
-
-        try:
-            body_text, json_data = await GenericTaskHandler._fetch_content(
-                url=target_url, definition=definition, ytdlp_opts=ytdlp_opts
-            )
-        except httpx.HTTPError as exc:
-            return TaskFailure(message="Failed to fetch target URL.", error=str(exc))
-        except Exception as exc:
-            LOG.exception(
-                "Failed to fetch content for task '%s'.",
-                task.name,
-                extra={
-                    "task_name": task.name,
-                    "definition": definition.name,
-                    "url": target_url,
-                    "exception_type": type(exc).__name__,
-                },
-            )
-            return TaskFailure(message="Failed to fetch target URL.", error=str(exc))
-
-        if "json" == definition.definition.response.type and json_data is None:
-            return TaskFailure(message="Expected JSON response but decoding failed.")
-
-        if "json" != definition.definition.response.type and not body_text:
-            return TaskFailure(message="Received empty response body.")
-
-        raw_items: list[dict[str, str]] = GenericTaskHandler._parse_items(
-            definition=definition, html=body_text or "", base_url=target_url, json_data=json_data
-        )
-
-        task_items: list[TaskItem] = []
-
-        def _generic_id(url):
-            import os
-            from urllib import parse
-
-            return parse.unquote(os.path.splitext(url.rstrip("/").split("/")[-1])[0])
-
-        for entry in raw_items:
-            if not isinstance(entry, dict):
-                continue
-
-            if not (url := entry.get("link") or entry.get("url")):
-                continue
-
-            id_dict: dict[str, str | None] = get_archive_id(url=url)
-            archive_id: str | None = id_dict.get("archive_id")
-            if not archive_id:
-                cache_key: str = hashlib.sha256(f"{task.name}-{url}".encode()).hexdigest()
-                if CACHE.has(cache_key):
-                    archive_id = CACHE.get(cache_key)
-                    if not archive_id:
-                        continue
-                else:
-                    LOG.warning(
-                        "Task '%s' could not generate a static archive ID. Fetching it with yt-dlp.",
-                        task.name,
-                        extra={"definition": definition.name, "task_name": task.name, "url": url},
-                    )
-
-                    (info, _) = await fetch_info(
-                        config=task.get_ytdlp_opts().get_all(),
-                        url=url,
-                        no_archive=True,
-                        no_log=True,
-                        budget_sleep=True,
-                    )
-
-                    if not info:
-                        LOG.error(
-                            "Task '%s' failed to extract info to generate an archive ID. Skipping item.",
-                            task.name,
-                            extra={"definition": definition.name, "task_name": task.name, "url": url},
-                        )
-                        CACHE.set(cache_key, None)
-                        continue
-
-                    if not info.get("id") or not info.get("extractor_key"):
-                        LOG.error(
-                            "Task '%s' returned incomplete info while generating an archive ID. Skipping item.",
-                            task.name,
-                            extra={"definition": definition.name, "task_name": task.name, "url": url},
-                        )
-                        CACHE.set(cache_key, None)
-                        continue
-
-                    archive_id = f"{str(info.get('extractor_key', '')).lower()} {info.get('id')}"
-                    CACHE.set(cache_key, archive_id)
-
-            metadata: dict[str, str] = {
-                k: v for k, v in entry.items() if k not in {"link", "url", "title", "published", "archive_id"}
-            }
-
-            task_items.append(
-                TaskItem(
-                    url=url,
-                    title=entry.get("title"),
-                    archive_id=archive_id,
-                    metadata={"published": entry.get("published"), **metadata},
-                )
-            )
-
-        return TaskResult(
-            items=task_items,
-            metadata={
-                "definition": definition.name,
-                "response_format": definition.definition.response.type,
-            },
-        )
-
-    @staticmethod
-    async def _fetch_content(
-        url: str,
-        definition: TaskDefinition,
-        ytdlp_opts: dict[str, Any],
-    ) -> tuple[str | None, Any | None]:
-        """
-        Fetch the content of the given URL using the specified engine.
-
-        Args:
-            url (str): The URL to fetch.
-            definition (TaskDefinitionRuntimeSchema): The task definition specifying the engine and request details.
-            ytdlp_opts (dict[str, Any]): yt-dlp options that may influence fetching
-
-        Returns:
-            (str|None): The fetched HTML content if successful, None otherwise.
-
-        """
-        if "selenium" == definition.definition.engine.type:
-            return await GenericTaskHandler._fetch_with_selenium(url=url, definition=definition)
-
-        return await GenericTaskHandler._fetch_with_httpx(url=url, definition=definition, ytdlp_opts=ytdlp_opts)
-
-    @staticmethod
-    async def _fetch_with_httpx(
-        url: str,
-        definition: TaskDefinition,
-        ytdlp_opts: dict[str, Any],
-    ) -> tuple[str | None, Any | None]:
-        """
-        Fetch the content using httpx.
-
-        Args:
-            url (str): The URL to fetch.
-            definition (TaskDefinitionRuntimeSchema): The task definition specifying the request details.
-            ytdlp_opts (dict[str, Any]): yt-dlp options that may influence fetching
-
-        Returns:
-            (str|None): The fetched HTML content if successful, None otherwise.
-
-        """
-        headers: dict[str, str] = {**definition.definition.request.headers}
-        use_curl = resolve_curl_transport()
-        request_headers = build_request_headers(
-            base_headers=headers,
-            user_agent=Globals.get_random_agent(),
-            use_curl=use_curl,
-        )
-
-        timeout_value: float | Any = definition.definition.request.timeout or ytdlp_opts.get("socket_timeout", 120)
-
-        client = get_async_client(proxy=ytdlp_opts.get("proxy"), use_curl=use_curl)
-        response: httpx.Response = await client.request(
-            method=definition.definition.request.method.upper(),
-            url=url,
-            params=definition.definition.request.params or None,
-            data=definition.definition.request.data,
-            json=definition.definition.request.json_data,
-            timeout=timeout_value,
-            headers=request_headers,
-        )
-        response.raise_for_status()
-
-        if "json" == definition.definition.response.type:
-            try:
-                json_data: dict[str, Any] = response.json()
-            except Exception as exc:
-                LOG.exception(
-                    "Task definition '%s' returned invalid JSON for '%s'.",
-                    definition.name,
-                    url,
-                    extra={
-                        "definition": definition.name,
-                        "url": url,
-                        "error": str(exc),
-                        "exception_type": type(exc).__name__,
-                    },
-                )
-                return response.text, None
-
-            return response.text, json_data
-
-        return response.text, None
-
-    @staticmethod
-    async def _fetch_with_selenium(
-        url: str,
-        definition: TaskDefinition,
-    ) -> tuple[str | None, Any | None]:
-        """
-        Fetch the content using a Selenium WebDriver.
-
-        Args:
-            url (str): The URL to fetch.
-            definition (TaskDefinitionRuntimeSchema): The task definition specifying the engine options.
-
-        Returns:
-            (str|None): The fetched HTML content if successful, None otherwise.
-
-        """
-        try:
-            from selenium import webdriver
-            from selenium.webdriver.chrome.options import Options as ChromeOptions
-            from selenium.webdriver.common.by import By
-            from selenium.webdriver.support import expected_conditions as EC
-            from selenium.webdriver.support.ui import WebDriverWait
-        except ImportError as exc:
-            LOG.exception(
-                "Task definition '%s' requested Selenium, but Selenium is not installed.",
-                definition.name,
-                extra={"definition": definition.name, "error": str(exc), "exception_type": type(exc).__name__},
-            )
-            return (None, None)
-
-        options_map: dict[str, Any] = definition.definition.engine.options
-        command_executor_value = options_map.get("url")
-        command_executor: str = (
-            str(command_executor_value)
-            if isinstance(command_executor_value, str) and command_executor_value
-            else "http://localhost:4444/wd/hub"
-        )
-        browser: str = str(options_map.get("browser", "chrome")).lower()
-
-        if "chrome" != browser:
-            LOG.error(
-                "Task definition '%s' requested unsupported Selenium browser '%s'.",
-                definition.name,
-                browser,
-                extra={"definition": definition.name, "browser": browser},
-            )
-            return (None, None)
-
-        arguments: list[str] | str = options_map.get("arguments", ["--headless", "--disable-gpu"])
-        if isinstance(arguments, str):
-            arguments = [arguments]
-
-        wait_for: Mapping | None = (
-            options_map.get("wait_for") if isinstance(options_map.get("wait_for"), Mapping) else None
-        )
-        wait_timeout = float(options_map.get("wait_timeout") or 15)
-        page_load_timeout = float(options_map.get("page_load_timeout") or 60)
-
-        def load_page() -> str | None:
-            chrome_options = ChromeOptions()
-            for arg in arguments:
-                chrome_options.add_argument(str(arg))
-
-            driver = webdriver.Remote(command_executor=command_executor, options=chrome_options)
-            try:
-                driver.set_page_load_timeout(page_load_timeout)
-                driver.get(url)
-
-                if wait_for:
-                    wait_type: str = str(wait_for.get("type", "css")).lower()
-                    expression: str | None = wait_for.get("expression") or wait_for.get("value")
-                    if isinstance(expression, str) and expression:
-                        locator = None
-                        locator = (By.XPATH, expression) if "xpath" == wait_type else (By.CSS_SELECTOR, expression)
-                        WebDriverWait(driver, wait_timeout).until(EC.presence_of_element_located(locator))
-
-                return driver.page_source
-            finally:
-                driver.quit()
-
-        html: str | None = await asyncio.to_thread(load_page)
-        return html, None
-
-    @staticmethod
-    def _parse_items(
-        definition: TaskDefinition,
-        html: str,
-        base_url: str,
-        json_data: Any | None = None,
-    ) -> list[dict[str, str]]:
-        """
-        Parse the HTML content and extract items based on the definition.
-
-        Args:
-            definition (TaskDefinitionRuntimeSchema): The task definition specifying the parsers.
-            html (str): The HTML content to parse.
-            base_url (str): The base URL to resolve relative links.
-            json_data (Any|None): The JSON data to parse if applicable.
-
-        Returns:
-            (list[dict[str, str]]): A list of extracted items as dictionaries.
-
-        """
-        if "json" == definition.definition.response.type:
-            return GenericTaskHandler._parse_json_items(definition, json_data, base_url)
-
-        selector = Selector(text=html)
-
-        if definition.definition.parse.get("items"):
-            return GenericTaskHandler._parse_with_container(
-                definition=definition,
-                selector=selector,
-                html=html,
-                base_url=base_url,
-            )
-
-        extracted: dict[str, list[str]] = {}
-
-        for _field, rule_data in definition.definition.parse.field_items():
-            if not isinstance(rule_data, dict):
-                continue
-            rule = ExtractionRule.model_validate(rule_data)
-            values: list[str] = GenericTaskHandler._execute_rule(field=_field, selector=selector, html=html, rule=rule)
-            extracted[_field] = values
-
-        link_values: list[str] = extracted.get("link", [])
-        if not link_values:
-            LOG.debug(
-                "Definition '%s' produced no link values.", definition.name, extra={"definition": definition.name}
-            )
-            return []
-
-        total_items: int = len(link_values)
-        items: list[dict[str, str]] = []
-
-        for index in range(total_items):
-            entry: dict[str, str] = {}
-            link_value: str = link_values[index]
-            if not link_value:
-                continue
-
-            entry["link"] = urljoin(base_url, link_value)
-
-            for _field, values in extracted.items():
-                if "link" == _field:
-                    continue
-
-                value: str | None = values[index] if index < len(values) else None
-                if value is None:
-                    continue
-
-                entry[_field] = value
-
-            items.append(entry)
-
-        return items
-
-    @staticmethod
-    def _parse_json_items(
-        definition: TaskDefinition,
-        json_data: Any | None,
-        base_url: str,
-    ) -> list[dict[str, str]]:
-        if json_data is None:
-            LOG.debug(
-                "Definition '%s' expects JSON but no data was parsed.",
-                definition.name,
-                extra={"definition": definition.name},
-            )
-            return []
-
-        if definition.definition.parse.get("items"):
-            return GenericTaskHandler._parse_json_with_container(definition, json_data, base_url)
-
-        items: list[dict[str, str]] = []
-        entry: dict[str, str] = {}
-
-        for _field, rule_data in definition.definition.parse.field_items():
-            if not isinstance(rule_data, dict):
-                continue
-            rule = ExtractionRule.model_validate(rule_data)
-            values: list[str] = GenericTaskHandler._execute_json_rule(_field, json_data, rule)
-            if values:
-                if "link" == _field:
-                    entry["link"] = urljoin(base_url, values[0])
-                else:
-                    entry[_field] = values[0]
-
-        if "link" in entry:
-            items.append(entry)
-
-        return items
-
-    @staticmethod
-    def _parse_with_container(
-        definition: TaskDefinition,
-        selector: Selector,
-        html: str,
-        base_url: str,
-    ) -> list[dict[str, str]]:
-        container: dict[str, Any] | None = definition.definition.parse.get("items")
-        if not container:
-            return []
-
-        container_type = container.get("type", "css")
-        container_selector = container.get("selector") or container.get("expression") or ""
-        if not container_selector:
-            LOG.error(
-                "Task definition '%s' is missing an item container selector.",
-                definition.name,
-                extra={"definition": definition.name},
-            )
-            return []
-        container_fields = container.get("fields", {})
-
-        selection: SelectorList[Selector] = (
-            selector.css(container_selector) if "css" == container_type else selector.xpath(container_selector)
-        )
-
-        items: list[dict[str, str]] = []
-
-        for node in selection:
-            node_html: Any | str = node.get() or html
-            entry: dict[str, str] = {}
-
-            for _field, rule_data in container_fields.items():
-                rule = ExtractionRule.model_validate(rule_data)
-                values: list[str] = GenericTaskHandler._execute_rule(
-                    field=_field,
-                    selector=node,
-                    html=node_html,
-                    rule=rule,
-                )
-
-                value: str | None = values[0] if values else None
-                if value is None:
-                    continue
-
-                if "link" == _field:
-                    entry["link"] = urljoin(base_url, value)
-                else:
-                    entry[_field] = value
-
-            if "link" not in entry:
-                continue
-
-            items.append(entry)
-
-        return items
-
-    @staticmethod
-    def _parse_json_with_container(
-        definition: TaskDefinition,
-        json_data: Any,
-        base_url: str,
-    ) -> list[dict[str, str]]:
-        container: dict[str, Any] | None = definition.definition.parse.get("items")
-        if not container:
-            return []
-
-        container_type = container.get("type", "css")
-        container_selector = container.get("selector") or container.get("expression", "")
-        container_fields = container.get("fields", {})
-
-        if "jsonpath" != container_type:
-            LOG.error(
-                "JSON response requires container selector type 'jsonpath'. Definition '%s'.",
-                definition.name,
-                extra={"definition": definition.name, "container_type": container_type},
-            )
-            return []
-
-        nodes: Any = GenericTaskHandler._json_search(json_data, container_selector)
-        if nodes is None:
-            return []
-
-        if not isinstance(nodes, list):
-            nodes = [nodes]
-
-        items: list[dict[str, str]] = []
-
-        for node in nodes:
-            entry: dict[str, str] = {}
-
-            for _field, rule_data in container_fields.items():
-                rule = ExtractionRule.model_validate(rule_data)
-                values: list[str] = GenericTaskHandler._execute_json_rule(_field, node, rule)
-                if not values:
-                    continue
-
-                if "link" == _field:
-                    entry["link"] = urljoin(base_url, values[0])
-                else:
-                    entry[_field] = values[0]
-
-            if "link" not in entry:
-                continue
-
-            items.append(entry)
-
-        return items
-
-    @staticmethod
-    def _execute_json_rule(field: str, data: Any, rule: ExtractionRule) -> list[str]:
-        values: list[str] = []
-
-        if "jsonpath" == rule.type:
-            result: Any = GenericTaskHandler._json_search(data, rule.expression)
-            candidates: list | list[Any] = result if isinstance(result, list) else [result]
-            for candidate in candidates:
-                if candidate is None:
-                    continue
-
-                text: str = GenericTaskHandler._coerce_to_string(candidate)
-                processed: str | None = GenericTaskHandler._apply_post_filter(text, rule)
-                if processed is not None:
-                    values.append(processed)
-
-            return values
-
-        if "regex" == rule.type:
-            target: str = GenericTaskHandler._coerce_to_string(data)
-            try:
-                pattern: re.Pattern[str] = re.compile(rule.expression, re.MULTILINE | re.DOTALL)
-            except re.error as exc:
-                LOG.exception(
-                    "Invalid regex expression '%s'.",
-                    rule.expression,
-                    extra={
-                        "field": field,
-                        "expression": rule.expression,
-                        "error": str(exc),
-                        "exception_type": type(exc).__name__,
-                    },
-                )
-                return values
-
-            for match in pattern.finditer(target):
-                raw: str | None = GenericTaskHandler._regex_value(match=match, attribute=rule.attribute)
-                processed = GenericTaskHandler._apply_post_filter(raw, rule)
-                if processed is not None:
-                    values.append(processed)
-
-            return values
-
-        LOG.error(
-            "Unsupported extraction type '%s' for JSON data in field '%s'.",
-            rule.type,
-            field,
-            extra={"field": field, "rule_type": rule.type},
-        )
-        return values
-
-    @staticmethod
-    def _json_search(data: Any, expression: str) -> Any:
-        try:
-            return jmespath.search(expression, data)
-        except Exception as exc:
-            LOG.exception(
-                "JSONPath search failed for expression '%s'.",
-                expression,
-                extra={"expression": expression, "error": str(exc), "exception_type": type(exc).__name__},
-            )
-            return None
-
-    @staticmethod
-    def _coerce_to_string(value: Any) -> str:
-        if isinstance(value, str):
-            return value
-        if isinstance(value, (int, float, bool)) or value is None:
-            return "" if value is None else str(value)
-        try:
-            return json.dumps(value, ensure_ascii=False)
-        except Exception:
-            return str(value)
-
-    @staticmethod
-    def _execute_rule(field: str, selector: Selector, html: str, rule: ExtractionRule) -> list[str]:
-        """
-        Execute a single extraction rule and return the list of extracted values.
-
-        Args:
-            field (str): The name of the field being extracted.
-            selector (Selector): The parsel Selector for the HTML content.
-            html (str): The raw HTML content.
-            rule (ExtractionRuleSchema): The extraction rule to execute.
-
-        Returns:
-            (list[str]): A list of extracted values.
-
-        """
-        values: list[str] = []
-
-        if "regex" == rule.type:
-            try:
-                pattern: re.Pattern[str] = re.compile(rule.expression, re.MULTILINE | re.DOTALL)
-            except re.error as exc:
-                LOG.exception(
-                    "Invalid regex expression '%s'.",
-                    rule.expression,
-                    extra={
-                        "field": field,
-                        "expression": rule.expression,
-                        "error": str(exc),
-                        "exception_type": type(exc).__name__,
-                    },
-                )
-                return values
-
-            for match in pattern.finditer(html):
-                raw: str | None = GenericTaskHandler._regex_value(match=match, attribute=rule.attribute)
-                processed: str | None = GenericTaskHandler._apply_post_filter(raw, rule)
-                if processed is not None:
-                    values.append(processed)
-
-            return values
-
-        if "jsonpath" == rule.type:
-            LOG.error("Field '%s' uses 'jsonpath' on a non-JSON response.", field, extra={"field": field})
-            return values
-
-        selection: SelectorList[Selector] = (
-            selector.css(rule.expression) if "css" == rule.type else selector.xpath(rule.expression)
-        )
-
-        for sel in selection:
-            raw = GenericTaskHandler._selector_value(field, sel, rule.attribute)
-            processed = GenericTaskHandler._apply_post_filter(raw, rule)
-            if processed is not None:
-                values.append(processed)
-
-        return values
-
-    @staticmethod
-    def _regex_value(match: re.Match[str], attribute: str | None) -> str | None:
-        """
-        Extract a value from a regex match based on the attribute.
-
-        Args:
-            match (re.Match[str]): The regex match object.
-            attribute (str|None): Optional group name or index to extract.
-
-        Returns:
-            (str|None): The extracted value if found, None otherwise.
-
-        """
-        if attribute:
-            try:
-                return match.group(attribute)
-            except (IndexError, KeyError):
-                LOG.debug(
-                    "Regex group '%s' not found in pattern '%s'.",
-                    attribute,
-                    match.re.pattern,
-                    extra={"attribute": attribute, "pattern": match.re.pattern},
-                )
-                return None
-
-        if match.groupdict():
-            return next((value for value in match.groupdict().values() if value), None)
-
-        if match.groups():
-            return match.group(1)
-
-        return match.group(0)
-
-    @staticmethod
-    def _selector_value(field: str, sel: Selector, attribute: str | None) -> str | None:
-        """
-        Extract a value from a parsel Selector based on the attribute.
-
-        Args:
-            field (str): The name of the field being extracted.
-            sel (Selector): The parsel Selector object.
-            attribute (str|None): Optional attribute to extract (e.g. 'href', 'src', 'text', etc.).
-
-        Returns:
-            (str|None): The extracted value if found, None otherwise.
-
-        """
-        attr: str | None = attribute.lower() if isinstance(attribute, str) else None
-
-        if attr in {"text", "inner_text"}:
-            return sel.xpath("normalize-space()").get()
-
-        if attr in {"html", "outer_html"}:
-            value: Any = sel.get()
-            return value if value is not None else None
-
-        if attr and attr not in {"html", "outer_html", "text", "inner_text"}:
-            try:
-                attributes: dict[str, str] | None = sel.attrib
-            except AttributeError:
-                attributes = None
-
-            if attributes and attr in attributes:
-                return attributes.get(attr)
-
-            attr_value: str | None = sel.xpath(f"@{attr}").get()
-            if attr_value is not None:
-                return attr_value
-
-        if attr is None and "link" == field.lower():
-            href = None
-            try:
-                attributes: dict[str, str] | None = sel.attrib
-            except AttributeError:
-                attributes = None
-
-            if attributes and "href" in attributes:
-                href: str | None = attributes.get("href")
-            if not href:
-                href: str | None = sel.xpath("@href").get()
-            if href:
-                return href
-
-        if attr is None:
-            text_value: str | None = sel.xpath("normalize-space()").get()
-            if text_value:
-                return text_value
-
-        value = sel.get()
-        return value if value is not None else None
-
-    @staticmethod
-    def _apply_post_filter(value: str | None, rule: ExtractionRule) -> str | None:
-        """
-        Apply the post-filter to the extracted value if defined.
-
-        Args:
-            value (str|None): The extracted value to filter.
-            rule (ExtractionRuleSchema): The extraction rule containing the post-filter.
-
-        Returns:
-            (str|None): The filtered value if applicable, None otherwise.
-
-        """
-        if value is None:
-            return None
-
-        cleaned: str = value.strip()
-        if rule.post_filter:
-            # Apply post-filter inline (removed helper method)
-            try:
-                pattern = re.compile(rule.post_filter.filter)
-                match = pattern.search(cleaned)
-                if not match:
-                    return None
-
-                if rule.post_filter.value:
-                    try:
-                        return match.group(rule.post_filter.value)
-                    except (IndexError, KeyError):
-                        return None
-
-                if match.groupdict():
-                    # Prefer first named group when available
-                    for group_value in match.groupdict().values():
-                        if group_value is not None:
-                            return group_value
-
-                if match.groups():
-                    return match.group(1)
-
-                return match.group(0)
-            except re.error:
-                return None
-
-        return cleaned or None

app/features/tasks/definitions/migration.py

@@ -1,138 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-from app.features.core.migration import Migration as FeatureMigration
-from app.library.config import Config
-from app.library.log import get_logger
-
-if TYPE_CHECKING:
-    from app.features.tasks.definitions.repository import TaskDefinitionsRepository
-
-LOG = get_logger()
-
-
-class Migration(FeatureMigration):
-    name: str = "task_definitions"
-
-    def __init__(self, repo: TaskDefinitionsRepository, config: Config | None = None) -> None:
-        self._config: Config = config or Config.get_instance()
-        super().__init__(config=self._config)
-        self._repo: TaskDefinitionsRepository = repo
-        self._source_dir: Path = Path(self._config.config_path) / "tasks"
-
-    async def should_run(self) -> bool:
-        if not self._source_dir.exists():
-            return False
-
-        return any(self._source_dir.glob("*.json"))
-
-    async def migrate(self) -> None:
-        if await self._repo.count() > 0:
-            LOG.warning("Task definitions already exist in the database; skipping migration.")
-            await self._archive_sources()
-            return
-
-        inserted = 0
-        seen_names: dict[str, int] = {}
-
-        for path in sorted(self._source_dir.glob("*.json")):
-            normalized = await self._normalize(path, seen_names)
-            if not normalized:
-                await self._move_file(path)
-                continue
-
-            try:
-                await self._repo.create(normalized)
-                inserted += 1
-            except Exception as exc:
-                LOG.exception(
-                    "Failed to insert task definition '%s'.",
-                    normalized.get("name"),
-                    extra={"definition": normalized.get("name"), "exception_type": type(exc).__name__},
-                )
-            finally:
-                await self._move_file(path)
-
-        LOG.info("Migrated %s task definition(s) from %s.", inserted, self._source_dir)
-
-    async def _archive_sources(self) -> None:
-        for path in self._source_dir.glob("*.json"):
-            await self._move_file(path)
-
-    async def _normalize(self, path: Path, seen_names: dict[str, int]) -> dict[str, Any] | None:
-        try:
-            content = path.read_text(encoding="utf-8")
-        except Exception as exc:
-            LOG.exception(
-                "Failed to read task definition '%s'.",
-                path,
-                extra={"path": str(path), "exception_type": type(exc).__name__},
-            )
-            return None
-
-        try:
-            payload = json.loads(content)
-        except Exception as exc:
-            LOG.exception(
-                "Failed to parse JSON for task definition '%s'.",
-                path,
-                extra={"path": str(path), "exception_type": type(exc).__name__},
-            )
-            return None
-
-        if not isinstance(payload, dict):
-            LOG.error("Task definition in '%s' must be a JSON object.", path)
-            return None
-
-        if "match" in payload and "match_url" not in payload:
-            payload["match_url"] = payload.pop("match")
-
-        # Normalize match_url from old object format to new string format
-        if "match_url" in payload and isinstance(payload["match_url"], list):
-            normalized_match: list[str] = []
-            for item in payload["match_url"]:
-                if isinstance(item, str):
-                    normalized_match.append(item)
-                elif isinstance(item, dict):
-                    if "regex" in item and isinstance(item["regex"], str):
-                        # Convert {regex: "pattern"} to /pattern/
-                        normalized_match.append(f"/{item['regex']}/")
-                    elif "glob" in item and isinstance(item["glob"], str):
-                        # Convert {glob: "pattern"} to pattern
-                        normalized_match.append(item["glob"])
-            payload["match_url"] = normalized_match
-
-        # Rename request.json to request.json_data
-        if "request" in payload and isinstance(payload["request"], dict) and "json" in payload["request"]:
-            payload["request"]["json_data"] = payload["request"].pop("json")
-
-        if "definition" not in payload:
-            definition_fields = {}
-            for field in ["parse", "engine", "request", "response"]:
-                if field in payload:
-                    definition_fields[field] = payload.pop(field)
-
-            if definition_fields:
-                payload["definition"] = definition_fields
-        # Also handle nested definition.request.json
-        elif isinstance(payload["definition"], dict):
-            if (
-                "request" in payload["definition"]
-                and isinstance(payload["definition"]["request"], dict)
-                and "json" in payload["definition"]["request"]
-            ):
-                payload["definition"]["request"]["json_data"] = payload["definition"]["request"].pop("json")
-
-        name_value = payload.get("name")
-        if not isinstance(name_value, str) or not name_value.strip():
-            LOG.error("Task definition in '%s' missing a valid name.", path)
-            return None
-
-        name = self._unique_name(name_value.strip(), seen_names)
-        payload["name"] = name
-
-        # Repository will handle validation and field extraction
-        return payload

app/features/tasks/definitions/models.py

@@ -1,27 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime  # noqa: TC003
-
-from sqlalchemy import JSON, Boolean, Index, Integer, String
-from sqlalchemy.orm import Mapped, mapped_column
-
-from app.features.core.models import Base, UTCDateTime, utcnow
-
-
-class TaskDefinitionModel(Base):
-    __tablename__: str = "task_definitions"
-    __table_args__: tuple[Index, ...] = (
-        Index("ix_task_definitions_name", "name"),
-        Index("ix_task_definitions_priority", "priority"),
-        Index("ix_task_definitions_match_url", "match_url"),
-        Index("ix_task_definitions_enabled", "enabled"),
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    priority: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
-    match_url: Mapped[list] = mapped_column(JSON, nullable=False)
-    definition: Mapped[dict] = mapped_column(JSON, nullable=False, default=dict)
-    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
-    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, nullable=False)
-    updated_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, onupdate=utcnow, nullable=False)

app/features/tasks/definitions/repository.py

@@ -1,187 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from sqlalchemy import func, or_, select
-
-from app.features.core.deps import get_session
-from app.features.core.schemas import CEFeature, ConfigEvent
-from app.features.tasks.definitions.migration import Migration
-from app.features.tasks.definitions.models import TaskDefinitionModel
-from app.library.Events import Event, EventBus, Events
-from app.library.log import get_logger
-from app.library.Services import Services
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-    from contextlib import AbstractAsyncContextManager
-
-    from sqlalchemy.engine.result import Result
-    from sqlalchemy.ext.asyncio import AsyncSession
-    from sqlalchemy.sql.elements import ColumnElement
-    from sqlalchemy.sql.selectable import Select
-
-    SessionFactory = Callable[[], AbstractAsyncContextManager[AsyncSession]]
-
-LOG = get_logger()
-
-
-class TaskDefinitionsRepository(metaclass=Singleton):
-    def __init__(self, session: SessionFactory | None = None) -> None:
-        self._migrated = False
-        self.session: SessionFactory = session or get_session
-
-    async def run_migrations(self) -> None:
-        if self._migrated:
-            return
-
-        self._migrated = True
-        await Migration(repo=self).run()
-
-    @staticmethod
-    def get_instance() -> TaskDefinitionsRepository:
-        return TaskDefinitionsRepository()
-
-    def attach(self, _: Any) -> None:
-        async def handle_event(_, __):
-            await self.run_migrations()
-
-        async def handler(e: Event, __):
-            from app.features.tasks.definitions.handlers.generic import GenericTaskHandler
-
-            if isinstance(e.data, ConfigEvent) and CEFeature.TASKS_DEFINITIONS == e.data.feature:
-                LOG.debug("Refreshing task definitions due to configuration update.")
-                await GenericTaskHandler.refresh_definitions(force=True)
-
-        Services.get_instance().add(TaskDefinitionsRepository.__name__, self)
-        EventBus.get_instance().subscribe(
-            Events.STARTED, handle_event, f"{TaskDefinitionsRepository.__name__}.run_migrations"
-        ).subscribe(Events.CONFIG_UPDATE, handler, "GenericTaskHandler.refresh_definitions")
-
-    async def all(self) -> list[TaskDefinitionModel]:
-        async with self.session() as session:
-            result: Result[tuple[TaskDefinitionModel]] = await session.execute(
-                select(TaskDefinitionModel).order_by(TaskDefinitionModel.priority.asc(), TaskDefinitionModel.name.asc())
-            )
-            return list(result.scalars().all())
-
-    async def list_paginated(self, page: int, per_page: int) -> tuple[list[TaskDefinitionModel], int, int, int]:
-        async with self.session() as session:
-            total: int = await self.count()
-            total_pages: int = (total + per_page - 1) // per_page if total > 0 else 1
-
-            if page > total_pages and total > 0:
-                page = total_pages
-
-            query: Select[tuple[TaskDefinitionModel]] = (
-                select(TaskDefinitionModel)
-                .order_by(TaskDefinitionModel.priority.asc(), TaskDefinitionModel.name.asc())
-                .limit(per_page)
-                .offset((page - 1) * per_page)
-            )
-            result: Result[tuple[TaskDefinitionModel]] = await session.execute(query)
-            return list(result.scalars().all()), total, page, total_pages
-
-    async def count(self) -> int:
-        async with self.session() as session:
-            result: Result[tuple[int]] = await session.execute(select(func.count()).select_from(TaskDefinitionModel))
-            return int(result.scalar_one())
-
-    async def get(self, identifier: int | str) -> TaskDefinitionModel | None:
-        async with self.session() as session:
-            if not identifier:
-                return None
-
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = TaskDefinitionModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(TaskDefinitionModel.id == int(identifier), TaskDefinitionModel.name == identifier)
-            else:
-                clause = TaskDefinitionModel.name == identifier
-
-            result: Result[tuple[TaskDefinitionModel]] = await session.execute(
-                select(TaskDefinitionModel).where(clause).limit(1)
-            )
-            return result.scalar_one_or_none()
-
-    async def get_by_name(self, name: str, exclude_id: int | None = None) -> TaskDefinitionModel | None:
-        async with self.session() as session:
-            query: Select[tuple[TaskDefinitionModel]] = select(TaskDefinitionModel).where(
-                TaskDefinitionModel.name == name
-            )
-            if exclude_id is not None:
-                query = query.where(TaskDefinitionModel.id != exclude_id)
-
-            result: Result[tuple[TaskDefinitionModel]] = await session.execute(query.limit(1))
-            return result.scalar_one_or_none()
-
-    async def create(self, payload: dict[str, Any]) -> TaskDefinitionModel:
-        async with self.session() as session:
-            model: TaskDefinitionModel = TaskDefinitionModel(**payload)
-            if model.id is not None:
-                model.id = None  # ty: ignore
-
-            if await self.get_by_name(name=model.name) is not None:
-                msg: str = f"Task definition with name '{model.name}' already exists."
-                raise ValueError(msg)
-
-            session.add(model)
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def update(self, identifier: int | str, payload: dict[str, Any]) -> TaskDefinitionModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = TaskDefinitionModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(TaskDefinitionModel.id == int(identifier), TaskDefinitionModel.name == identifier)
-            else:
-                clause = TaskDefinitionModel.name == identifier
-
-            result: Result[tuple[TaskDefinitionModel]] = await session.execute(
-                select(TaskDefinitionModel).where(clause).limit(1)
-            )
-            model: TaskDefinitionModel | None = result.scalar_one_or_none()
-
-            if not model:
-                msg: str = f"Task definition '{identifier}' not found."
-                raise KeyError(msg)
-
-            payload.pop("id", None)
-            payload.pop("created_at", None)
-            payload.pop("updated_at", None)
-
-            if "name" in payload and await self.get_by_name(name=payload["name"], exclude_id=model.id) is not None:
-                msg = f"Task definition with name '{payload['name']}' already exists."
-                raise ValueError(msg)
-
-            for key, value in payload.items():
-                if hasattr(model, key):
-                    setattr(model, key, value)
-
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def delete(self, identifier: int | str) -> TaskDefinitionModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = TaskDefinitionModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(TaskDefinitionModel.id == int(identifier), TaskDefinitionModel.name == identifier)
-            else:
-                clause = TaskDefinitionModel.name == identifier
-
-            result: Result[tuple[TaskDefinitionModel]] = await session.execute(
-                select(TaskDefinitionModel).where(clause).limit(1)
-            )
-
-            if not (model := result.scalar_one_or_none()):
-                msg: str = f"Task definition '{identifier}' not found."
-                raise KeyError(msg)
-
-            await session.delete(model)
-            await session.commit()
-            return model

app/features/tasks/definitions/results.py

@@ -1,233 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import asdict, dataclass, field
-from pathlib import Path
-from typing import Any
-
-from app.features.tasks.schemas import Task as TaskSchema
-from app.features.ytdlp.ytdlp_opts import YTDLPOpts
-
-from .utils import split_inspect_metadata
-
-
-class HandleTask(TaskSchema):
-    def get_ytdlp_opts(self) -> YTDLPOpts:
-        """
-        Get the yt-dlp options for the task.
-
-        Returns:
-            YTDLPOpts: The yt-dlp options.
-
-        """
-        from app.features.ytdlp.ytdlp_opts import YTDLPOpts
-
-        params: YTDLPOpts = YTDLPOpts.get_instance()
-
-        if self.preset:
-            params = params.preset(name=self.preset)
-
-        if self.cli:
-            params = params.add_cli(self.cli, from_user=True)
-
-        if self.template:
-            params = params.add({"outtmpl": {"default": self.template}}, from_user=False)
-
-        return params
-
-    async def mark(self) -> tuple[bool, str]:
-        """
-        Mark the task's items as downloaded in the archive file.
-
-        Returns:
-            tuple[bool, str]: A tuple indicating success and a message.
-
-        """
-        from app.features.ytdlp.utils import archive_add
-
-        ret: tuple[bool, str] | dict[str, Any] = await self._mark_logic()
-        if isinstance(ret, tuple):
-            return ret
-
-        archive_file = ret.get("file")
-        items = ret.get("items", set())
-        if not isinstance(archive_file, Path) or not isinstance(items, set):
-            return (False, "Failed to get archive information.")
-        archive_items = [item for item in items if isinstance(item, str)]
-
-        if len(archive_items) < 1 or not archive_add(archive_file, archive_items):
-            return (True, "No new items to mark as downloaded.")
-
-        return (True, f"Task '{self.name}' items marked as downloaded.")
-
-    async def unmark(self) -> tuple[bool, str]:
-        """
-        Unmark the task's items from the archive file.
-
-        Returns:
-            tuple[bool, str]: A tuple indicating success and a message.
-
-        """
-        from app.features.ytdlp.utils import archive_delete
-
-        ret: tuple[bool, str] | dict[str, Any] = await self._mark_logic()
-        if isinstance(ret, tuple):
-            return ret
-
-        archive_file = ret.get("file")
-        items = ret.get("items", set())
-        if not isinstance(archive_file, Path) or not isinstance(items, set):
-            return (False, "Failed to get archive information.")
-        archive_items = [item for item in items if isinstance(item, str)]
-
-        if len(archive_items) < 1 or not archive_delete(archive_file, archive_items):
-            return (True, "No items to remove from archive file.")
-
-        return (True, f"Removed '{self.name}' items from archive file.")
-
-    async def fetch_metadata(self, full: bool = False) -> tuple[dict[str, Any] | None, bool, str]:
-        """
-        Fetch metadata for the task's URL.
-
-        Args:
-            full (bool): Whether to fetch full metadata including all entries for playlists.
-
-        Returns:
-            tuple[dict[str, Any]|None, bool, str]: A tuple containing the metadata (or None on failure), a boolean
-            indicating if the operation was successful, and a message.
-
-        """
-        from app.features.ytdlp.extractor import fetch_info
-
-        if not self.url:
-            return ({}, False, "No URL found in task parameters.")
-
-        params = self.get_ytdlp_opts()
-        if not full:
-            params.add_cli("-I0", from_user=False)
-
-        params_dict = params.get_all()
-
-        (ie_info, _) = await fetch_info(
-            params_dict,
-            self.url,
-            no_archive=True,
-            follow_redirect=False,
-            sanitize_info=True,
-            budget_sleep=True,
-        )
-
-        if not ie_info or not isinstance(ie_info, dict):
-            return ({}, False, "Failed to extract information from URL.")
-
-        return (ie_info, True, "")
-
-    async def _mark_logic(self) -> tuple[bool, str] | dict[str, Any]:
-        """
-        Internal logic for marking/un-marking items.
-
-        Returns:
-            tuple[bool, str] | dict[str, Any]: Either an error tuple or a dict with 'file' and 'items' keys.
-
-        """
-        from app.features.ytdlp.extractor import fetch_info
-
-        if not self.url:
-            return (False, "No URL found in task parameters.")
-
-        params: dict = self.get_ytdlp_opts().get_all()
-        if not (archive_file := params.get("download_archive")):
-            return (False, "No archive file found.")
-
-        archive_file: Path = Path(archive_file)
-
-        (ie_info, _) = await fetch_info(params, self.url, no_archive=True, follow_redirect=True, budget_sleep=True)
-        if not ie_info or not isinstance(ie_info, dict):
-            return (False, "Failed to extract information from URL.")
-
-        if "playlist" != ie_info.get("_type"):
-            return (False, "Expected a playlist type from extract_info.")
-
-        items: set[str] = set()
-
-        def _process(item: dict):
-            for entry in item.get("entries", []):
-                if not isinstance(entry, dict):
-                    continue
-
-                if "playlist" == entry.get("_type"):
-                    _process(entry)
-                    continue
-
-                if entry.get("_type") not in ("video", "url"):
-                    continue
-
-                if not entry.get("id") or not entry.get("ie_key"):
-                    continue
-
-                archive_id: str = f"{entry.get('ie_key', '').lower()} {entry.get('id')}"
-
-                items.add(archive_id)
-
-        _process(ie_info)
-
-        return {"file": archive_file, "items": items}
-
-
-@dataclass(slots=True)
-class TaskItem:
-    """Represents a single item in a task result."""
-
-    url: str
-    "The URL of the item."
-    title: str | None = None
-    "The title of the item."
-    archive_id: str | None = None
-    "The archive ID of the item."
-    metadata: dict[str, Any] = field(default_factory=dict)
-    "Additional metadata related to the item."
-
-
-@dataclass(slots=True)
-class TaskResult:
-    """Represents a successful task handler execution result."""
-
-    items: list[TaskItem] = field(default_factory=list)
-    "The list of items."
-    metadata: dict[str, Any] = field(default_factory=dict)
-    "Additional metadata related to the result."
-
-    def serialize(self) -> dict[str, Any]:
-        primary, extra = split_inspect_metadata(self.metadata)
-        payload: dict[str, Any] = {**primary, "items": [asdict(item) for item in self.items]}
-
-        if extra:
-            payload["metadata"] = extra
-
-        return payload
-
-
-@dataclass(slots=True)
-class TaskFailure:
-    """Represents a failed task handler execution result."""
-
-    message: str
-    "A human-readable message describing the failure."
-    error: str | None = None
-    "An optional error code or string."
-    metadata: dict[str, Any] = field(default_factory=dict)
-    "Additional metadata related to the failure."
-
-    def serialize(self) -> dict[str, Any]:
-        primary, extra = split_inspect_metadata(self.metadata)
-        payload: dict[str, Any] = dict(primary)
-
-        if self.error:
-            payload["error"] = self.error
-
-        if self.message and (not self.error or self.message != self.error):
-            payload["message"] = self.message
-
-        if extra:
-            payload["metadata"] = extra
-
-        return payload

app/features/tasks/definitions/router.py

@@ -1,255 +0,0 @@
-from typing import Any
-
-from aiohttp import web
-from aiohttp.web import Request, Response
-from pydantic import ValidationError
-
-from app.features.core.schemas import CEAction, CEFeature, ConfigEvent, Pagination
-from app.features.core.utils import build_pagination, format_validation_errors, normalize_pagination
-from app.features.tasks.definitions.repository import TaskDefinitionsRepository as Repo
-from app.features.tasks.definitions.schemas import (
-    TaskDefinition,
-    TaskDefinitionList,
-    TaskDefinitionPatch,
-)
-from app.features.tasks.definitions.utils import model_to_schema, schema_to_payload
-from app.library.encoder import Encoder
-from app.library.Events import EventBus, Events
-from app.library.log import get_logger
-from app.library.router import route
-
-LOG = get_logger()
-
-
-@route("GET", "api/tasks/definitions/", "task_definitions")
-async def task_definitions_list(request: Request, encoder: Encoder, repo: Repo) -> Response:
-    page, per_page = normalize_pagination(request)
-    models, total, current_page, total_pages = await repo.list_paginated(page, per_page)
-
-    include: str | None = request.query.get("include")
-    summary: bool = "definition" != include
-
-    return web.json_response(
-        data=TaskDefinitionList(
-            items=[model_to_schema(model, summary=summary) for model in models],
-            pagination=Pagination.model_validate(build_pagination(total, current_page, per_page, total_pages)),
-        ),
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("GET", r"api/tasks/definitions/{id:\d+}", "task_definitions_get")
-async def task_definitions_get(request: Request, encoder: Encoder, repo: Repo) -> Response:
-    identifier: str = request.match_info.get("id", "").strip()
-    if not identifier:
-        return web.json_response(
-            data={"error": "Missing task definition identifier."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if not (model := await repo.get(identifier)):
-        return web.json_response(
-            data={"error": f"Task definition '{identifier}' not found."},
-            status=web.HTTPNotFound.status_code,
-        )
-
-    definition = model_to_schema(model)
-    return web.json_response(data=definition, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("POST", "api/tasks/definitions/", "task_definitions_create")
-async def task_definitions_create(request: Request, encoder: Encoder, notify: EventBus, repo: Repo) -> Response:
-    try:
-        payload: Any = await request.json()
-    except Exception:
-        return web.json_response(
-            data={"error": "Invalid JSON in request body."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if not isinstance(payload, dict):
-        return web.json_response(
-            data={"error": "Invalid request body; expected JSON object."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        definition_input = TaskDefinition.model_validate(payload)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate task definition.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        repo_payload = schema_to_payload(definition_input)
-        model = await repo.create(repo_payload)
-        definition = model_to_schema(model)
-
-        notify.emit(
-            Events.CONFIG_UPDATE,
-            data=ConfigEvent(feature=CEFeature.TASKS_DEFINITIONS, action=CEAction.CREATE, data=definition.model_dump()),
-        )
-        return web.json_response(data=definition, status=web.HTTPCreated.status_code, dumps=encoder.encode)
-    except ValueError as exc:
-        return web.json_response(data={"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-    except Exception as exc:
-        LOG.exception(
-            "Failed to create task definition '%s'.",
-            getattr(definition_input, "name", None),
-            extra={"definition": getattr(definition_input, "name", None), "exception_type": type(exc).__name__},
-        )
-        return web.json_response(
-            data={"error": "Failed to create task definition."},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-
-@route("PUT", r"api/tasks/definitions/{id:\d+}", "task_definitions_update")
-async def task_definitions_update(request: Request, encoder: Encoder, notify: EventBus, repo: Repo) -> Response:
-    if not (identifier := request.match_info.get("id", "").strip()):
-        return web.json_response(
-            data={"error": "Missing task definition identifier."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        payload: dict | None = await request.json()
-    except Exception:
-        return web.json_response(
-            data={"error": "Invalid JSON in request body."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if not isinstance(payload, dict):
-        return web.json_response(
-            data={"error": "Invalid request body; expected JSON object."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        definition_input: TaskDefinition = TaskDefinition.model_validate(payload)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate task definition.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        definition: TaskDefinition = model_to_schema(await repo.update(identifier, schema_to_payload(definition_input)))
-        notify.emit(
-            Events.CONFIG_UPDATE,
-            data=ConfigEvent(feature=CEFeature.TASKS_DEFINITIONS, action=CEAction.UPDATE, data=definition.model_dump()),
-        )
-        return web.json_response(data=definition, status=web.HTTPOk.status_code, dumps=encoder.encode)
-    except KeyError as exc:
-        return web.json_response(data={"error": str(exc)}, status=web.HTTPNotFound.status_code)
-    except ValueError as exc:
-        return web.json_response(data={"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-    except Exception as exc:
-        LOG.exception(
-            "Failed to update task definition '%s'.",
-            definition_input.name,
-            extra={
-                "definition_id": identifier,
-                "definition": definition_input.name,
-                "exception_type": type(exc).__name__,
-            },
-        )
-        return web.json_response(
-            data={"error": "Failed to update task definition."},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-
-@route("PATCH", r"api/tasks/definitions/{id:\d+}", "task_definitions_patch")
-async def task_definitions_patch(request: Request, encoder: Encoder, notify: EventBus, repo: Repo) -> Response:
-    if not (identifier := request.match_info.get("id", "").strip()):
-        return web.json_response(
-            data={"error": "Missing task definition identifier."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if not await repo.get(identifier):
-        return web.json_response(
-            data={"error": f"Task definition '{identifier}' not found."},
-            status=web.HTTPNotFound.status_code,
-        )
-
-    try:
-        payload: dict | None = await request.json()
-    except Exception:
-        return web.json_response(
-            data={"error": "Invalid JSON in request body."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if not isinstance(payload, dict):
-        return web.json_response(
-            data={"error": "Invalid request body; expected JSON object."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        patch_input: TaskDefinitionPatch = TaskDefinitionPatch.model_validate(payload)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate task definition patch.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        definition: TaskDefinition = model_to_schema(
-            await repo.update(identifier, patch_input.model_dump(exclude_unset=True))
-        )
-
-        notify.emit(
-            Events.CONFIG_UPDATE,
-            data=ConfigEvent(feature=CEFeature.TASKS_DEFINITIONS, action=CEAction.UPDATE, data=definition.model_dump()),
-        )
-        return web.json_response(data=definition, status=web.HTTPOk.status_code, dumps=encoder.encode)
-    except KeyError as exc:
-        return web.json_response(data={"error": str(exc)}, status=web.HTTPNotFound.status_code)
-    except ValueError as exc:
-        return web.json_response(data={"error": str(exc)}, status=web.HTTPBadRequest.status_code)
-    except Exception as exc:
-        LOG.exception(
-            "Failed to patch task definition '%s'.",
-            identifier,
-            extra={"definition_id": identifier, "exception_type": type(exc).__name__},
-        )
-        return web.json_response(
-            data={"error": "Failed to patch task definition."},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-
-@route("DELETE", r"api/tasks/definitions/{id:\d+}", "task_definitions_delete")
-async def task_definitions_delete(request: Request, encoder: Encoder, notify: EventBus, repo: Repo) -> Response:
-    if not (identifier := request.match_info.get("id", "").strip()):
-        return web.json_response(
-            data={"error": "Missing task definition identifier."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        definition: TaskDefinition = model_to_schema(await repo.delete(identifier))
-
-        notify.emit(
-            Events.CONFIG_UPDATE,
-            data=ConfigEvent(feature=CEFeature.TASKS_DEFINITIONS, action=CEAction.DELETE, data=definition.model_dump()),
-        )
-        return web.json_response(data=definition, status=web.HTTPOk.status_code, dumps=encoder.encode)
-    except KeyError as exc:
-        return web.json_response(data={"error": str(exc)}, status=web.HTTPNotFound.status_code)
-    except Exception as exc:
-        LOG.exception(
-            "Failed to delete task definition '%s'.",
-            identifier,
-            extra={"definition_id": identifier, "exception_type": type(exc).__name__},
-        )
-        return web.json_response(
-            data={"error": "Failed to delete task definition."},
-            status=web.HTTPInternalServerError.status_code,
-        )

app/features/tasks/definitions/schemas.py

@@ -1,222 +0,0 @@
-from __future__ import annotations
-
-import re
-from datetime import datetime  # noqa: TC003
-from typing import Any, Literal
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
-
-from app.features.core.schemas import Pagination
-from app.features.core.utils import parse_int
-
-
-class PostFilter(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True)
-    filter: str = Field(min_length=1)
-    value: str | None = None
-
-    @field_validator("filter")
-    @classmethod
-    def _validate_filter(cls, value: str) -> str:
-        try:
-            re.compile(value)
-        except re.error as exc:
-            msg: str = f"Invalid post_filter regex pattern: {exc}"
-            raise ValueError(msg) from exc
-        return value
-
-
-class ExtractionRule(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True)
-    type: Literal["css", "xpath", "regex", "jsonpath"]
-    expression: str = Field(min_length=1)
-    attribute: str | None = None
-    post_filter: PostFilter | None = None
-
-    def __getitem__(self, key: str) -> Any:
-        """Support bracket notation access."""
-        if not hasattr(self, key):
-            raise KeyError(key)
-        return getattr(self, key)
-
-
-class ParseItems(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True)
-    type: Literal["css", "xpath", "jsonpath"] = "css"
-    selector: str | None = Field(None, min_length=1)
-    expression: str | None = Field(None, min_length=1)
-    fields: dict[str, ExtractionRule]
-
-    def get(self, key: str, default: Any = None) -> Any:
-        """Get a field value by key, supporting dict-like access."""
-        return getattr(self, key, default)
-
-    def __getitem__(self, key: str) -> Any:
-        """Support bracket notation access."""
-        if not hasattr(self, key):
-            raise KeyError(key)
-        return getattr(self, key)
-
-    @model_validator(mode="after")
-    def _validate_items(self) -> ParseItems:
-        if not self.selector and not self.expression:
-            msg = "Either 'selector' or 'expression' must be provided."
-            raise ValueError(msg)
-        if not self.selector:
-            self.selector = self.expression
-        if "link" not in self.fields:
-            msg = "Container 'fields' must include a 'link' field."
-            raise ValueError(msg)
-        return self
-
-
-class Parse(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, extra="allow")
-    items: ParseItems | None = None
-
-    def get(self, key: str, default: Any = None) -> Any:
-        """Get a field value by key, supporting dict-like access."""
-        return getattr(self, key, default)
-
-    def field_items(self) -> list[tuple[str, Any]]:
-        """Return field items like a dict, excluding private fields and 'items'."""
-        data: dict[str, Any] = self.model_dump()
-        return [(k, v) for k, v in data.items() if k not in ("items",)]
-
-    def __getitem__(self, key: str) -> Any:
-        """Support bracket notation access."""
-        if not hasattr(self, key):
-            raise KeyError(key)
-        return getattr(self, key)
-
-    def __contains__(self, key: str) -> bool:
-        """Support 'in' operator."""
-        return hasattr(self, key) and not key.startswith("_")
-
-    @model_validator(mode="before")
-    @classmethod
-    def _validate_parse(cls, value: Any) -> Any:
-        """Validate that we have either items or direct parsers with link."""
-        if not isinstance(value, dict):
-            msg: str = "Parse must be a dict"
-            raise ValueError(msg)
-
-        has_items: bool = "items" in value and value["items"] is not None
-        direct_parsers: dict[str, Any] = {
-            k: v for k, v in value.items() if k not in ("items",) and not k.startswith("_")
-        }
-        has_direct_parsers: bool = len(direct_parsers) > 0
-        has_link_parser: bool = "link" in direct_parsers
-
-        if not has_items and not has_direct_parsers:
-            msg: str = "Field 'parse' must contain either 'items' or direct parsers."
-            raise ValueError(msg)
-
-        if not has_items and not has_link_parser:
-            msg: str = "Missing required 'link' parser definition."
-            raise ValueError(msg)
-
-        for field_name, field_value in direct_parsers.items():
-            if not isinstance(field_value, dict):
-                msg: str = f"Parse field '{field_name}' must be an object."
-                raise ValueError(msg)
-
-        return value
-
-
-class EngineConfig(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True)
-    type: Literal["httpx", "selenium"] = "httpx"
-    options: dict[str, Any] = Field(default_factory=dict)
-
-
-class RequestConfig(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True, protected_namespaces=())
-    method: str = "GET"
-    headers: dict[str, str] = Field(default_factory=dict)
-    params: dict[str, Any] = Field(default_factory=dict)
-    data: dict[str, Any] | None = None
-    json_data: dict[str, Any] | None = None
-    timeout: float | None = None
-    url: str | None = None
-
-
-class ResponseConfig(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True)
-    type: Literal["html", "json"] = "html"
-
-
-class Definition(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True)
-    parse: Parse
-    engine: EngineConfig = Field(default_factory=EngineConfig)
-    request: RequestConfig = Field(default_factory=RequestConfig)
-    response: ResponseConfig = Field(default_factory=ResponseConfig)
-
-
-class TaskDefinitionSummary(BaseModel):
-    model_config = ConfigDict(from_attributes=True, str_strip_whitespace=True)
-    id: int | None = None
-    name: str = Field(min_length=1)
-    priority: int = Field(default=0, ge=0)
-    match_url: list[str] = Field(min_length=1)
-    enabled: bool = Field(default=True)
-    created_at: datetime | None = None
-    updated_at: datetime | None = None
-
-
-class TaskDefinition(TaskDefinitionSummary):
-    definition: Definition
-
-    @field_validator("priority", mode="before")
-    @classmethod
-    def _normalize_priority(cls, value: Any) -> int:
-        if value is None:
-            return 0
-        return parse_int(value, field="Priority", minimum=0)
-
-    @field_validator("match_url", mode="before")
-    @classmethod
-    def _validate_match_url(cls, value: Any) -> list[str]:
-        """Validate that match_url is a list of strings and validate regex patterns."""
-        if not isinstance(value, list):
-            msg = "match_url must be a list"
-            raise ValueError(msg)
-
-        validated: list[str] = []
-        for item in value:
-            if not isinstance(item, str):
-                msg: str = f"match_url items must be strings, got {type(item).__name__}"
-                raise ValueError(msg)
-
-            item: str = item.strip()
-            if not item:
-                msg = "match_url items cannot be empty"
-                raise ValueError(msg)
-
-            if item.startswith("/") and item.endswith("/") and len(item) > 2:
-                pattern = item[1:-1]
-                try:
-                    re.compile(pattern)
-                except re.error as exc:
-                    msg = f"Invalid regex pattern '{pattern}': {exc}"
-                    raise ValueError(msg) from exc
-
-            validated.append(item)
-
-        return validated
-
-
-class TaskDefinitionPatch(TaskDefinition):
-    model_config = ConfigDict(str_strip_whitespace=True)
-    name: str | None = None
-    priority: int | None = None
-    match_url: list[str] | None = None
-    definition: Definition | None = None
-    enabled: bool | None = None
-
-
-class TaskDefinitionList(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-    items: list[TaskDefinitionSummary | TaskDefinition] = Field(default_factory=list)
-    pagination: Pagination

app/features/tasks/definitions/service.py

@@ -1,629 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import importlib
-import inspect
-import pkgutil
-import random
-from datetime import UTC, datetime
-from typing import TYPE_CHECKING, Any
-
-from app.features.tasks.definitions.handlers._base_handler import BaseHandler
-from app.features.tasks.definitions.results import HandleTask, TaskFailure, TaskItem, TaskResult
-from app.features.tasks.models import TaskModel
-from app.features.ytdlp.utils import archive_read
-from app.library.downloads.queue_manager import DownloadQueue
-from app.library.Events import EventBus, Events
-from app.library.ItemDTO import Item, ItemDTO
-from app.library.log import get_logger
-from app.library.Services import Services
-
-if TYPE_CHECKING:
-    from app.features.tasks.repository import TasksRepository
-    from app.library.config import Config
-    from app.library.Scheduler import Scheduler
-
-LOG = get_logger()
-
-
-class TaskHandle:
-    def __init__(self, scheduler: Scheduler, tasks: TasksRepository, config: Config) -> None:
-        self._handlers: list[type[BaseHandler]] = []
-        "The available handlers."
-        self._repo: TasksRepository = tasks
-        "The tasks manager."
-        self._scheduler: Scheduler = scheduler
-        "The scheduler."
-        self._config: Config = config
-        "The configuration."
-        self._task_name: str = f"{TaskHandle.__name__}._dispatcher"
-        "The task name for the scheduler."
-        self._queued: dict[str, set[str]] = {}
-        "Queued archive IDs per handler."
-        self._failure_count: dict[str, dict[str, int]] = {}
-        "Failure counts per handler and archive ID."
-
-        EventBus.get_instance().subscribe(
-            Events.ITEM_ERROR,
-            self._handle_item_error,
-            f"{TaskHandle.__name__}.item_error",
-        )
-
-    def load(self) -> None:
-        self._handlers: list[type[BaseHandler]] = self._discover()
-
-        timer: str = self._config.tasks_handler_timer
-        try:
-            from cronsim import CronSim
-
-            CronSim(timer, datetime.now(UTC))
-        except Exception as e:
-            timer = "15 */1 * * *"
-            LOG.error(
-                "Invalid task handler timer '%s'; using default '%s'.",
-                self._config.tasks_handler_timer,
-                timer,
-                extra={
-                    "timer": self._config.tasks_handler_timer,
-                    "default_timer": timer,
-                    "exception_type": type(e).__name__,
-                },
-            )
-
-        self._scheduler.add(
-            timer=timer,
-            func=lambda: asyncio.create_task(self._dispatcher(), name="task-handler-dispatcher"),
-            id=f"{TaskHandle.__name__}._dispatcher",
-        )
-
-    async def _dispatcher(self):
-        s: dict[str, list[str]] = {"h": [], "d": [], "u": [], "f": []}
-
-        handler_groups: dict[str, list[tuple[HandleTask, type[BaseHandler]]]] = {}
-        dispatches: list[tuple[HandleTask, type[BaseHandler], asyncio.Task[TaskResult | TaskFailure | None]]] = []
-
-        tasks: list[TaskModel] = await self._repo.all()
-
-        for task_model in tasks:
-            task: HandleTask = HandleTask.model_validate(task_model)
-
-            if not task.enabled or not task.handler_enabled:
-                s["d"].append(task.name)
-                continue
-
-            if not task.get_ytdlp_opts().get_all().get("download_archive"):
-                LOG.debug(
-                    "Task '%s' does not have an archive file configured.",
-                    task.name,
-                    extra={"task_id": task.id, "task_name": task.name},
-                )
-                s["f"].append(task.name)
-                continue
-
-            try:
-                handler: type[BaseHandler] | None = await self._find_handler(task)
-                if handler is None:
-                    s["u"].append(task.name)
-                    continue
-
-                handler_name: str = handler.__name__
-                if handler_name not in handler_groups:
-                    handler_groups[handler_name] = []
-                handler_groups[handler_name].append((task, handler))
-            except Exception as e:
-                LOG.exception(
-                    "Failed to find handler for task '%s'.",
-                    task.name,
-                    extra={"task_id": task.id, "task_name": task.name, "exception_type": type(e).__name__},
-                )
-                s["f"].append(task.name)
-
-        for tasks_with_handlers in handler_groups.values():
-            for idx, (task, handler) in enumerate(tasks_with_handlers):
-                try:
-                    t: asyncio.Task[TaskResult | TaskFailure | None] = asyncio.create_task(
-                        coro=self._dispatch(
-                            task,
-                            handler,
-                            delay=0.0 if 0 == idx else random.uniform(1.0, self._config.task_handler_random_delay),
-                        ),
-                        name=f"taskHandler-{task.id}",
-                    )
-                    t.add_done_callback(lambda fut, t=task: self._handle_exception(fut, t))
-                    dispatches.append((task, handler, t))
-                except Exception as e:
-                    LOG.exception(
-                        "Failed to schedule handler '%s' for task '%s'.",
-                        handler.__name__,
-                        task.name,
-                        extra={
-                            "task_id": task.id,
-                            "task_name": task.name,
-                            "handler_name": handler.__name__,
-                            "exception_type": type(e).__name__,
-                        },
-                    )
-                    s["f"].append(task.name)
-
-        if dispatches:
-            results = await asyncio.gather(*(t for _, _, t in dispatches), return_exceptions=True)
-
-            for (task, handler, _), result in zip(dispatches, results, strict=True):
-                if isinstance(result, TaskResult):
-                    s["h"].append(task.name)
-                    continue
-
-                if isinstance(result, TaskFailure):
-                    s["f"].append(task.name)
-                    continue
-
-                if result is None:
-                    LOG.error(
-                        "Handler '%s' returned no result for task '%s'.",
-                        handler.__name__,
-                        task.name,
-                        extra={"task_id": task.id, "task_name": task.name, "handler_name": handler.__name__},
-                    )
-
-                s["f"].append(task.name)
-
-        if len(tasks) > 0:
-            LOG.info(
-                "Task dispatch finished: %s handled, %s unhandled, %s disabled, %s failed.",
-                len(s["h"]),
-                len(s["u"]),
-                len(s["d"]),
-                len(s["f"]),
-                extra={
-                    "handled_count": len(s["h"]),
-                    "unhandled_count": len(s["u"]),
-                    "disabled_count": len(s["d"]),
-                    "failed_count": len(s["f"]),
-                },
-            )
-
-    async def _dispatch(
-        self, task: HandleTask, handler: type[BaseHandler], delay: float
-    ) -> TaskResult | TaskFailure | None:
-        """
-        Dispatch a task after a random delay to avoid rate limiting.
-
-        Args:
-            task: The task to dispatch.
-            handler: The handler to use.
-            delay: The delay in seconds before dispatching.
-
-        Returns:
-            The dispatch result.
-
-        """
-        if delay > 0:
-            LOG.debug(
-                "Delaying dispatch of task '%s' by %.1f seconds.",
-                task.name,
-                delay,
-                extra={"task_id": task.id, "task_name": task.name, "delay_s": round(delay, 1)},
-            )
-            await asyncio.sleep(delay)
-        return await self.dispatch(task, handler=handler)
-
-    def _handle_exception(self, fut: asyncio.Task, task: HandleTask) -> None:
-        if fut.cancelled():
-            return
-
-        if exc := fut.exception():
-            LOG.exception(
-                "Task handler raised after dispatch.",
-                extra={"task_id": task.id, "task_name": task.name, "exception_type": type(exc).__name__},
-                exc_info=(type(exc), exc, exc.__traceback__),
-            )
-
-    async def _find_handler(self, task: HandleTask) -> type[BaseHandler] | None:
-        for cls in self._handlers:
-            try:
-                if await Services.get_instance().handle_async(handler=cls.can_handle, task=task):
-                    return cls
-            except Exception as e:
-                LOG.exception(
-                    "Handler '%s' capability check failed for task '%s'.",
-                    cls.__name__,
-                    task.name,
-                    extra={
-                        "task_id": task.id,
-                        "task_name": task.name,
-                        "handler_name": cls.__name__,
-                        "exception_type": type(e).__name__,
-                    },
-                )
-                continue
-
-        return None
-
-    async def dispatch(
-        self,
-        task: HandleTask,
-        handler: type[BaseHandler] | None = None,
-        **kwargs,
-    ) -> TaskResult | TaskFailure | None:
-        _ = kwargs
-        """
-        Dispatch a task to the appropriate handler.
-
-        Args:
-            task: The task to dispatch.
-            handler: Optional specific handler to use instead of finding one.
-            **kwargs: Additional context to pass to the handler.
-
-        Returns:
-            The extraction outcome, or None if no handler matched.
-
-        """
-        if not handler:
-            handler = await self._find_handler(task)
-            if handler is None:
-                return None
-
-        services: Services = Services.get_instance()
-
-        try:
-            extraction: TaskResult | TaskFailure = await services.handle_async(
-                handler=handler.extract, task=task, config=self._config
-            )
-        except NotImplementedError as exc:
-            LOG.exception(
-                "Task handler '%s' does not implement extraction for task '%s'.",
-                handler.__name__,
-                task.name,
-                extra={
-                    "task_id": task.id,
-                    "task_name": task.name,
-                    "handler_name": handler.__name__,
-                    "exception_type": type(exc).__name__,
-                },
-            )
-            return TaskFailure(message="Handler does not support extraction.")
-        except Exception as exc:
-            LOG.exception(
-                "Handler '%s' extraction failed for task '%s'.",
-                handler.__name__,
-                task.name,
-                extra={
-                    "task_id": task.id,
-                    "task_name": task.name,
-                    "handler_name": handler.__name__,
-                    "exception_type": type(exc).__name__,
-                },
-            )
-            raise
-
-        if isinstance(extraction, TaskFailure):
-            msg: str = extraction.message
-            if extraction.error and extraction.error != extraction.message:
-                msg = f"{msg} {extraction.error}"
-
-            LOG.error(
-                "Handler '%s' failed to extract items for task '%s' because %s.",
-                handler.__name__,
-                task.name,
-                msg,
-                extra={"task_id": task.id, "task_name": task.name, "handler_name": handler.__name__, "error": msg},
-            )
-            return extraction
-
-        if not isinstance(extraction, TaskResult):
-            LOG.error(
-                "Handler '%s' returned unexpected result type '%s' for task '%s'.",
-                handler.__name__,
-                type(extraction).__name__,
-                task.name,
-                extra={
-                    "task_id": task.id,
-                    "task_name": task.name,
-                    "handler_name": handler.__name__,
-                    "result_type": type(extraction).__name__,
-                },
-            )
-            return TaskFailure(
-                message="Handler returned invalid result type.", metadata={"type": type(extraction).__name__}
-            )
-
-        raw_items: list[TaskItem] = extraction.items or []
-        metadata: dict[str, Any] = extraction.metadata or {}
-
-        handler_name: str = handler.__name__
-        queued: set[str] = self._queued.setdefault(handler_name, set())
-        failures: dict[str, int] = self._failure_count.setdefault(handler_name, {})
-
-        params: dict = task.get_ytdlp_opts().get_all()
-        archive_file: str | None = params.get("download_archive")
-
-        download_queue: DownloadQueue = services.get("queue") or DownloadQueue.get_instance()
-        notify: EventBus = services.get("notify") or EventBus.get_instance()
-
-        archive_ids: list[str] = [
-            item.archive_id for item in raw_items if isinstance(item, TaskItem) and item.archive_id
-        ]
-        downloaded: list[str] = archive_read(archive_file, archive_ids) if archive_file else []
-
-        filtered: list[TaskItem] = []
-
-        for item in raw_items:
-            if not isinstance(item, TaskItem):
-                LOG.warning(
-                    "Handler '%s' returned unexpected item type '%s' for task '%s'.",
-                    handler.__name__,
-                    type(item).__name__,
-                    task.name,
-                    extra={
-                        "task_id": task.id,
-                        "task_name": task.name,
-                        "handler_name": handler.__name__,
-                        "item_type": type(item).__name__,
-                    },
-                )
-                continue
-
-            url: str = item.url
-            if not url:
-                continue
-
-            archive_id: str | None = item.archive_id
-            if not archive_id:
-                LOG.warning(
-                    "Handler '%s' skipped '%s' for task '%s' because it has no archive ID.",
-                    handler.__name__,
-                    url,
-                    task.name,
-                    extra={"task_id": task.id, "task_name": task.name, "handler_name": handler.__name__, "url": url},
-                )
-                continue
-
-            if archive_id in queued:
-                continue
-
-            queued.add(archive_id)
-
-            if archive_file and archive_id in downloaded:
-                continue
-
-            if await download_queue.queue.exists(url=url):
-                continue
-
-            try:
-                done = await download_queue.done.get(url=url)
-                if "error" != done.info.status:
-                    continue
-            except KeyError:
-                pass
-
-            if archive_id not in failures:
-                failures[archive_id] = 0
-
-            filtered.append(item)
-
-        if not filtered:
-            if raw_items:
-                LOG.debug(
-                    "Handler '%s' found %s item(s) for task '%s', but none were queued.",
-                    handler.__name__,
-                    len(raw_items),
-                    task.name,
-                    extra={
-                        "task_id": task.id,
-                        "task_name": task.name,
-                        "handler_name": handler.__name__,
-                        "raw_count": len(raw_items),
-                    },
-                )
-            return TaskResult(items=[], metadata=metadata)
-
-        LOG.info(
-            "Handler '%s' found %s new item(s) for task '%s'.",
-            handler.__name__,
-            len(filtered),
-            task.name,
-            extra={
-                "task_id": task.id,
-                "task_name": task.name,
-                "handler_name": handler.__name__,
-                "item_count": len(filtered),
-                "raw_count": len(raw_items),
-            },
-        )
-
-        base_item = Item.format(
-            {
-                "url": task.url,
-                "preset": task.preset or self._config.default_preset,
-                "folder": task.folder or "",
-                "template": task.template or "",
-                "cli": task.cli or "",
-                "auto_start": task.auto_start,
-                "extras": {"source_name": task.name, "source_id": task.id, "source_handler": handler.__name__},
-            }
-        )
-
-        for item in filtered:
-            metadata_entry: dict[str, Any] = item.metadata if isinstance(item.metadata, dict) else {}
-            extras: dict[str, Any] = base_item.extras.copy()
-            if metadata_entry:
-                extras["metadata"] = metadata_entry
-
-            notify.emit(
-                Events.ADD_URL,
-                data=base_item.new_with(url=item.url, extras=extras).serialize(),
-            )
-
-        return TaskResult(items=filtered, metadata=metadata)
-
-    async def inspect(
-        self,
-        url: str,
-        preset: str | None = None,
-        handler_name: str | None = None,
-        static_only: bool = False,
-    ) -> TaskResult | TaskFailure:
-        """
-        Inspect a URL to find a matching handler and optionally extract items.
-
-        Args:
-            url: The URL to inspect.
-            preset: Optional preset name to use.
-            handler_name: Optional specific handler name to use.
-            static_only: If True, only check if a handler matches without extraction.
-
-        Returns:
-            TaskResult or TaskFailure with inspection results.
-
-        """
-        if not self._handlers:
-            self._handlers = self._discover()
-
-        task = HandleTask(
-            id=None,
-            name="Inspector",
-            url=url,
-            preset=preset or self._config.default_preset,
-            auto_start=False,
-        )
-
-        services = Services.get_instance()
-
-        handler_cls: type | None
-        if handler_name:
-            handler_cls = next((cls for cls in self._handlers if cls.__name__.lower() == handler_name.lower()), None)
-            if handler_cls is None:
-                message: str = f"Handler '{handler_name}' not found."
-                return TaskFailure(
-                    message=message,
-                    error=message,
-                    metadata={"matched": False, "handler": handler_name},
-                )
-
-            try:
-                matched = await services.handle_async(handler=handler_cls.can_handle, task=task)
-            except Exception as exc:  # pragma: no cover - defensive
-                LOG.exception(
-                    "Handler '%s' inspection capability check failed for '%s'.",
-                    handler_cls.__name__,
-                    url,
-                    extra={"handler_name": handler_cls.__name__, "url": url, "exception_type": type(exc).__name__},
-                )
-                message = str(exc)
-                return TaskFailure(
-                    message=message,
-                    error=message,
-                    metadata={"matched": False, "handler": handler_cls.__name__},
-                )
-
-            if not matched:
-                return TaskFailure(
-                    message="Handler cannot process the supplied URL.",
-                    metadata={"matched": False, "handler": handler_cls.__name__},
-                )
-        else:
-            handler_cls = await self._find_handler(task)
-            if handler_cls is None:
-                message = "No handler matched the supplied URL."
-                return TaskFailure(
-                    message=message,
-                    error=message,
-                    metadata={"matched": False, "handler": None},
-                )
-
-        base_metadata: dict[str, Any] = {"matched": True, "handler": handler_cls.__name__}
-
-        if static_only:
-            return TaskResult(items=[], metadata=base_metadata)
-
-        try:
-            extraction: TaskResult | TaskFailure = await services.handle_async(
-                handler=handler_cls.extract, task=task, config=self._config
-            )
-        except NotImplementedError:
-            return TaskFailure(
-                message="Handler does not support manual inspection.",
-                metadata={**base_metadata, "supported": False},
-            )
-        except Exception as exc:
-            LOG.exception(
-                "Handler '%s' manual inspection failed for '%s'.",
-                handler_cls.__name__,
-                url,
-                extra={"handler_name": handler_cls.__name__, "url": url, "exception_type": type(exc).__name__},
-            )
-            message = str(exc)
-            return TaskFailure(
-                message=message,
-                error=message,
-                metadata={**base_metadata, "supported": True},
-            )
-
-        if isinstance(extraction, TaskFailure):
-            combined_failure_metadata: dict[str, Any] = {**base_metadata, "supported": True}
-            if extraction.metadata:
-                combined_failure_metadata.update(extraction.metadata)
-
-            return TaskFailure(
-                message=extraction.message,
-                error=extraction.error or extraction.message,
-                metadata=combined_failure_metadata,
-            )
-
-        if not isinstance(extraction, TaskResult):
-            LOG.error(
-                "Handler '%s' returned unexpected result type '%s' while inspecting '%s'.",
-                handler_cls.__name__,
-                type(extraction).__name__,
-                url,
-                extra={"handler_name": handler_cls.__name__, "url": url, "result_type": type(extraction).__name__},
-            )
-            extraction = TaskResult()
-
-        combined_metadata: dict[str, Any] = {**base_metadata, "supported": True}
-        if extraction.metadata:
-            combined_metadata.update(extraction.metadata)
-
-        return TaskResult(items=list(extraction.items), metadata=combined_metadata)
-
-    def _discover(self) -> list[type[BaseHandler]]:
-        """Discover all available task handlers."""
-        import app.features.tasks.definitions.handlers as handlers_pkg
-
-        handlers: list[type[BaseHandler]] = []
-
-        for _, module_name, _ in pkgutil.iter_modules(handlers_pkg.__path__):
-            if module_name.startswith("_"):
-                continue
-
-            module = importlib.import_module(f"{handlers_pkg.__name__}.{module_name}")
-            for _, cls in inspect.getmembers(module, inspect.isclass):
-                if cls.__module__ != module.__name__:
-                    continue
-
-                if callable(getattr(cls, "can_handle", None)) and callable(getattr(cls, "extract", None)):
-                    handlers.append(cls)
-
-        return handlers
-
-    async def _handle_item_error(self, event, _name, **_kwargs):
-        """Handle item error events to clean up queued items and track failures."""
-        item: ItemDTO | None = getattr(event, "data", None)
-        if not isinstance(item, ItemDTO):
-            return
-
-        extras: dict[Any, Any] = getattr(item, "extras", {}) or {}
-        handler_name: Any | None = extras.get("source_handler")
-        if not handler_name:
-            return
-
-        archive_id: str | None = item.archive_id
-        if not archive_id:
-            return
-
-        queued: set[str] | None = self._queued.get(handler_name)
-        if queued:
-            queued.discard(archive_id)
-
-        failures: dict[str, int] = self._failure_count.setdefault(handler_name, {})
-        failures[archive_id] = failures.get(archive_id, 0) + 1

app/features/tasks/definitions/tests/test_generic_task_handler.py

@@ -1,402 +0,0 @@
-from datetime import datetime
-from unittest.mock import patch
-
-import pytest
-
-from app.features.tasks.definitions.handlers.generic import GenericTaskHandler
-from app.features.tasks.definitions.results import TaskFailure, TaskResult
-from app.features.tasks.definitions.schemas import (
-    Definition,
-    EngineConfig,
-    Parse,
-    RequestConfig,
-    ResponseConfig,
-    TaskDefinition,
-)
-from app.features.tasks.definitions.results import HandleTask
-
-
-@pytest.fixture(autouse=True)
-def reset_generic_handler(monkeypatch):
-    monkeypatch.setattr(GenericTaskHandler, "_definitions", [])
-    monkeypatch.setattr(GenericTaskHandler, "_sources_mtime", {})
-
-
-def test_build_def_payload():
-    definition = TaskDefinition(
-        id=1,
-        name="example",
-        priority=0,
-        match_url=["https://example.com/articles/*"],
-        created_at=datetime.now(),
-        updated_at=datetime.now(),
-        definition=Definition(
-            parse=Parse.model_validate(
-                {
-                    "link": {"type": "css", "expression": ".article a.link::attr(href)"},
-                    "title": {"type": "css", "expression": ".article .title", "attribute": "text"},
-                }
-            ),
-            engine=EngineConfig(),
-            request=RequestConfig(),
-            response=ResponseConfig(),
-        ),
-    )
-
-    assert definition.name == "example"
-    assert definition.match_url == ["https://example.com/articles/*"]
-    assert definition.definition.parse["link"]["expression"] == ".article a.link::attr(href)"
-
-
-def test_build_def_container():
-    definition = TaskDefinition(
-        id=2,
-        name="container",
-        priority=0,
-        match_url=["https://example.com/cards"],
-        created_at=datetime.now(),
-        updated_at=datetime.now(),
-        definition=Definition(
-            parse=Parse.model_validate(
-                {
-                    "items": {
-                        "selector": ".cards .card",
-                        "fields": {
-                            "link": {"type": "css", "expression": ".card-header a", "attribute": "href"},
-                            "title": {"type": "css", "expression": ".card-header a", "attribute": "text"},
-                        },
-                    }
-                }
-            ),
-            engine=EngineConfig(),
-            request=RequestConfig(),
-            response=ResponseConfig(),
-        ),
-    )
-
-    assert definition.definition.parse["items"]["selector"] == ".cards .card"
-    assert definition.definition.parse["items"]["fields"]["link"]["attribute"] == "href"
-
-
-def test_build_def_json():
-    definition = TaskDefinition(
-        id=3,
-        name="json-def",
-        priority=0,
-        match_url=["https://example.com/api"],
-        created_at=datetime.now(),
-        updated_at=datetime.now(),
-        definition=Definition(
-            parse=Parse.model_validate(
-                {
-                    "items": {
-                        "type": "jsonpath",
-                        "selector": "items",
-                        "fields": {
-                            "link": {"type": "jsonpath", "expression": "url"},
-                            "title": {"type": "jsonpath", "expression": "title"},
-                        },
-                    }
-                }
-            ),
-            engine=EngineConfig(),
-            request=RequestConfig(),
-            response=ResponseConfig(type="json"),
-        ),
-    )
-
-    assert definition.definition.response.type == "json"
-    assert definition.definition.parse["items"]["type"] == "jsonpath"
-    assert definition.definition.parse["items"]["fields"]["link"]["type"] == "jsonpath"
-
-
-def test_parse_items_basic():
-    definition = TaskDefinition(
-        id=4,
-        name="example",
-        priority=0,
-        match_url=["https://example.com/*"],
-        created_at=datetime.now(),
-        updated_at=datetime.now(),
-        definition=Definition(
-            parse=Parse.model_validate(
-                {
-                    "link": {"type": "css", "expression": ".article a.link::attr(href)", "attribute": None},
-                    "title": {"type": "css", "expression": ".article .title", "attribute": "text"},
-                    "id": {"type": "css", "expression": ".article", "attribute": "data-id"},
-                }
-            ),
-            engine=EngineConfig(),
-            request=RequestConfig(),
-            response=ResponseConfig(),
-        ),
-    )
-
-    html = """
-    <div class="article" data-id="101">
-      <a class="link" href="/article-101">First</a>
-      <span class="title">First Title</span>
-    </div>
-    <div class="article" data-id="102">
-      <a class="link" href="https://example.com/article-102">Second</a>
-      <span class="title">Second Title</span>
-    </div>
-    """
-
-    items = GenericTaskHandler._parse_items(definition, html, "https://example.com/base/")
-
-    assert len(items) == 2
-    assert items[0] == {
-        "link": "https://example.com/article-101",
-        "title": "First Title",
-        "id": "101",
-    }
-    assert items[1]["link"] == "https://example.com/article-102"
-
-
-def test_parse_items_cards():
-    definition = TaskDefinition(
-        id=5,
-        name="nested",
-        priority=0,
-        match_url=["https://example.com/*"],
-        created_at=datetime.now(),
-        updated_at=datetime.now(),
-        definition=Definition(
-            parse=Parse.model_validate(
-                {
-                    "items": {
-                        "type": "css",
-                        "selector": ".columns .card",
-                        "fields": {
-                            "link": {
-                                "type": "css",
-                                "expression": ".card-header a[href]",
-                                "attribute": "href",
-                            },
-                            "title": {
-                                "type": "css",
-                                "expression": ".card-header a[href]",
-                                "attribute": "text",
-                            },
-                            "poet": {
-                                "type": "css",
-                                "expression": "footer .card-footer-item:first-child a",
-                                "attribute": "text",
-                            },
-                            "category": {
-                                "type": "css",
-                                "expression": "footer .card-footer-item:nth-child(2) a",
-                                "attribute": "text",
-                            },
-                        },
-                    }
-                }
-            ),
-            engine=EngineConfig(),
-            request=RequestConfig(),
-            response=ResponseConfig(),
-        ),
-    )
-
-    html = """
-    <div class="columns is-multiline">
-      <div class="column is-6">
-        <div class="card">
-          <div class="card-header">
-            <p class="card-header-title is-4 has-text-centered is-block text-truncate">
-              <a href="/poems/view/111" title="First Poem">First Poem</a>
-            </p>
-          </div>
-          <footer class="card-footer has-text-centered">
-            <p class="card-footer-item text-truncate">
-              <span class="text-truncate"> By <a href="/poet/alpha">Poet Alpha</a></span>
-            </p>
-            <p class="card-footer-item text-truncate">
-              <span class="text-truncate"> In <a href="/category/one">Category One</a></span>
-            </p>
-          </footer>
-        </div>
-      </div>
-      <div class="column is-6">
-        <div class="card">
-          <div class="card-header">
-            <p class="card-header-title is-4 has-text-centered is-block text-truncate">
-              <a href="/poems/view/222" title="Second Poem">Second Poem</a>
-            </p>
-          </div>
-          <footer class="card-footer has-text-centered">
-            <p class="card-footer-item text-truncate">
-              <span class="text-truncate"> By <a href="/poet/beta">Poet Beta</a></span>
-            </p>
-          </footer>
-        </div>
-      </div>
-    </div>
-    """
-
-    items = GenericTaskHandler._parse_items(definition, html, "https://example.com")
-
-    assert len(items) == 2
-    assert items[0] == {
-        "link": "https://example.com/poems/view/111",
-        "title": "First Poem",
-        "poet": "Poet Alpha",
-        "category": "Category One",
-    }
-    assert items[1] == {
-        "link": "https://example.com/poems/view/222",
-        "title": "Second Poem",
-        "poet": "Poet Beta",
-    }
-
-
-def test_parse_items_json():
-    definition = TaskDefinition(
-        id=6,
-        name="json",
-        priority=0,
-        match_url=["https://example.com/*"],
-        created_at=datetime.now(),
-        updated_at=datetime.now(),
-        definition=Definition(
-            parse=Parse.model_validate(
-                {
-                    "items": {
-                        "type": "jsonpath",
-                        "selector": "entries",
-                        "fields": {
-                            "link": {"type": "jsonpath", "expression": "url"},
-                            "title": {"type": "jsonpath", "expression": "title"},
-                            "id": {"type": "jsonpath", "expression": "id"},
-                        },
-                    }
-                }
-            ),
-            engine=EngineConfig(),
-            request=RequestConfig(),
-            response=ResponseConfig(type="json"),
-        ),
-    )
-
-    payload = {
-        "entries": [
-            {"url": "/video/1", "title": "First", "id": 1},
-            {"url": "https://example.com/video/2", "title": "Second", "id": 2},
-            {"title": "Missing Link", "id": 3},
-        ]
-    }
-
-    items = GenericTaskHandler._parse_items(
-        definition=definition,
-        html="",
-        base_url="https://example.com",
-        json_data=payload,
-    )
-
-    assert items == [
-        {"link": "https://example.com/video/1", "title": "First", "id": "1"},
-        {"link": "https://example.com/video/2", "title": "Second", "id": "2"},
-    ]
-
-
-@pytest.mark.asyncio
-async def test_generic_task_handler_inspect(monkeypatch):
-    definition = TaskDefinition(
-        id=7,
-        name="json-inspect",
-        priority=0,
-        match_url=["https://example.com/*"],
-        created_at=datetime.now(),
-        updated_at=datetime.now(),
-        definition=Definition(
-            parse=Parse.model_validate(
-                {
-                    "items": {
-                        "type": "jsonpath",
-                        "selector": "items",
-                        "fields": {
-                            "link": {"type": "jsonpath", "expression": "url"},
-                            "title": {"type": "jsonpath", "expression": "title"},
-                        },
-                    }
-                }
-            ),
-            engine=EngineConfig(),
-            request=RequestConfig(),
-            response=ResponseConfig(type="json"),
-        ),
-    )
-
-    async def fake_find_definition(cls, url):  # noqa: ARG001
-        return definition
-
-    monkeypatch.setattr(
-        GenericTaskHandler,
-        "_find_definition",
-        classmethod(fake_find_definition),
-    )
-
-    async def fake_fetch_content(url, definition, ytdlp_opts):  # noqa: ARG001
-        return "", {"items": [{"url": "/video/1", "title": "First"}]}
-
-    monkeypatch.setattr(GenericTaskHandler, "_fetch_content", staticmethod(fake_fetch_content))
-
-    # Mock fetch_info to return valid info with required fields for archive ID generation
-    async def fake_fetch_info(config, url, **kwargs):  # noqa: ARG001
-        return ({"id": "test_video_1", "extractor_key": "Example"}, [])
-
-    with patch("app.features.tasks.definitions.handlers.generic.fetch_info", side_effect=fake_fetch_info):
-        task = HandleTask(id=1, name="Inspect", url="https://example.com/api")
-        result: TaskResult | TaskFailure = await GenericTaskHandler.extract(task)
-
-        assert isinstance(result, TaskResult)
-        assert len(result.items) == 1
-        item = result.items[0]
-        assert item.url == "https://example.com/video/1"
-        assert item.title == "First"
-
-
-def test_parse_items_json_list():
-    definition = TaskDefinition(
-        id=8,
-        name="json-list",
-        priority=0,
-        match_url=["https://example.com/*"],
-        created_at=datetime.now(),
-        updated_at=datetime.now(),
-        definition=Definition(
-            parse=Parse.model_validate(
-                {
-                    "items": {
-                        "type": "jsonpath",
-                        "selector": "[]",
-                        "fields": {
-                            "link": {"type": "jsonpath", "expression": "url"},
-                            "title": {"type": "jsonpath", "expression": "title"},
-                        },
-                    }
-                }
-            ),
-            engine=EngineConfig(),
-            request=RequestConfig(),
-            response=ResponseConfig(type="json"),
-        ),
-    )
-
-    payload = [
-        {"url": "/video/1", "title": "First"},
-        {"url": "/video/2", "title": "Second"},
-    ]
-
-    items = GenericTaskHandler._parse_items(
-        definition=definition,
-        html="",
-        base_url="https://example.com",
-        json_data=payload,
-    )
-
-    assert items == [
-        {"link": "https://example.com/video/1", "title": "First"},
-        {"link": "https://example.com/video/2", "title": "Second"},
-    ]

app/features/tasks/definitions/tests/test_task_definitions.py

@@ -1,226 +0,0 @@
-from __future__ import annotations
-
-import json
-from collections.abc import AsyncGenerator
-from unittest.mock import AsyncMock, MagicMock
-
-import pytest
-import pytest_asyncio
-from aiohttp import web
-from aiohttp.web import Request
-
-from app.features.tasks.definitions.repository import TaskDefinitionsRepository
-from app.features.tasks.definitions.router import (
-    task_definitions_create,
-    task_definitions_delete,
-    task_definitions_get,
-    task_definitions_list,
-    task_definitions_patch,
-    task_definitions_update,
-)
-from app.library.encoder import Encoder
-from app.library.sqlite_store import SqliteStore
-from app.main import EventBus
-from app.tests.helpers import make_in_memory_db_path
-
-
-def _sample_definition(name: str = "example", *, priority: int = 0) -> dict:
-    """Returns a properly structured task definition payload for the repository."""
-    return {
-        "name": name,
-        "match_url": ["https://example.com/*"],
-        "priority": priority,
-        "definition": {
-            "parse": {
-                "link": {
-                    "type": "css",
-                    "expression": "a",
-                    "attribute": "href",
-                }
-            },
-            "engine": {"type": "httpx"},
-            "request": {},
-            "response": {"type": "html"},
-        },
-    }
-
-
-@pytest_asyncio.fixture
-async def repo() -> AsyncGenerator[TaskDefinitionsRepository, None]:
-    TaskDefinitionsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-    store = SqliteStore(db_path=make_in_memory_db_path("task-definitions-repository"))
-    await store.get_connection()
-
-    repository = TaskDefinitionsRepository.get_instance()
-
-    yield repository
-
-    await store.close()
-
-    TaskDefinitionsRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-
-class TestTaskDefinitionsRepository:
-    @pytest.mark.asyncio
-    async def test_create_and_list(self, repo: TaskDefinitionsRepository) -> None:
-        await repo.create(_sample_definition("Alpha", priority=2))
-        await repo.create(_sample_definition("Beta", priority=1))
-
-        items = await repo.all()
-        assert len(items) == 2, "Should return two task definitions"
-        assert [item.name for item in items] == ["Beta", "Alpha"], "Should sort by priority then name"
-
-    @pytest.mark.asyncio
-    async def test_create_duplicate_name_raises(self, repo: TaskDefinitionsRepository) -> None:
-        payload = _sample_definition("Dup")
-        await repo.create(payload)
-
-        with pytest.raises(ValueError, match="already exists"):
-            await repo.create(payload)
-
-        with pytest.raises(ValueError, match="already exists"):
-            await repo.create(payload)
-
-    @pytest.mark.asyncio
-    async def test_update_missing_raises(self, repo: TaskDefinitionsRepository) -> None:
-        with pytest.raises(KeyError, match="not found"):
-            await repo.update(999, {"name": "Missing"})
-
-    @pytest.mark.asyncio
-    async def test_list_paginated(self, repo: TaskDefinitionsRepository) -> None:
-        for idx in range(5):
-            await repo.create(_sample_definition(f"Item {idx}", priority=idx))
-
-        items, total, page, total_pages = await repo.list_paginated(page=1, per_page=2)
-        assert len(items) == 2, "Should return two items per page"
-        assert total == 5, "Should report total count of 5"
-        assert page == 1, "Should return requested page"
-        assert total_pages == 3, "Should compute total pages"
-
-
-@pytest.mark.asyncio
-class TestTaskDefinitionRoutes:
-    async def test_list_definitions(self, repo: TaskDefinitionsRepository) -> None:
-        await repo.create(_sample_definition("Sample"))
-        request = MagicMock(spec=Request)
-        request.query = {}
-
-        response = await task_definitions_list(request, Encoder(), repo)
-        payload = json.loads(response.text)
-
-        assert response.status == web.HTTPOk.status_code, "Should return 200 for list"
-        assert payload["items"][0]["name"] == "Sample", "Should include created definition"
-
-    async def test_get_definition_not_found(self, repo: TaskDefinitionsRepository) -> None:
-        request = MagicMock(spec=Request)
-        request.match_info = {"id": "999"}
-
-        response = await task_definitions_get(request, Encoder(), repo)
-        payload = json.loads(response.text)
-
-        assert response.status == web.HTTPNotFound.status_code, "Should return 404 for missing definition"
-        assert "error" in payload, "Should include error payload"
-
-    async def test_create_definition_success(self, repo: TaskDefinitionsRepository) -> None:
-        request = MagicMock(spec=Request)
-        request.json = AsyncMock(return_value=_sample_definition("New", priority=3))
-
-        response = await task_definitions_create(request, Encoder(), MagicMock(spec=EventBus), repo)
-        body = json.loads(response.text)
-
-        assert response.status == web.HTTPCreated.status_code, "Should create task definition"
-        assert body["name"] == "New", "Should return created name"
-        assert body["priority"] == 3, "Should return created priority"
-
-    async def test_update_definition_success(self, repo: TaskDefinitionsRepository) -> None:
-        created = await repo.create(_sample_definition("Original", priority=0))
-
-        request = MagicMock(spec=Request)
-        request.match_info = {"id": str(created.id)}
-        request.json = AsyncMock(return_value=_sample_definition("Updated", priority=4))
-
-        response = await task_definitions_update(request, Encoder(), MagicMock(spec=EventBus), repo)
-        body = json.loads(response.text)
-
-        assert response.status == web.HTTPOk.status_code, "Should update task definition"
-        assert body["name"] == "Updated", "Should return updated name"
-        assert body["priority"] == 4, "Should return updated priority"
-
-    async def test_delete_definition_success(self, repo: TaskDefinitionsRepository) -> None:
-        created = await repo.create(_sample_definition("Delete"))
-
-        request = MagicMock(spec=Request)
-        request.match_info = {"id": str(created.id)}
-
-        response = await task_definitions_delete(request, Encoder(), MagicMock(spec=EventBus), repo)
-        assert response.status == web.HTTPOk.status_code, "Should delete task definition"
-
-    async def test_patch_definition_enabled(self, repo: TaskDefinitionsRepository) -> None:
-        created = await repo.create(_sample_definition("PatchTest", priority=5))
-        assert created.enabled is True, "Should be enabled by default"
-
-        request = MagicMock(spec=Request)
-        request.match_info = {"id": str(created.id)}
-        request.json = AsyncMock(return_value={"enabled": False})
-
-        response = await task_definitions_patch(request, Encoder(), MagicMock(spec=EventBus), repo)
-        body = json.loads(response.text)
-
-        assert response.status == web.HTTPOk.status_code, "Should patch task definition"
-        assert body["name"] == "PatchTest", "Should keep original name"
-        assert body["priority"] == 5, "Should keep original priority"
-        assert body["enabled"] is False, "Should update enabled status"
-
-    async def test_patch_definition_priority(self, repo: TaskDefinitionsRepository) -> None:
-        created = await repo.create(_sample_definition("PatchPriority", priority=1))
-
-        request = MagicMock(spec=Request)
-        request.match_info = {"id": str(created.id)}
-        request.json = AsyncMock(return_value={"priority": 10})
-
-        response = await task_definitions_patch(request, Encoder(), MagicMock(spec=EventBus), repo)
-        body = json.loads(response.text)
-
-        assert response.status == web.HTTPOk.status_code, "Should patch task definition"
-        assert body["priority"] == 10, "Should update priority"
-        assert body["enabled"] is True, "Should keep original enabled status"
-
-    async def test_patch_definition_not_found(self, repo: TaskDefinitionsRepository) -> None:
-        request = MagicMock(spec=Request)
-        request.match_info = {"id": "999"}
-        request.json = AsyncMock(return_value={"enabled": False})
-
-        response = await task_definitions_patch(request, Encoder(), MagicMock(spec=EventBus), repo)
-        payload = json.loads(response.text)
-
-        assert response.status == web.HTTPNotFound.status_code, "Should return 404 for missing definition"
-        assert "error" in payload, "Should include error payload"
-
-    async def test_create_with_regex_pattern(self, repo: TaskDefinitionsRepository) -> None:
-        payload = _sample_definition("RegexTest", priority=0)
-        payload["match_url"] = ["/https://example\\.com/post/[0-9]+/"]
-
-        request = MagicMock(spec=Request)
-        request.json = AsyncMock(return_value=payload)
-
-        response = await task_definitions_create(request, Encoder(), MagicMock(spec=EventBus), repo)
-        body = json.loads(response.text)
-
-        assert response.status == web.HTTPCreated.status_code, "Should create task definition with regex pattern"
-        assert body["match_url"][0] == "/https://example\\.com/post/[0-9]+/", "Should preserve regex pattern format"
-
-    async def test_create_with_invalid_regex_pattern(self, repo: TaskDefinitionsRepository) -> None:
-        payload = _sample_definition("BadRegex", priority=0)
-        payload["match_url"] = ["/[invalid(/"]
-
-        request = MagicMock(spec=Request)
-        request.json = AsyncMock(return_value=payload)
-
-        response = await task_definitions_create(request, Encoder(), MagicMock(spec=EventBus), repo)
-        payload_response = json.loads(response.text)
-
-        assert response.status == web.HTTPBadRequest.status_code, "Should reject invalid regex pattern"
-        assert "error" in payload_response, "Should include error payload"

app/features/tasks/definitions/utils.py

@@ -1,77 +0,0 @@
-from typing import Any, Literal, overload
-
-from app.features.tasks.definitions.models import TaskDefinitionModel
-from app.features.tasks.definitions.schemas import Definition, TaskDefinition, TaskDefinitionSummary
-
-
-@overload
-def model_to_schema(model: TaskDefinitionModel, summary: Literal[False] = False) -> TaskDefinition: ...
-
-
-@overload
-def model_to_schema(model: TaskDefinitionModel, summary: Literal[True]) -> TaskDefinitionSummary: ...
-
-
-def model_to_schema(model: TaskDefinitionModel, summary: bool = False) -> TaskDefinition | TaskDefinitionSummary:
-    """
-    Convert a TaskDefinitionModel to a TaskDefinition or TaskDefinitionSummary schema.
-
-    Args:
-        model (TaskDefinitionModel): The model instance to convert.
-        summary (bool): Whether to return a summary schema.
-
-    Returns:
-        TaskDefinition | TaskDefinitionSummary: The corresponding schema instance.
-
-    """
-    dct = {
-        "id": model.id,
-        "name": model.name,
-        "priority": model.priority,
-        "match_url": model.match_url,
-        "enabled": model.enabled,
-        "created_at": model.created_at,
-        "updated_at": model.updated_at,
-    }
-    return TaskDefinitionSummary(**dct) if summary else TaskDefinition(**dct, definition=Definition(**model.definition))
-
-
-def schema_to_payload(item: TaskDefinition) -> dict[str, Any]:
-    """
-    Convert a TaskDefinition schema to a dictionary payload for database operations.
-
-    Args:
-        item (TaskDefinition): The schema instance to convert.
-
-    Returns:
-        dict[str, Any]: The corresponding dictionary payload.
-
-    """
-    return {
-        "name": item.name,
-        "priority": item.priority,
-        "match_url": item.match_url,
-        "enabled": item.enabled,
-        "definition": item.definition.model_dump(exclude_unset=True, exclude_none=True),
-    }
-
-
-def split_inspect_metadata(metadata: dict[str, Any] | None) -> tuple[dict[str, Any], dict[str, Any]]:
-    """
-    Split commonly consumed metadata keys from the rest.
-
-    Args:
-        metadata (dict[str, Any]|None): The metadata to split.
-
-    Returns:
-        tuple[dict[str, Any], dict[str, Any]]: The primary and extra metadata.
-
-    """
-    metadata = dict(metadata or {})
-    primary: dict[str, Any] = {}
-
-    for key in ("matched", "handler", "supported"):
-        if key in metadata:
-            primary[key] = metadata.pop(key)
-
-    return primary, metadata

app/features/tasks/deps.py

@@ -1,14 +0,0 @@
-from __future__ import annotations
-
-from app.features.tasks.repository import TasksRepository
-from app.features.tasks.service import Tasks
-
-
-def get_tasks_repo() -> TasksRepository:
-    """Get tasks repository instance."""
-    return TasksRepository.get_instance()
-
-
-def get_tasks_service() -> Tasks:
-    """Get tasks service instance."""
-    return Tasks.get_instance()

app/features/tasks/migration.py

@@ -1,124 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-from app.features.core.migration import Migration as FeatureMigration
-from app.features.tasks.schemas import Task
-from app.library.config import Config
-from app.library.log import get_logger
-
-if TYPE_CHECKING:
-    from app.features.tasks.repository import TasksRepository
-
-LOG = get_logger()
-
-
-class Migration(FeatureMigration):
-    name: str = "tasks"
-
-    def __init__(self, repo: TasksRepository, config: Config | None = None):
-        self._config: Config = config or Config.get_instance()
-        super().__init__(config=self._config)
-        self._repo: TasksRepository = repo
-        self._source_file: Path = Path(self._config.config_path) / "tasks.json"
-
-    async def should_run(self) -> bool:
-        return self._source_file.exists()
-
-    async def migrate(self) -> None:
-        if await self._repo.count() > 0:
-            LOG.warning("Tasks already exist in the database; skipping migration.")
-            await self._move_file(self._source_file)
-            return
-
-        try:
-            items: list[dict[str, Any]] | None = json.loads(self._source_file.read_text())
-        except Exception as exc:
-            LOG.exception(
-                "Failed to read tasks migration file '%s'. Ignoring.",
-                self._source_file,
-                extra={"file_path": str(self._source_file), "exception_type": type(exc).__name__},
-            )
-            await self._move_file(self._source_file)
-            return
-
-        if items is None:
-            LOG.warning("No tasks found in %s; skipping migration.", self._source_file)
-            await self._move_file(self._source_file)
-            return
-
-        inserted = 0
-        seen_names: dict[str, int] = {}
-        for index, item in enumerate(items):
-            if not (normalized := self._normalize(item, index, seen_names)):
-                continue
-            try:
-                await self._repo.create(normalized)
-                inserted += 1
-            except Exception as exc:
-                LOG.exception(
-                    "Failed to insert task '%s'.",
-                    normalized["name"],
-                    extra={"task_name": normalized["name"], "exception_type": type(exc).__name__},
-                )
-
-        LOG.info("Migrated %s task(s) from %s.", inserted, self._source_file)
-        await self._move_file(self._source_file)
-
-    def _normalize(self, item: Any, index: int, seen_names: dict[str, int]) -> dict[str, Any] | None:
-        if not isinstance(item, dict):
-            LOG.warning("Skipping task at index %s due to invalid type.", index)
-            return None
-
-        assert isinstance(item, dict)
-
-        name: str | None = item.get("name")
-        if not name or not isinstance(name, str):
-            LOG.warning("Skipping task at index %s due to missing name.", index)
-            return None
-
-        normalized_name = name.strip()
-        if not normalized_name:
-            LOG.warning("Skipping task at index %s due to empty name.", index)
-            return None
-
-        name = self._unique_name(normalized_name, seen_names)
-
-        url: str | None = item.get("url")
-        if not url or not isinstance(url, str):
-            LOG.warning("Skipping task '%s' at index %s due to missing URL.", name, index)
-            return None
-
-        url = url.strip()
-        if not url:
-            LOG.warning("Skipping task '%s' at index %s due to empty URL.", name, index)
-            return None
-
-        folder: str = item.get("folder") if isinstance(item.get("folder"), str) else ""
-        preset: str = item.get("preset") if isinstance(item.get("preset"), str) else ""
-        timer: str = item.get("timer") if isinstance(item.get("timer"), str) else ""
-        template: str = item.get("template") if isinstance(item.get("template"), str) else ""
-        cli: str = item.get("cli") if isinstance(item.get("cli"), str) else ""
-        auto_start: bool = item.get("auto_start") if isinstance(item.get("auto_start"), bool) else True
-        handler_enabled: bool = item.get("handler_enabled") if isinstance(item.get("handler_enabled"), bool) else True
-        enabled: bool = item.get("enabled") if isinstance(item.get("enabled"), bool) else True
-
-        try:
-            validated = Task(
-                name=name,
-                url=url,
-                folder=folder,
-                preset=preset,
-                timer=timer,
-                template=template,
-                cli=cli,
-                auto_start=auto_start,
-                handler_enabled=handler_enabled,
-                enabled=enabled,
-            )
-            return validated.model_dump()
-        except Exception as e:
-            LOG.warning("Skipping task '%s' at index %s due to validation error: %s", name, index, e)
-            return None

app/features/tasks/models.py

@@ -1,31 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime  # noqa: TC003
-
-from sqlalchemy import Boolean, Index, Integer, String, Text
-from sqlalchemy.orm import Mapped, mapped_column
-
-from app.features.core.models import Base, UTCDateTime, utcnow
-
-
-class TaskModel(Base):
-    __tablename__: str = "tasks"
-    __table_args__: tuple[Index, ...] = (
-        Index("ix_tasks_name", "name"),
-        Index("ix_tasks_enabled", "enabled"),
-        Index("ix_tasks_timer", "timer"),
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    name: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    url: Mapped[str] = mapped_column(String(2048), nullable=False)
-    folder: Mapped[str] = mapped_column(String(512), nullable=False, default="")
-    preset: Mapped[str] = mapped_column(String(255), nullable=False, default="")
-    timer: Mapped[str] = mapped_column(String(255), nullable=False, default="")
-    template: Mapped[str] = mapped_column(String(1024), nullable=False, default="")
-    cli: Mapped[str] = mapped_column(Text, nullable=False, default="")
-    auto_start: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
-    handler_enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
-    enabled: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
-    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, nullable=False)
-    updated_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow, onupdate=utcnow, nullable=False)

app/features/tasks/repository.py

@@ -1,188 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-from sqlalchemy import func, or_, select
-
-from app.features.core.deps import get_session
-from app.features.tasks.models import TaskModel
-from app.library.log import get_logger
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-    from contextlib import AbstractAsyncContextManager
-
-    from sqlalchemy.engine.result import Result
-    from sqlalchemy.ext.asyncio import AsyncSession
-    from sqlalchemy.sql.elements import ColumnElement
-    from sqlalchemy.sql.selectable import Select
-
-    SessionFactory = Callable[[], AbstractAsyncContextManager[AsyncSession]]
-
-LOG = get_logger()
-
-
-def _model_from_payload(payload: dict[str, Any]) -> TaskModel:
-    model = TaskModel()
-    for key, value in payload.items():
-        if not hasattr(model, key):
-            msg = f"'{key}' is an invalid keyword argument for TaskModel"
-            raise TypeError(msg)
-        setattr(model, key, value)
-    return model
-
-
-def _coerce_model(payload: TaskModel | dict[str, Any]) -> TaskModel:
-    if isinstance(payload, TaskModel):
-        return payload
-    return _model_from_payload(payload)
-
-
-class TasksRepository(metaclass=Singleton):
-    def __init__(self, session: SessionFactory | None = None) -> None:
-        self._migrated = False
-        self.session: SessionFactory = session or get_session
-
-    async def run_migrations(self) -> None:
-        if self._migrated:
-            return
-
-        self._migrated = True
-        from app.features.tasks.migration import Migration
-
-        await Migration(repo=self).run()
-
-    @staticmethod
-    def get_instance() -> TasksRepository:
-        return TasksRepository()
-
-    async def all(self) -> list[TaskModel]:
-        async with self.session() as session:
-            result: Result[tuple[TaskModel]] = await session.execute(select(TaskModel).order_by(TaskModel.name.asc()))
-            return list(result.scalars().all())
-
-    async def list_paginated(self, page: int, per_page: int) -> tuple[list[TaskModel], int, int, int]:
-        async with self.session() as session:
-            total: int = await self.count()
-            total_pages: int = (total + per_page - 1) // per_page if total > 0 else 1
-
-            if page > total_pages and total > 0:
-                page = total_pages
-
-            query: Select[tuple[TaskModel]] = (
-                select(TaskModel).order_by(TaskModel.name.asc()).limit(per_page).offset((page - 1) * per_page)
-            )
-            result: Result[tuple[TaskModel]] = await session.execute(query)
-            return list(result.scalars().all()), total, page, total_pages
-
-    async def count(self) -> int:
-        async with self.session() as session:
-            result: Result[tuple[int]] = await session.execute(select(func.count()).select_from(TaskModel))
-            return int(result.scalar_one())
-
-    async def get(self, identifier: int | str) -> TaskModel | None:
-        async with self.session() as session:
-            if not identifier:
-                return None
-
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = TaskModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(TaskModel.id == int(identifier), TaskModel.name == identifier)
-            else:
-                clause = TaskModel.name == identifier
-
-            result: Result[tuple[TaskModel]] = await session.execute(select(TaskModel).where(clause).limit(1))
-            return result.scalar_one_or_none()
-
-    async def get_by_name(self, name: str, exclude_id: int | None = None) -> TaskModel | None:
-        async with self.session() as session:
-            query: Select[tuple[TaskModel]] = select(TaskModel).where(TaskModel.name == name)
-            if exclude_id is not None:
-                query = query.where(TaskModel.id != exclude_id)
-
-            result: Result[tuple[TaskModel]] = await session.execute(query.limit(1))
-            return result.scalar_one_or_none()
-
-    async def get_all_enabled(self) -> list[TaskModel]:
-        """Get all enabled tasks."""
-        async with self.session() as session:
-            result: Result[tuple[TaskModel]] = await session.execute(
-                select(TaskModel).where(TaskModel.enabled).order_by(TaskModel.name.asc())
-            )
-            return list(result.scalars().all())
-
-    async def get_all_with_timer(self) -> list[TaskModel]:
-        """Get all tasks that have a timer configured."""
-        async with self.session() as session:
-            result: Result[tuple[TaskModel]] = await session.execute(
-                select(TaskModel).where(TaskModel.timer != "").order_by(TaskModel.name.asc())
-            )
-            return list(result.scalars().all())
-
-    async def create(self, payload: TaskModel | dict[str, Any]) -> TaskModel:
-        async with self.session() as session:
-            model = _coerce_model(payload)
-            if model.id is not None:
-                model.id = None  # ty: ignore
-
-            if await self.get_by_name(name=model.name) is not None:
-                msg: str = f"Task with name '{model.name}' already exists."
-                raise ValueError(msg)
-
-            session.add(model)
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def update(self, identifier: int | str, payload: dict[str, Any]) -> TaskModel:
-        """Update an existing task."""
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = TaskModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(TaskModel.id == int(identifier), TaskModel.name == identifier)
-            else:
-                clause = TaskModel.name == identifier
-
-            result: Result[tuple[TaskModel]] = await session.execute(select(TaskModel).where(clause).limit(1))
-            model: TaskModel | None = result.scalar_one_or_none()
-
-            if model is None:
-                msg: str = f"Task '{identifier}' not found."
-                raise KeyError(msg)
-
-            if "name" in payload:
-                existing: TaskModel | None = await self.get_by_name(name=payload["name"], exclude_id=model.id)
-                if existing is not None:
-                    msg = f"Task with name '{payload['name']}' already exists."
-                    raise ValueError(msg)
-
-            for key, value in payload.items():
-                if hasattr(model, key):
-                    setattr(model, key, value)
-
-            await session.commit()
-            await session.refresh(model)
-            return model
-
-    async def delete(self, identifier: int | str) -> TaskModel:
-        async with self.session() as session:
-            if isinstance(identifier, int):
-                clause: ColumnElement[bool] = TaskModel.id == identifier
-            elif isinstance(identifier, str) and identifier.isdigit():
-                clause = or_(TaskModel.id == int(identifier), TaskModel.name == identifier)
-            else:
-                clause = TaskModel.name == identifier
-
-            result: Result[tuple[TaskModel]] = await session.execute(select(TaskModel).where(clause).limit(1))
-            model: TaskModel | None = result.scalar_one_or_none()
-
-            if model is None:
-                msg: str = f"Task '{identifier}' not found."
-                raise KeyError(msg)
-
-            await session.delete(model)
-            await session.commit()
-            return model

app/features/tasks/router.py

@@ -1,798 +0,0 @@
-import asyncio
-from typing import TYPE_CHECKING, Any
-
-from aiohttp import web
-from aiohttp.web import Request, Response
-from pydantic import ValidationError
-
-from app.features.core.schemas import CEAction, CEFeature, ConfigEvent, Pagination
-from app.features.core.utils import build_pagination, format_validation_errors, normalize_pagination
-from app.features.tasks.definitions.results import HandleTask as ExtendedTask
-from app.features.tasks.definitions.results import TaskFailure, TaskResult
-from app.features.tasks.definitions.service import TaskHandle
-from app.features.tasks.repository import TasksRepository
-from app.features.tasks.schemas import Task, TaskList, TaskPatch
-from app.features.ytdlp.utils import parse_outtmpl
-from app.library.ag_utils import ag
-from app.library.config import Config
-from app.library.encoder import Encoder
-from app.library.Events import EventBus, Events
-from app.library.log import get_logger
-from app.library.router import route
-from app.library.Utils import get_channel_images, get_file, validate_url
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-
-LOG = get_logger()
-
-TIMER_SLOTS_PER_HOUR: int = 12
-
-
-def _offset_timer(timer: str, index: int) -> str:
-    """
-    Add deterministic offset to CRON timer based on index.
-
-    Uses 5-minute increments with 12 slots per hour (0-55 minutes).
-    After 12 items, expands to hours.
-
-    Formula:
-        hours_offset = index // 12
-        minutes_offset = (index % 12) * 5
-
-    Examples:
-        index 0: +0min, index 5: +25min, index 11: +55min
-        index 12: +1hr 0min, index 24: +2hr 0min
-
-    Args:
-        timer: CRON expression string (5 fields)
-        index: Task index for offset calculation
-
-    Returns:
-        Modified CRON expression with offset applied, or original on error
-
-    """
-    if not timer or index <= 0:
-        return timer
-
-    try:
-        parts = timer.strip().split()
-        if len(parts) != 5:
-            return timer
-
-        minute, hour, dom, month, dow = parts
-
-        hours_offset = index // TIMER_SLOTS_PER_HOUR
-        minutes_offset = (index % TIMER_SLOTS_PER_HOUR) * 5
-
-        original_minute = int(minute) if minute.isdigit() else 0
-
-        if minute.isdigit():
-            new_minute = (original_minute + minutes_offset) % 60
-            minute = str(new_minute)
-        elif "/" in minute:
-            base, step = minute.split("/", 1)
-            if base.isdigit():
-                new_base = (int(base) + minutes_offset) % 60
-                minute = f"{new_base}/{step}"
-        elif minute == "*":
-            minute = str(minutes_offset)
-
-        carry_hour = (original_minute + minutes_offset) // 60
-
-        if hour.isdigit():
-            new_hour = (int(hour) + hours_offset + carry_hour) % 24
-            hour = str(new_hour)
-        elif "/" in hour:
-            base, step = hour.split("/", 1)
-            if base.isdigit():
-                new_base = (int(base) + hours_offset + carry_hour) % 24
-                hour = f"{new_base}/{step}"
-        elif hour == "*" and (hours_offset > 0 or carry_hour > 0):
-            hour = str((hours_offset + carry_hour) % 24)
-
-        return f"{minute} {hour} {dom} {month} {dow}"
-    except Exception as e:
-        LOG.warning(
-            "Failed to offset task timer.",
-            extra={"timer": timer, "index": index, "error": str(e), "exception_type": type(e).__name__},
-            exc_info=True,
-        )
-        return timer
-
-
-async def _get_info(url: str, preset: str) -> tuple[str | None, str | None]:
-    """
-    Fetch metadata from URL and extract title for task name.
-
-    Also converts YouTube @handle URLs to channel IDs when possible.
-
-    Args:
-        url: URL to fetch metadata from
-        preset: Preset name to use for extraction options
-
-    Returns:
-        Tuple of (title or None, converted_url or None)
-
-    """
-    try:
-        from app.features.ytdlp.extractor import fetch_info
-        from app.features.ytdlp.ytdlp_opts import YTDLPOpts
-
-        params = YTDLPOpts.get_instance().add_cli("-I0", from_user=False)
-        if preset:
-            params.preset(name=preset)
-
-        (metadata, _) = await fetch_info(config=params.get_all(), url=url)
-
-        if not metadata or not isinstance(metadata, dict):
-            return (None, None)
-
-        title = ag(metadata, ["title", "fulltitle"])
-        name = str(title)[:255] if title else None
-
-        converted_url: str | None = None
-        channel_id = metadata.get("channel_id")
-        if channel_id and "/@" in url:
-            import re
-
-            converted_url = re.sub(r"/@[^/]+", f"/channel/{channel_id}", url)
-
-        return (name, converted_url)
-    except TimeoutError:
-        LOG.debug("Timeout while inferring name from '%s'.", url, extra={"url": url, "preset": preset})
-        return (None, None)
-    except Exception as e:
-        LOG.debug(
-            "Failed to infer a task name from '%s' because %s.",
-            url,
-            e,
-            extra={"url": url, "preset": preset, "error": str(e)},
-        )
-        return (None, None)
-
-
-def _model(model: Any) -> Task:
-    return Task.model_validate(model)
-
-
-def _serialize(model: Any) -> dict:
-    return _model(model).model_dump()
-
-
-async def _require_timer_or_handler(task: Task, handler: TaskHandle) -> None:
-    if task.timer:
-        return
-
-    if task.handler_enabled is False:
-        msg = "Task requires a timer when the handler is disabled."
-        raise ValueError(msg)
-
-    result = await handler.inspect(url=task.url, preset=task.preset, static_only=True)
-    if isinstance(result, TaskResult) and result.metadata.get("matched") is True:
-        return
-
-    msg = "Task requires a timer when no supported handler matches the URL."
-    raise ValueError(msg)
-
-
-@route("GET", "api/tasks/", "tasks_list")
-async def tasks_list(request: Request, repo: TasksRepository, encoder: Encoder) -> Response:
-    page, per_page = normalize_pagination(request)
-    items, total, current_page, total_pages = await repo.list_paginated(page, per_page)
-    return web.json_response(
-        data=TaskList(
-            items=[_model(model) for model in items],
-            pagination=Pagination.model_validate(build_pagination(total, current_page, per_page, total_pages)),
-        ),
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("POST", "api/tasks/", "tasks_add")
-async def tasks_add(
-    request: Request,
-    repo: TasksRepository,
-    encoder: Encoder,
-    notify: EventBus,
-    handler: TaskHandle,
-) -> Response:
-    data = await request.json()
-
-    if isinstance(data, dict):
-        data = [data]
-
-    if not isinstance(data, list) or len(data) == 0:
-        return web.json_response(
-            {"error": "Invalid request body. Expecting dict or list of dicts."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    first_item = data[0]
-    if not isinstance(first_item, dict) or not first_item.get("url"):
-        return web.json_response(
-            {"error": "First item requires 'url' field."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if not first_item.get("name"):
-        return web.json_response(
-            {"error": "First item requires 'name' field."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        first_task: Task = Task.model_validate(first_item)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate first task.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if await repo.get_by_name(first_task.name):
-        return web.json_response(
-            data={"error": f"Task with name '{first_task.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    pending_tasks: list[dict[str, Any]] = []
-    created_tasks: list[dict[str, Any]] = []
-    base_settings = first_task.model_dump(exclude={"id", "name", "url", "created_at", "updated_at"})
-
-    for idx, item in enumerate(data):
-        if not isinstance(item, dict):
-            LOG.warning("Skipping item %s: not a dict.", idx, extra={"index": idx})
-            continue
-
-        url = str(item.get("url", "")).strip()
-        if not url:
-            LOG.debug("Skipping item %s: empty URL.", idx, extra={"index": idx})
-            continue
-
-        inferred_name, converted_url = await _get_info(url, item.get("preset", first_task.preset))
-        name = item.get("name", first_task.name if 0 == idx else (inferred_name or f"task-{idx}"))
-
-        final_name = str(name)
-        counter = 1
-        while await repo.get_by_name(final_name):
-            final_name = f"{name}-{counter}"
-            counter += 1
-
-        item_settings = base_settings.copy()
-        for key in ["timer", "preset", "folder", "template", "cli", "auto_start", "handler_enabled", "enabled"]:
-            if key in item and item[key] is not None:
-                item_settings[key] = item[key]
-
-        task_dict: dict[str, Any] = {
-            "name": final_name,
-            "url": converted_url or url,
-            **item_settings,
-        }
-
-        if not task_dict.get("timer") and first_task.timer and idx > 0:
-            task_dict["timer"] = _offset_timer(first_task.timer, idx)
-
-        try:
-            validated = Task.model_validate(task_dict)
-        except ValidationError as exc:
-            return web.json_response(
-                data={"error": "Failed to validate task.", "detail": format_validation_errors(exc)},
-                status=web.HTTPBadRequest.status_code,
-            )
-
-        try:
-            await _require_timer_or_handler(validated, handler)
-        except ValueError as exc:
-            return web.json_response(
-                data={"error": str(exc)},
-                status=web.HTTPBadRequest.status_code,
-            )
-
-        pending_tasks.append(validated.model_dump())
-
-    for idx, task_data in enumerate(pending_tasks):
-        try:
-            created = await repo.create(task_data)
-            saved = _serialize(created)
-            created_tasks.append(saved)
-            notify.emit(
-                Events.CONFIG_UPDATE,
-                data=ConfigEvent(feature=CEFeature.TASKS, action=CEAction.CREATE, data=saved),
-            )
-        except ValueError as exc:
-            LOG.warning(
-                "Failed to create task from request item %s.",
-                idx,
-                extra={"index": idx, "error": str(exc), "exception_type": type(exc).__name__},
-            )
-            continue
-
-    if len(created_tasks) == 0:
-        return web.json_response(
-            {"error": "Failed to create any tasks."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if len(created_tasks) == 1:
-        return web.json_response(data=created_tasks[0], status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-    return web.json_response(data=created_tasks, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("GET", r"api/tasks/{id:\d+}", "tasks_get")
-async def tasks_get(request: Request, repo: TasksRepository, encoder: Encoder) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    model = await repo.get(identifier)
-    if not model:
-        return web.json_response({"error": "Task not found"}, status=web.HTTPNotFound.status_code)
-
-    return web.json_response(data=_serialize(model), status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("DELETE", r"api/tasks/{id:\d+}", "tasks_delete")
-async def tasks_delete(request: Request, repo: TasksRepository, encoder: Encoder, notify: EventBus) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        deleted = _serialize(await repo.delete(identifier))
-        notify.emit(
-            Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.TASKS, action=CEAction.DELETE, data=deleted)
-        )
-        return web.json_response(
-            data=deleted,
-            status=web.HTTPOk.status_code,
-            dumps=encoder.encode,
-        )
-    except KeyError as exc:
-        return web.json_response({"error": str(exc)}, status=web.HTTPNotFound.status_code)
-
-
-@route("PATCH", r"api/tasks/{id:\d+}", "tasks_patch")
-async def tasks_patch(
-    request: Request,
-    repo: TasksRepository,
-    encoder: Encoder,
-    notify: EventBus,
-    handler: TaskHandle,
-) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    model = await repo.get(identifier)
-    if not model:
-        return web.json_response({"error": "Task not found"}, status=web.HTTPNotFound.status_code)
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        validated = TaskPatch.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate task.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if validated.name and await repo.get_by_name(validated.name, exclude_id=model.id):
-        return web.json_response(
-            data={"error": f"Task with name '{validated.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    merged = _model(model).model_copy(update=validated.model_dump(exclude_unset=True))
-
-    try:
-        await _require_timer_or_handler(merged, handler)
-    except ValueError as exc:
-        return web.json_response(
-            data={"error": str(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    updated = _serialize(await repo.update(model.id, validated.model_dump(exclude_unset=True)))
-    notify.emit(Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.TASKS, action=CEAction.UPDATE, data=updated))
-    return web.json_response(
-        data=updated,
-        status=web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("PUT", r"api/tasks/{id:\d+}", "tasks_update")
-async def tasks_update(
-    request: Request,
-    repo: TasksRepository,
-    encoder: Encoder,
-    notify: EventBus,
-    handler: TaskHandle,
-) -> Response:
-    if not (identifier := request.match_info.get("id")):
-        return web.json_response({"error": "ID required"}, status=web.HTTPBadRequest.status_code)
-
-    model = await repo.get(identifier)
-    if not model:
-        return web.json_response({"error": "Task not found"}, status=web.HTTPNotFound.status_code)
-
-    data = await request.json()
-
-    if not isinstance(data, dict):
-        return web.json_response(
-            {"error": "Invalid request body expecting dict."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        validated = Task.model_validate(data)
-    except ValidationError as exc:
-        return web.json_response(
-            data={"error": "Failed to validate task.", "detail": format_validation_errors(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if validated.name and await repo.get_by_name(validated.name, exclude_id=model.id):
-        return web.json_response(
-            data={"error": f"Task with name '{validated.name}' already exists."},
-            status=web.HTTPConflict.status_code,
-        )
-
-    try:
-        await _require_timer_or_handler(validated, handler)
-    except ValueError as exc:
-        return web.json_response(
-            data={"error": str(exc)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    updated = _serialize(await repo.update(model.id, validated.model_dump(exclude_unset=True)))
-    notify.emit(Events.CONFIG_UPDATE, data=ConfigEvent(feature=CEFeature.TASKS, action=CEAction.UPDATE, data=updated))
-
-    return web.json_response(data=updated, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-
-@route("POST", "api/tasks/inspect", "task_handler_inspect")
-async def task_handler_inspect(request: Request, handler: TaskHandle, encoder: Encoder, config: Config) -> Response:
-    """
-    Check if handler can process the given URL.
-
-    Args:
-        request: The request object.
-        handler: The handler service instance.
-        encoder: The encoder instance.
-        config: The config instance.
-
-    Returns:
-        The response object.
-
-    """
-    data = await request.json()
-
-    url: str | None = data.get("url") if isinstance(data, dict) else None
-    if not url:
-        return web.json_response({"error": "url is required."}, status=web.HTTPBadRequest.status_code)
-
-    static_only: bool = data.get("static_only", False) if isinstance(data, dict) else False
-    if not static_only:
-        try:
-            await asyncio.to_thread(validate_url, url, config.allow_internal_urls)
-        except ValueError as e:
-            return web.json_response({"error": str(e)}, status=web.HTTPBadRequest.status_code)
-
-    preset: str = data.get("preset", "") if isinstance(data, dict) else ""
-    handler_name: str | None = data.get("handler") if isinstance(data, dict) else None
-
-    try:
-        result: TaskResult | TaskFailure = await handler.inspect(
-            url=url, preset=preset, handler_name=handler_name, static_only=static_only
-        )
-    except Exception as e:
-        LOG.exception(
-            "Failed to inspect task handler for '%s'.",
-            url,
-            extra={
-                "handler_name": handler_name,
-                "url": url,
-                "static_only": static_only,
-                "exception_type": type(e).__name__,
-            },
-        )
-        return web.json_response(
-            {"error": "Failed to inspect handler.", "message": str(e)},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-    return web.json_response(
-        data=result,
-        status=web.HTTPBadRequest.status_code if isinstance(result, TaskFailure) else web.HTTPOk.status_code,
-        dumps=encoder.encode,
-    )
-
-
-@route("POST", r"api/tasks/{id:\d+}/mark", "tasks_mark")
-async def task_mark(request: Request, repo: TasksRepository, encoder: Encoder) -> Response:
-    """
-    Mark all items from task as downloaded.
-
-    Args:
-        request: The request object.
-        repo: The tasks repository instance.
-        encoder: The encoder instance.
-
-    Returns:
-        The response object.
-
-    """
-    if not (task_id := request.match_info.get("id")):
-        return web.json_response(data={"error": "No task id."}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        model = await repo.get(int(task_id))
-        if not model:
-            return web.json_response(
-                data={"error": f"Task '{task_id}' does not exist."}, status=web.HTTPNotFound.status_code
-            )
-
-        # Convert to extended Task with handler methods
-        task = ExtendedTask.model_validate(model)
-        _status, _message = await task.mark()
-
-        if not _status:
-            return web.json_response(data={"error": _message}, status=web.HTTPBadRequest.status_code)
-
-        return web.json_response(data={"message": _message}, status=web.HTTPOk.status_code, dumps=encoder.encode)
-    except ValueError as e:
-        return web.json_response(data={"error": str(e)}, status=web.HTTPBadRequest.status_code)
-
-
-@route("DELETE", r"api/tasks/{id:\d+}/mark", "tasks_unmark")
-async def task_unmark(request: Request, repo: TasksRepository, encoder: Encoder) -> Response:
-    """
-    Remove all task items from download archive.
-
-    Args:
-        request: The request object.
-        repo: The tasks repository instance.
-        encoder: The encoder instance.
-
-    Returns:
-        The response object.
-
-    """
-    if not (task_id := request.match_info.get("id")):
-        return web.json_response(data={"error": "No task id."}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        model = await repo.get(int(task_id))
-        if not model:
-            return web.json_response(
-                data={"error": f"Task '{task_id}' does not exist."}, status=web.HTTPNotFound.status_code
-            )
-
-        # Convert to extended Task with handler methods
-        task = ExtendedTask.model_validate(model)
-        _status, _message = await task.unmark()
-
-        if not _status:
-            return web.json_response(data={"error": _message}, status=web.HTTPBadRequest.status_code)
-
-        return web.json_response(data={"message": _message}, status=web.HTTPOk.status_code, dumps=encoder.encode)
-    except ValueError as e:
-        return web.json_response(data={"error": str(e)}, status=web.HTTPBadRequest.status_code)
-
-
-@route("POST", r"api/tasks/{id:\d+}/metadata", "tasks_metadata")
-async def task_metadata(request: Request, repo: TasksRepository, config: Config, encoder: Encoder) -> Response:
-    """
-    Generate metadata for the task.
-
-    Args:
-        request: The request object.
-        repo: The tasks repository instance.
-        config: The config instance.
-        encoder: The encoder instance.
-
-    Returns:
-        The response object.
-
-    """
-    if not (task_id := request.match_info.get("id")):
-        return web.json_response(data={"error": "No task id."}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        if not (model := await repo.get(int(task_id))):
-            return web.json_response(
-                data={"error": f"Task '{task_id}' does not exist."}, status=web.HTTPNotFound.status_code
-            )
-
-        task = ExtendedTask.model_validate(model)
-
-        (save_path, _) = get_file(config.download_path, task.folder)
-        if not str(save_path or "").startswith(str(config.download_path)):
-            return web.json_response(data={"error": "Invalid task folder."}, status=web.HTTPBadRequest.status_code)
-
-        if not save_path.exists():
-            save_path.mkdir(parents=True, exist_ok=True)
-
-        metadata, status, message = await task.fetch_metadata()
-        if not status:
-            return web.json_response(data={"error": message}, status=web.HTTPBadRequest.status_code)
-        if not isinstance(metadata, dict):
-            return web.json_response(
-                data={"error": "Failed to get metadata."},
-                status=web.HTTPBadRequest.status_code,
-            )
-
-        if not task.folder:
-            try:
-                ytdlp_opts: dict = task.get_ytdlp_opts().get_all()
-                outtmpl: str = parse_outtmpl(
-                    output_template=ytdlp_opts.get("outtmpl", {}).get("default", "{title} [{id}]"),
-                    info_dict=metadata,
-                    params=ytdlp_opts,
-                )
-                if outtmpl:
-                    _path: Path = save_path / outtmpl
-                    if not _path.is_dir():
-                        _path: Path = _path.parent
-
-                    (save_path, _) = get_file(config.download_path, _path.relative_to(config.download_path))
-                    if not str(save_path or "").startswith(str(config.download_path)):
-                        return web.json_response(
-                            data={"error": "Invalid final path folder."}, status=web.HTTPBadRequest.status_code
-                        )
-
-                    if not save_path.exists():
-                        save_path.mkdir(parents=True, exist_ok=True)
-            except Exception as e:
-                LOG.warning(
-                    "Failed to resolve the metadata output path for task '%s'.",
-                    task.name,
-                    extra={"task_id": task.id, "task_name": task.name, "error": str(e)},
-                    exc_info=True,
-                )
-
-        info = {
-            "id": ag(metadata, ["id", "channel_id"]),
-            "id_type": metadata.get("extractor", "").split(":")[0].lower() if metadata.get("extractor") else None,
-            "title": ag(metadata, ["title", "fulltitle"]) or None,
-            "description": metadata.get("description", ""),
-            "uploader": metadata.get("uploader", ""),
-            "tags": metadata.get("tags", []),
-            "year": metadata.get("release_year"),
-            "thumbnails": get_channel_images(metadata.get("thumbnails", {})),
-        }
-
-        if not info.get("title"):
-            return web.json_response(
-                data={"error": "Failed to get title from metadata."}, status=web.HTTPBadRequest.status_code
-            )
-
-        LOG.info(
-            "Generating metadata for task '%s' in '%s'.",
-            task.name,
-            save_path,
-            extra={"task_id": task.id, "task_name": task.name, "save_path": str(save_path)},
-        )
-
-        from yt_dlp.utils import sanitize_filename
-
-        from app.yt_dlp_plugins.postprocessor.nfo_maker import NFOMakerPP
-
-        title: str = sanitize_filename(str(info.get("title") or ""))
-        info_file: Path = save_path / f"{title} [{info.get('id')}].info.json"
-        info_file.write_text(encoder.encode(metadata), encoding="utf-8")
-        info["json_file"] = str(info_file.relative_to(config.download_path))
-
-        xml_file: Path = save_path / "tvshow.nfo"
-        info["nfo_file"] = str(xml_file.relative_to(config.download_path))
-
-        xml_content = "<tvshow>\n"
-        xml_content += f"  <title>{NFOMakerPP._escape_text(info.get('title'))}</title>\n"
-        if info.get("description"):
-            xml_content += f"  <plot>{NFOMakerPP._escape_text(NFOMakerPP._clean_description(str(info.get('description') or '')))}</plot>\n"
-        if info.get("id"):
-            xml_content += f"  <id>{NFOMakerPP._escape_text(info.get('id'))}</id>\n"
-        if info.get("id_type") and info.get("id"):
-            xml_content += f'  <uniqueid type="{NFOMakerPP._escape_text(info.get("id_type"))}" default="true">{NFOMakerPP._escape_text(info.get("id"))}</uniqueid>\n'
-        if info.get("uploader"):
-            xml_content += f"  <studio>{NFOMakerPP._escape_text(info.get('uploader'))}</studio>\n"
-        tags = info.get("tags", [])
-        if isinstance(tags, list):
-            for tag in tags:
-                xml_content += f"  <tag>{NFOMakerPP._escape_text(tag)}</tag>\n"
-        if info.get("year"):
-            xml_content += f"  <year>{info.get('year')}</year>\n"
-        xml_content += "  <status>Continuing</status>\n"
-        xml_content += "</tvshow>\n"
-        xml_file.write_text(xml_content, encoding="utf-8")
-
-        try:
-            from app.library.httpx_client import (
-                Globals,
-                build_request_headers,
-                get_async_client,
-                resolve_curl_transport,
-            )
-
-            ytdlp_args: dict = task.get_ytdlp_opts().get_all()
-            use_curl = resolve_curl_transport()
-            request_headers = build_request_headers(
-                user_agent=request.headers.get("User-Agent", ytdlp_args.get("user_agent", Globals.get_random_agent())),
-                use_curl=use_curl,
-            )
-
-            client = get_async_client(proxy=ytdlp_args.get("proxy"), use_curl=use_curl)
-            thumbnails = info.get("thumbnails", {})
-            if not isinstance(thumbnails, dict):
-                thumbnails = {}
-                info["thumbnails"] = thumbnails
-            for key in thumbnails:
-                url: str | None = None
-                try:
-                    url = thumbnails.get(key)
-                    LOG.info(
-                        "Fetching '%s' thumbnail for task '%s'.",
-                        key,
-                        task.name,
-                        extra={"task_id": task.id, "task_name": task.name, "thumbnail": key, "url": url},
-                    )
-                    if not url:
-                        continue
-
-                    try:
-                        await asyncio.to_thread(validate_url, url, config.allow_internal_urls)
-                    except ValueError as exc:
-                        LOG.warning(
-                            "Task '%s' has an invalid '%s' thumbnail URL because %s.",
-                            task.name,
-                            key,
-                            exc,
-                            extra={"task_id": task.id, "task_name": task.name, "thumbnail": key, "url": url},
-                        )
-                        continue
-
-                    resp = await client.request(
-                        method="GET",
-                        url=url,
-                        follow_redirects=True,
-                        headers=request_headers,
-                    )
-
-                    img_file = save_path / f"{key}.jpg"
-                    img_file.write_bytes(resp.content)
-                    thumbnails[key] = str(img_file.relative_to(config.download_path))
-                except Exception as e:
-                    LOG.warning(
-                        "Failed to fetch '%s' thumbnail for task '%s'.",
-                        key,
-                        task.name,
-                        extra={
-                            "task_id": task.id,
-                            "task_name": task.name,
-                            "thumbnail": key,
-                            "url": url,
-                            "error": str(e),
-                        },
-                        exc_info=True,
-                    )
-                    continue
-        except Exception as e:
-            LOG.warning(
-                "Failed to fetch metadata thumbnails for task '%s'.",
-                task.name,
-                extra={"task_id": task.id, "task_name": task.name, "error": str(e)},
-                exc_info=True,
-            )
-
-        return web.json_response(data=info, status=web.HTTPOk.status_code, dumps=encoder.encode)
-    except ValueError as e:
-        return web.json_response(data={"error": str(e)}, status=web.HTTPBadRequest.status_code)

app/features/tasks/schemas.py

@@ -1,131 +0,0 @@
-from __future__ import annotations
-
-from datetime import datetime  # noqa: TC003
-from typing import Any
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator
-
-from app.features.core.schemas import Pagination
-
-
-class Task(BaseModel):
-    model_config = ConfigDict(from_attributes=True, str_strip_whitespace=True)
-
-    id: int | None = None
-    name: str = Field(min_length=1)
-    url: str = Field(min_length=1)
-    folder: str = ""
-    preset: str = ""
-    timer: str = ""
-    template: str = ""
-    cli: str = ""
-    auto_start: bool = True
-    handler_enabled: bool = True
-    enabled: bool = True
-    created_at: datetime | None = None
-    updated_at: datetime | None = None
-
-    @field_validator("name", mode="before")
-    @classmethod
-    def _normalize_name(cls, value: Any) -> str:
-        if not isinstance(value, str):
-            msg: str = "Name must be a string."
-            raise ValueError(msg)
-        value = value.strip()
-        if not value:
-            msg = "Name cannot be empty."
-            raise ValueError(msg)
-        return value
-
-    @field_validator("url", mode="before")
-    @classmethod
-    def _normalize_url(cls, value: Any) -> str:
-        if not isinstance(value, str):
-            msg: str = "URL must be a string."
-            raise ValueError(msg)
-        value = value.strip()
-        if not value:
-            msg = "URL cannot be empty."
-            raise ValueError(msg)
-
-        from app.library.Utils import validate_url
-
-        try:
-            validate_url(value, allow_internal=True)
-        except ValueError as e:
-            msg = f"Invalid URL format: {e!s}"
-            raise ValueError(msg) from e
-
-        return value
-
-    @field_validator("timer", mode="before")
-    @classmethod
-    def _validate_timer(cls, value: Any) -> str:
-        if not value:
-            return ""
-
-        if not isinstance(value, str):
-            msg: str = "Timer must be a string."
-            raise ValueError(msg)
-
-        value = value.strip()
-        if not value:
-            return ""
-
-        from datetime import UTC, datetime
-
-        try:
-            from cronsim import CronSim
-
-            CronSim(value, datetime.now(UTC))
-        except Exception as e:
-            msg = f"Invalid timer format: {e!s}"
-            raise ValueError(msg) from e
-
-        return value
-
-    @field_validator("cli", mode="before")
-    @classmethod
-    def _validate_cli(cls, value: Any) -> str:
-        if not value:
-            return ""
-
-        if not isinstance(value, str):
-            msg: str = "CLI must be a string."
-            raise ValueError(msg)
-
-        value = value.strip()
-        if not value:
-            return ""
-
-        try:
-            from app.features.ytdlp.utils import arg_converter
-
-            arg_converter(args=value)
-        except Exception as e:
-            msg = f"Invalid command options for yt-dlp: {e!s}"
-            raise ValueError(msg) from e
-
-        return value
-
-
-class TaskPatch(BaseModel):
-    model_config = ConfigDict(str_strip_whitespace=True)
-
-    name: str | None = None
-    url: str | None = None
-    folder: str | None = None
-    preset: str | None = None
-    timer: str | None = None
-    template: str | None = None
-    cli: str | None = None
-    auto_start: bool | None = None
-    handler_enabled: bool | None = None
-    enabled: bool | None = None
-
-
-class TaskList(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    items: list[Task] = Field(default_factory=list)
-    pagination: Pagination

app/features/tasks/service.py

@@ -1,237 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from app.features.core.schemas import CEAction, CEFeature, ConfigEvent
-from app.features.tasks.models import TaskModel
-from app.features.tasks.utils import cron_time
-from app.library.Events import Event, EventBus, Events
-from app.library.log import get_logger
-from app.library.Scheduler import Scheduler
-from app.library.Services import Services
-from app.library.Singleton import Singleton
-
-if TYPE_CHECKING:
-    from aiohttp import web
-
-LOG = get_logger()
-
-
-class Tasks(metaclass=Singleton):
-    def __init__(self):
-        from app.features.tasks.deps import get_tasks_repo
-
-        self._repo = get_tasks_repo()
-        self._loaded: bool = False
-        self._handlers_service = None
-        self._scheduler = Scheduler.get_instance()
-
-    @staticmethod
-    def get_instance() -> Tasks:
-        """Get the singleton instance of Tasks."""
-        return Tasks()
-
-    def attach(self, _: web.Application) -> None:
-        async def handle_started(_, __):
-            await self._repo.run_migrations()
-            await self._load_tasks()
-            await self._init_handlers_service(self._scheduler)
-
-        Services.get_instance().add("tasks_service", self).add("tasks_repository", self._repo)
-
-        async def handle_config_update(e: Event, _):
-            if isinstance(e.data, ConfigEvent) and CEFeature.TASKS == e.data.feature:
-                await self._handle_task_change(e.data)
-
-        EventBus.get_instance().subscribe(
-            Events.CONFIG_UPDATE, handle_config_update, "Tasks.config_update_scheduler"
-        ).subscribe(Events.STARTED, handle_started, "TasksRepository.run_migrations")
-
-    async def on_shutdown(self, _: web.Application) -> None:
-        pass
-
-    async def _load_tasks(self) -> None:
-        tasks = await self._repo.all()
-
-        for task in tasks:
-            if not task.timer or not task.enabled:
-                continue
-
-            try:
-                self._scheduler.add(timer=task.timer, func=self._runner, args=(task,), id=f"task-cronjob-{task.id}")
-                LOG.info(
-                    "Queued task '%s' to run at '%s'.",
-                    task.name,
-                    cron_time(task.timer),
-                    extra={"task_id": task.id, "task_name": task.name, "timer": task.timer},
-                )
-            except Exception as e:
-                LOG.exception(
-                    "Failed to queue task '%s'.",
-                    task.name,
-                    extra={
-                        "task_id": task.id,
-                        "task_name": task.name,
-                        "timer": task.timer,
-                        "exception_type": type(e).__name__,
-                    },
-                )
-
-    async def _init_handlers_service(self, scheduler) -> None:
-        """Initialize the handlers service after migrations."""
-        if self._handlers_service is not None:
-            return
-
-        from app.features.tasks.definitions.service import TaskHandle
-        from app.library.config import Config
-
-        config = Config.get_instance()
-        self._handlers_service = TaskHandle(scheduler, self._repo, config)
-        self._handlers_service.load()
-        LOG.debug("Task handlers service initialized.")
-        Services.get_instance().add("task_handle_service", self._handlers_service)
-
-    async def _handle_task_change(self, event_data) -> None:
-        task_data: dict = event_data.data
-        task_id: str = f"task-cronjob-{task_data['id']}"
-
-        if CEAction.DELETE == event_data.action:
-            if self._scheduler.has(task_id):
-                self._scheduler.remove(task_id)
-
-        elif event_data.action in (CEAction.CREATE, CEAction.UPDATE):
-            if not (task := await self._repo.get(int(task_data["id"]))):
-                return
-
-            if self._scheduler.has(task_id):
-                self._scheduler.remove(task_id)
-
-            if task.timer and task.enabled:
-                self._scheduler.add(timer=task.timer, func=self._runner, args=(task,), id=task_id)
-                LOG.info(
-                    "Queued task '%s' to run at '%s'.",
-                    task.name,
-                    cron_time(task.timer),
-                    extra={"task_id": task.id, "task_name": task.name, "timer": task.timer},
-                )
-
-    async def _runner(self, task: TaskModel) -> None:
-        """
-        Execute a scheduled task.
-
-        Args:
-            task: The TaskModel to execute.
-
-        """
-        import time
-        from datetime import UTC, datetime
-
-        from app.library.config import Config
-        from app.library.downloads import DownloadQueue
-        from app.library.ItemDTO import Item
-
-        timeNow: str = datetime.now(UTC).isoformat()
-        task_id = task.id
-        task_name = task.name
-        try:
-            current_task = await self._repo.get(task_id)
-            if not current_task:
-                LOG.info("Task '%s' no longer exists.", task_name, extra={"task_id": task_id, "task_name": task_name})
-                return
-            task = current_task
-
-            if not task.enabled:
-                LOG.debug(
-                    "Task '%s' is disabled. Skipping execution.",
-                    task.name,
-                    extra={"task_id": task.id, "task_name": task.name},
-                )
-                return
-
-            if not task.url:
-                LOG.error(
-                    "Failed to dispatch task '%s' because it has no URL.",
-                    task.name,
-                    extra={"task_id": task.id, "task_name": task.name},
-                )
-                return
-
-            started: float = time.time()
-
-            config = Config.get_instance()
-            preset: str = task.preset or config.default_preset
-            folder: str = task.folder or ""
-            template: str = task.template or ""
-            cli: str = task.cli or ""
-
-            notify: EventBus = EventBus.get_instance()
-
-            status = await DownloadQueue.get_instance().add(
-                item=Item.format(
-                    {
-                        "url": task.url,
-                        "preset": preset,
-                        "folder": folder,
-                        "template": template,
-                        "cli": cli,
-                        "auto_start": task.auto_start,
-                        "extras": {
-                            "source_name": task.name,
-                            "source_id": str(task.id),
-                            "source_handler": "Tasks",
-                        },
-                    }
-                )
-            )
-
-            timeNow = datetime.now(UTC).isoformat()
-            ended: float = time.time()
-            LOG.info(
-                "Task '%s' completed in %.2f seconds.",
-                task.name,
-                ended - started,
-                extra={
-                    "task_id": task.id,
-                    "task_name": task.name,
-                    "url": task.url,
-                    "preset": preset,
-                    "elapsed_s": round(ended - started, 2),
-                    "status": status.get("status") if isinstance(status, dict) else None,
-                },
-            )
-
-            notify.emit(
-                Events.TASK_DISPATCHED,
-                data={**status, "preset": task.preset} if status else {"preset": task.preset},
-                title=f"Task '{task.name}' dispatched",
-                message=f"Task '{task.name}' dispatched at '{timeNow}'.",
-            )
-            notify.emit(
-                Events.LOG_SUCCESS,
-                data={"preset": task.preset, "lowPriority": True},
-                title="Task completed",
-                message=f"Task '{task.name}' completed in '{ended - started:.2f}'.",
-            )
-        except Exception as e:
-            LOG.exception(
-                "Failed to execute scheduled task '%s'.",
-                task.name,
-                extra={
-                    "task_id": task.id,
-                    "task_name": task.name,
-                    "url": task.url,
-                    "time": timeNow,
-                    "exception_type": type(e).__name__,
-                },
-            )
-            EventBus.get_instance().emit(
-                Events.LOG_ERROR,
-                data={"preset": task.preset},
-                title="Task failed",
-                message=f"Failed to execute '{task.name}'. '{e!s}'",
-            )
-
-    @property
-    def handlers(self):
-        """Get the handlers service instance."""
-        return self._handlers_service

app/features/tasks/tests/__init__.py

@@ -1 +0,0 @@
-"""Tests for tasks feature."""

app/features/tasks/tests/test_tasks_repository.py

@@ -1,267 +0,0 @@
-"""Tests for TasksRepository."""
-
-from __future__ import annotations
-
-import pytest
-import pytest_asyncio
-
-from app.features.tasks.repository import TasksRepository
-from app.library.sqlite_store import SqliteStore
-from app.tests.helpers import make_in_memory_db_path
-
-
-@pytest_asyncio.fixture
-async def repo():
-    """Provide a fresh repository instance with initialized database for each test."""
-    TasksRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-    store = SqliteStore(db_path=make_in_memory_db_path("tasks-repository"))
-    await store.get_connection()
-
-    repository = TasksRepository.get_instance()
-
-    yield repository
-
-    await store.close()
-
-    TasksRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-
-class TestTasksRepository:
-    """Test suite for TasksRepository database operations."""
-
-    @pytest.mark.asyncio
-    async def test_create_task(self, repo):
-        """Create task with valid data."""
-        data = {
-            "name": "Daily Download",
-            "url": "https://example.com/video",
-            "folder": "/downloads",
-            "preset": "audio",
-            "timer": "0 0 * * *",
-            "template": "%(title)s.%(ext)s",
-            "cli": "--format best",
-            "auto_start": True,
-            "handler_enabled": True,
-            "enabled": True,
-        }
-
-        model = await repo.create(data)
-
-        assert model.id is not None, "Should generate ID for new task"
-        assert model.name == "Daily Download", "Should store name correctly"
-        assert model.url == "https://example.com/video", "Should store URL correctly"
-        assert model.folder == "/downloads", "Should store folder correctly"
-        assert model.preset == "audio", "Should store preset correctly"
-        assert model.timer == "0 0 * * *", "Should store timer correctly"
-        assert model.template == "%(title)s.%(ext)s", "Should store template correctly"
-        assert model.cli == "--format best", "Should store CLI correctly"
-        assert model.auto_start is True, "Should store auto_start correctly"
-        assert model.handler_enabled is True, "Should store handler_enabled correctly"
-        assert model.enabled is True, "Should store enabled correctly"
-        assert model.created_at is not None, "Should have created_at timestamp"
-        assert model.updated_at is not None, "Should have updated_at timestamp"
-
-    @pytest.mark.asyncio
-    async def test_create_with_minimal_data(self, repo):
-        """Create task with minimal required data."""
-        data = {
-            "name": "Simple Task",
-            "url": "https://example.com",
-        }
-
-        model = await repo.create(data)
-
-        assert model.name == "Simple Task", "Should store name"
-        assert model.url == "https://example.com", "Should store URL"
-        assert model.folder == "", "Should default folder to empty string"
-        assert model.preset == "", "Should default preset to empty string"
-        assert model.timer == "", "Should default timer to empty string"
-        assert model.template == "", "Should default template to empty string"
-        assert model.cli == "", "Should default CLI to empty string"
-        assert model.auto_start is True, "Should default auto_start to True"
-        assert model.handler_enabled is True, "Should default handler_enabled to True"
-        assert model.enabled is True, "Should default enabled to True"
-
-    @pytest.mark.asyncio
-    async def test_get_by_id(self, repo):
-        """Get task by integer ID."""
-        created = await repo.create(
-            {
-                "name": "Get Test",
-                "url": "https://example.com",
-            }
-        )
-
-        retrieved = await repo.get(created.id)
-
-        assert retrieved is not None, "Should retrieve created task"
-        assert retrieved.id == created.id, "Should retrieve correct task by ID"
-        assert retrieved.name == "Get Test", "Should match created task name"
-
-    @pytest.mark.asyncio
-    async def test_get_by_string_id(self, repo):
-        """Get task by string ID."""
-        created = await repo.create(
-            {
-                "name": "String ID Test",
-                "url": "https://example.com",
-            }
-        )
-
-        retrieved = await repo.get(str(created.id))
-
-        assert retrieved is not None, "Should retrieve by string ID"
-        assert retrieved.id == created.id, "Should match created task ID"
-
-    @pytest.mark.asyncio
-    async def test_get_nonexistent(self, repo):
-        """Get nonexistent task returns None."""
-        result = await repo.get(99999)
-        assert result is None, "Should return None for nonexistent ID"
-
-        result = await repo.get("99999")
-        assert result is None, "Should return None for nonexistent string ID"
-
-    @pytest.mark.asyncio
-    async def test_update_task(self, repo):
-        """Update existing task."""
-        created = await repo.create(
-            {
-                "name": "Update Test",
-                "url": "https://example.com",
-                "preset": "video",
-                "enabled": True,
-            }
-        )
-
-        updated = await repo.update(
-            created.id,
-            {
-                "name": "Updated Name",
-                "preset": "audio",
-                "enabled": False,
-            },
-        )
-
-        assert updated.name == "Updated Name", "Should update name"
-        assert updated.preset == "audio", "Should update preset"
-        assert updated.enabled is False, "Should update enabled"
-        assert updated.url == "https://example.com", "Should preserve unchanged URL"
-
-    @pytest.mark.asyncio
-    async def test_update_nonexistent_raises(self, repo):
-        """Update nonexistent task raises KeyError."""
-        with pytest.raises(KeyError, match="not found"):
-            await repo.update(99999, {"name": "should_fail"})
-
-    @pytest.mark.asyncio
-    async def test_delete_task(self, repo):
-        """Delete existing task."""
-        created = await repo.create(
-            {
-                "name": "Delete Test",
-                "url": "https://example.com",
-            }
-        )
-
-        deleted = await repo.delete(created.id)
-
-        assert deleted.id == created.id, "Should return deleted task"
-
-        result = await repo.get(created.id)
-        assert result is None, "Deleted task should not be retrievable"
-
-    @pytest.mark.asyncio
-    async def test_delete_nonexistent_raises(self, repo):
-        """Delete nonexistent task raises KeyError."""
-        with pytest.raises(KeyError, match="not found"):
-            await repo.delete(99999)
-
-    @pytest.mark.asyncio
-    async def test_get_by_name(self, repo):
-        """Get task by name."""
-        await repo.create(
-            {
-                "name": "Named Task",
-                "url": "https://example.com",
-            }
-        )
-
-        retrieved = await repo.get_by_name("Named Task")
-
-        assert retrieved is not None, "Should retrieve by name"
-        assert retrieved.name == "Named Task", "Should match task name"
-
-    @pytest.mark.asyncio
-    async def test_get_by_name_excludes_id(self, repo):
-        """Get by name can exclude specific ID."""
-        first = await repo.create(
-            {
-                "name": "duplicate",
-                "url": "https://example.com",
-            }
-        )
-
-        result = await repo.get_by_name("duplicate", exclude_id=first.id)
-        assert result is None, "Should not find when excluding only match"
-
-        result = await repo.get_by_name("duplicate", exclude_id=None)
-        assert result is not None, "Should find without exclusion"
-
-    @pytest.mark.asyncio
-    async def test_get_all_enabled(self, repo):
-        """Get all enabled tasks."""
-        await repo.create({"name": "Enabled 1", "url": "https://example.com", "enabled": True})
-        await repo.create({"name": "Disabled", "url": "https://example.com", "enabled": False})
-        await repo.create({"name": "Enabled 2", "url": "https://example.com", "enabled": True})
-
-        enabled = await repo.get_all_enabled()
-
-        assert len(enabled) == 2, "Should return only enabled tasks"
-        assert all(task.enabled for task in enabled), "All tasks should be enabled"
-
-    @pytest.mark.asyncio
-    async def test_get_all_with_timer(self, repo):
-        """Get all tasks with timer configured."""
-        await repo.create({"name": "With Timer", "url": "https://example.com", "timer": "0 0 * * *"})
-        await repo.create({"name": "No Timer", "url": "https://example.com", "timer": ""})
-        await repo.create({"name": "Another Timer", "url": "https://example.com", "timer": "0 12 * * *"})
-
-        with_timer = await repo.get_all_with_timer()
-
-        assert len(with_timer) == 2, "Should return only tasks with timer"
-        assert all(task.timer for task in with_timer), "All tasks should have timer"
-
-    @pytest.mark.asyncio
-    async def test_list_paginated(self, repo):
-        """List paginated returns correct subset."""
-        for i in range(5):
-            await repo.create(
-                {
-                    "name": f"Task {i}",
-                    "url": "https://example.com",
-                }
-            )
-
-        items, total, page, total_pages = await repo.list_paginated(page=1, per_page=2)
-
-        assert len(items) == 2, "Should return 2 items per page"
-        assert total == 5, "Should report total count of 5"
-        assert page == 1, "Should be on page 1"
-        assert total_pages == 3, "Should have 3 pages total"
-
-    @pytest.mark.asyncio
-    async def test_list_ordering(self, repo):
-        """List orders by name ascending."""
-        await repo.create({"name": "Charlie", "url": "https://example.com"})
-        await repo.create({"name": "Alice", "url": "https://example.com"})
-        await repo.create({"name": "Bob", "url": "https://example.com"})
-
-        items = await repo.all()
-
-        assert items[0].name == "Alice", "Should be alphabetically first"
-        assert items[1].name == "Bob", "Should be alphabetically second"
-        assert items[2].name == "Charlie", "Should be alphabetically third"

app/features/tasks/tests/test_tasks_router.py

@@ -1,184 +0,0 @@
-from __future__ import annotations
-
-from types import SimpleNamespace
-from typing import Any
-
-import pytest
-import pytest_asyncio
-from aiohttp import web
-from aiohttp.test_utils import make_mocked_request
-
-from app.features.tasks import router
-from app.features.tasks.definitions.results import TaskFailure, TaskResult
-from app.features.tasks.repository import TasksRepository
-from app.library.encoder import Encoder
-from app.library.sqlite_store import SqliteStore
-from app.tests.helpers import make_in_memory_db_path
-
-
-@pytest_asyncio.fixture
-async def repo():
-    TasksRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-    store = SqliteStore(db_path=make_in_memory_db_path("tasks-router"))
-    await store.get_connection()
-
-    repository = TasksRepository.get_instance()
-
-    yield repository
-
-    await store.close()
-    TasksRepository._reset_singleton()
-    SqliteStore._reset_singleton()
-
-
-@pytest.fixture(autouse=True)
-def patch_get_info(monkeypatch: pytest.MonkeyPatch) -> None:
-    async def _fake_get_info(_url: str, _preset: str) -> tuple[None, None]:
-        return (None, None)
-
-    monkeypatch.setattr(router, "_get_info", _fake_get_info)
-
-
-def _json_request(method: str, path: str, payload: object, *, match_info: dict[str, str] | None = None) -> web.Request:
-    mock_request: Any = make_mocked_request(method, path, match_info=match_info or {}, app=SimpleNamespace())
-
-    async def _json() -> object:
-        return payload
-
-    mock_request.json = _json
-    return mock_request
-
-
-class _Notify:
-    def emit(self, *_args, **_kwargs) -> None:
-        return None
-
-
-class _Handler:
-    def __init__(self, matched: bool | dict[str, bool]) -> None:
-        self._matched = matched
-
-    async def inspect(self, *, url: str, preset: str | None = None, static_only: bool = False, **_kwargs):
-        del preset, static_only
-
-        if isinstance(self._matched, dict):
-            matched = self._matched.get(url, False)
-        else:
-            matched = self._matched
-
-        if matched:
-            return TaskResult(metadata={"matched": True, "handler": "TestHandler"})
-
-        return TaskFailure(message="No handler", metadata={"matched": False, "handler": None})
-
-
-@pytest.mark.asyncio
-async def test_add_requires_timer_without_handler(repo) -> None:
-    request = _json_request(
-        "POST",
-        "/api/tasks/",
-        {"name": "No Timer", "url": "https://example.com/channel"},
-    )
-
-    response = await router.tasks_add(request, repo, Encoder(), _Notify(), _Handler(matched=False))
-
-    assert response.status == web.HTTPBadRequest.status_code
-    assert b"requires a timer" in response.body
-    assert await repo.all() == []
-
-
-@pytest.mark.asyncio
-async def test_add_all_or_nothing(repo) -> None:
-    request = _json_request(
-        "POST",
-        "/api/tasks/",
-        [
-            {"name": "First", "url": "https://example.com/first"},
-            {"url": "https://example.com/second"},
-        ],
-    )
-
-    response = await router.tasks_add(
-        request,
-        repo,
-        Encoder(),
-        _Notify(),
-        _Handler({"https://example.com/first": True, "https://example.com/second": False}),
-    )
-
-    assert response.status == web.HTTPBadRequest.status_code
-    assert b"requires a timer" in response.body
-    assert await repo.all() == []
-
-
-@pytest.mark.asyncio
-async def test_add_allows_handler_only(repo) -> None:
-    request = _json_request(
-        "POST",
-        "/api/tasks/",
-        {"name": "Handler Only", "url": "https://example.com/feed"},
-    )
-
-    response = await router.tasks_add(request, repo, Encoder(), _Notify(), _Handler(matched=True))
-
-    assert response.status == web.HTTPOk.status_code
-    items = await repo.all()
-    assert len(items) == 1
-    assert items[0].name == "Handler Only"
-
-
-@pytest.mark.asyncio
-async def test_update_requires_timer_without_handler(repo) -> None:
-    item = await repo.create({"name": "Needs Timer", "url": "https://example.com/a", "timer": "0 0 * * *"})
-
-    request = _json_request(
-        "PUT",
-        f"/api/tasks/{item.id}",
-        {"name": item.name, "url": item.url, "timer": "", "preset": "", "folder": "", "template": "", "cli": ""},
-        match_info={"id": str(item.id)},
-    )
-
-    response = await router.tasks_update(request, repo, Encoder(), _Notify(), _Handler(matched=False))
-
-    assert response.status == web.HTTPBadRequest.status_code
-    refreshed = await repo.get(item.id)
-    assert refreshed is not None
-    assert refreshed.timer == "0 0 * * *"
-
-
-@pytest.mark.asyncio
-async def test_patch_requires_timer_without_handler(repo) -> None:
-    item = await repo.create({"name": "Patch Timer", "url": "https://example.com/b", "timer": "0 0 * * *"})
-
-    request = _json_request(
-        "PATCH",
-        f"/api/tasks/{item.id}",
-        {"timer": ""},
-        match_info={"id": str(item.id)},
-    )
-
-    response = await router.tasks_patch(request, repo, Encoder(), _Notify(), _Handler(matched=False))
-
-    assert response.status == web.HTTPBadRequest.status_code
-    refreshed = await repo.get(item.id)
-    assert refreshed is not None
-    assert refreshed.timer == "0 0 * * *"
-
-
-@pytest.mark.asyncio
-async def test_patch_requires_timer_when_handler_disabled(repo) -> None:
-    item = await repo.create({"name": "Disabled Handler", "url": "https://example.com/c", "timer": "0 0 * * *"})
-
-    request = _json_request(
-        "PATCH",
-        f"/api/tasks/{item.id}",
-        {"timer": "", "handler_enabled": False},
-        match_info={"id": str(item.id)},
-    )
-
-    response = await router.tasks_patch(request, repo, Encoder(), _Notify(), _Handler(matched=True))
-
-    assert response.status == web.HTTPBadRequest.status_code
-    assert b"handler is disabled" in response.body

app/features/tasks/utils.py

@@ -1,20 +0,0 @@
-from app.library.log import get_logger
-
-LOG = get_logger()
-
-
-def cron_time(timer: str) -> str:
-    try:
-        from datetime import UTC, datetime
-
-        from cronsim import CronSim
-
-        cs = CronSim(timer, datetime.now(UTC))
-        return cs.explain()
-    except Exception as exc:
-        LOG.exception(
-            "Failed to explain task timer '%s'.",
-            timer,
-            extra={"timer": timer, "exception_type": type(exc).__name__},
-        )
-        return timer

app/features/ytdlp/extractor.py

@@ -1,503 +0,0 @@
-import asyncio
-import functools
-import logging
-import multiprocessing
-import pickle
-import sys
-from concurrent.futures import ProcessPoolExecutor
-from pathlib import Path
-from typing import Any
-
-from aiohttp import web
-
-from app.features.ytdlp.utils import _DATA, LogWrapper, get_archive_id
-from app.features.ytdlp.ytdlp import YTDLP
-from app.library.log import get_logger
-from app.library.Services import Services
-from app.library.Singleton import Singleton
-
-LOG = get_logger()
-
-LIVE_REEXTRACT_STATUSES: set[str] = {"is_live", "post_live"}
-REEXTRACT_INFO_KEY = "_ytptube_reextract"
-
-
-def _ytdlp_logger(target: logging.Logger):
-    return _YTDLPLogger(target)
-
-
-class _YTDLPLogger:
-    def __init__(self, target: logging.Logger) -> None:
-        self.target = target
-
-    def __call__(self, level: int, msg: str, *args: Any, **kwargs: Any) -> None:
-        kwargs.setdefault("stacklevel", 4)
-        if level <= logging.DEBUG and isinstance(msg, str) and msg.startswith("[debug] "):
-            self.target.debug(msg.removeprefix("[debug] "), *args, **kwargs)
-            return
-
-        if level <= logging.DEBUG:
-            self.target.info(msg, *args, **kwargs)
-            return
-
-        self.target.log(level, msg, *args, **kwargs)
-
-
-class _LogCapture:
-    def __init__(self, logs: list[str]) -> None:
-        self.logs = logs
-
-    def __call__(self, _: int, msg: str, *args: Any, **__: Any) -> None:
-        self.logs.append(msg % args if args else msg)
-
-
-def _get_process_pool_kwargs() -> dict[str, Any]:
-    """Use a fork-based pool for frozen Linux builds."""
-    if sys.platform == "linux" and getattr(sys, "frozen", False):
-        return {"mp_context": multiprocessing.get_context("fork")}
-
-    return {}
-
-
-class ExtractorConfig:
-    """Configuration for the extractor."""
-
-    def __init__(
-        self,
-        concurrency: int = 4,
-        timeout: float = 60.0,
-        wait_threshold: float = 0.2,
-    ):
-        """
-        Initialize extractor configuration.
-
-        Args:
-            concurrency: Maximum number of concurrent extract operations
-            timeout: Timeout for extract operations in seconds
-            wait_threshold: Log warning if waiting exceeds this threshold in seconds
-
-        """
-        self.concurrency = concurrency
-        self.timeout = timeout
-        self.wait_threshold = wait_threshold
-
-
-def _sleep_timeout(config: dict[str, Any], timeout: float, budget_sleep: bool) -> float:
-    if not budget_sleep:
-        return timeout
-
-    sleep_requests = config.get("sleep_interval_requests")
-    if not isinstance(sleep_requests, int | float) or sleep_requests <= 0:
-        return timeout
-
-    return timeout + min(float(sleep_requests) * 20, 300.0)
-
-
-class ExtractorPool(metaclass=Singleton):
-    """
-    Manages process pool and semaphore for video information extraction.
-
-    This class uses the Singleton pattern to ensure only one instance exists.
-    """
-
-    def __init__(self):
-        """Initialize the extractor pool."""
-        self._pool: ProcessPoolExecutor | None = None
-        self._semaphore: asyncio.Semaphore | None = None
-        self._config: ExtractorConfig | None = None
-
-    @classmethod
-    def get_instance(cls) -> "ExtractorPool":
-        """
-        Get the singleton instance.
-
-        Returns:
-            ExtractorPool instance
-
-        """
-        return cls()
-
-    def attach(self, app: web.Application) -> None:
-        """Attach the extractor pool to the application (no-op for now)."""
-        app.on_shutdown.append(self.shutdown)
-        Services.get_instance().add(type(self).__name__, self)
-
-    def _ensure_initialized(self, config: ExtractorConfig) -> None:
-        """
-        Ensure pool and semaphore are initialized.
-
-        Args:
-            config: Extractor configuration
-
-        """
-        if self._config is None or self._config.concurrency != config.concurrency:
-            self._config = config
-
-        if self._semaphore is None:
-            self._semaphore = asyncio.Semaphore(config.concurrency)
-
-        if self._pool is None:
-            self._pool = ProcessPoolExecutor(max_workers=config.concurrency, **_get_process_pool_kwargs())
-            LOG.info("Initialized extractor process pool with %s workers", config.concurrency)
-
-    def get_pool(self, config: ExtractorConfig) -> ProcessPoolExecutor:
-        """
-        Get the process pool executor.
-
-        Args:
-            config: Extractor configuration
-
-        Returns:
-            ProcessPoolExecutor instance
-
-        """
-        self._ensure_initialized(config)
-        if self._pool is None:
-            msg = "Process pool not initialized"
-            raise RuntimeError(msg)
-        return self._pool
-
-    def get_semaphore(self, config: ExtractorConfig) -> asyncio.Semaphore:
-        """
-        Get the semaphore for limiting concurrency.
-
-        Args:
-            config: Extractor configuration
-
-        Returns:
-            asyncio.Semaphore instance
-
-        """
-        self._ensure_initialized(config)
-        if self._semaphore is None:
-            msg = "Semaphore not initialized"
-            raise RuntimeError(msg)
-        return self._semaphore
-
-    async def shutdown(self) -> None:
-        """Shutdown the extractor pool and clean up resources."""
-        if self._pool is not None:
-            try:
-                self._pool.shutdown(wait=False, cancel_futures=False)
-                LOG.debug("Extractor process pool shutdown complete")
-            except Exception as exc:
-                LOG.exception(
-                    "Failed to shut down the extractor process pool.",
-                    extra={"exception_type": type(exc).__name__},
-                )
-            else:
-                self._pool = None
-
-        self._semaphore = None
-        self._config = None
-
-
-def _is_picklable(value: Any) -> bool:
-    """
-    Check if a value can be pickled.
-
-    Args:
-        value: Value to check
-
-    Returns:
-        bool: True if value can be pickled, False otherwise
-
-    """
-    try:
-        pickle.dumps(value)
-        return True
-    except Exception:
-        return False
-
-
-def _sanitize_picklable(value: Any) -> Any:
-    """
-    Convert a value to a picklable format.
-
-    Args:
-        value: Value to sanitize
-
-    Returns:
-        Sanitized value that can be pickled
-
-    """
-    if isinstance(value, Path):
-        return str(value)
-    if isinstance(value, dict):
-        return {k: _sanitize_picklable(v) for k, v in value.items()}
-    if isinstance(value, (list, tuple, set)):
-        return [_sanitize_picklable(v) for v in value]
-    if _is_picklable(value):
-        return value
-    return str(value)
-
-
-def _sanitize_config(config: dict[str, Any]) -> dict[str, Any]:
-    """
-    Sanitize configuration for use in process pool.
-
-    Removes unpicklable keys and converts values to picklable formats.
-
-    Args:
-        config: Configuration dictionary
-
-    Returns:
-        Sanitized configuration dictionary
-
-    """
-    sanitized: dict[str, Any] = {}
-    for key, value in config.items():
-        if key in {"logger", "progress_hooks", "postprocessor_hooks", "postprocessors", "post_hooks"}:
-            continue
-        sanitized[key] = _sanitize_picklable(value)
-
-    return sanitized
-
-
-def needs_reextract(info: dict[str, Any]) -> bool:
-    return bool(info.get("is_live") or info.get("live_status") in LIVE_REEXTRACT_STATUSES)
-
-
-def _process_safe_info(info: dict[str, Any]) -> dict[str, Any]:
-    if needs_reextract(info):
-        info = dict(info)
-        info[REEXTRACT_INFO_KEY] = True
-        for key in ("formats", "requested_formats", "requested_downloads", "fragments"):
-            info.pop(key, None)
-
-    if _is_picklable(info):
-        return info
-
-    return YTDLP.sanitize_info(info, remove_private_keys=False)
-
-
-def extract_info_sync(
-    config: dict[str, Any],
-    url: str,
-    debug: bool = False,
-    no_archive: bool = False,
-    follow_redirect: bool = False,
-    sanitize_info: bool = False,
-    capture_logs: int | None = None,
-    process_safe: bool = False,
-    **kwargs,
-) -> tuple[dict[str, Any] | None, list[str]]:
-    """
-    Extract video information from a URL.
-
-    Args:
-        config: yt-dlp configuration options
-        url: URL to extract information from
-        debug: Enable debug logging
-        no_archive: Disable download archive
-        follow_redirect: Follow URL redirects
-        sanitize_info: Sanitize the extracted information
-        capture_logs: If provided (e.g., logging.WARNING), capture logs at this level.
-        process_safe: Strip non-pickleable data for safe inter-process communication.
-        **kwargs: Additional arguments
-
-    Returns:
-        tuple[dict | None, list[str]]: Extracted information and captured logs.
-
-    """
-    params: dict[str, Any] = {**config, **_DATA.YTDLP_PARAMS, "simulate": True}
-
-    if debug:
-        params["verbose"] = True
-        params.pop("quiet", None)
-
-    suppress: tuple[str, ...] = ()
-    patterns = kwargs.get("suppress_logs")
-    if isinstance(patterns, list | tuple):
-        suppress = tuple(value for value in patterns if isinstance(value, str) and value)
-
-    log_wrapper = LogWrapper(suppress=suppress)
-    id_dict: dict[str, str | None] = get_archive_id(url=url)
-    archive_id: str | None = f".{id_dict['id']}" if id_dict.get("id") else None
-    logger_name: str = f"yt-dlp{archive_id or '.extract_info'}"
-
-    try:
-        log_wrapper.add_target(
-            target=_ytdlp_logger(logging.getLogger(logger_name)),
-            level=logging.DEBUG,
-            name=logger_name,
-        )
-
-        captured_logs: list[str] = kwargs.get("captured_logs", [])
-        if capture_logs is not None:
-            log_wrapper.add_target(
-                target=_LogCapture(captured_logs),
-                level=capture_logs,
-                name="log-capture",
-            )
-
-        if log_wrapper.has_targets():
-            if "logger" in params:
-                log_wrapper.add_target(target=params["logger"], level=logging.DEBUG)
-
-            params["logger"] = log_wrapper
-
-        if kwargs.get("no_log", False):
-            params["logger"] = LogWrapper()
-            params["quiet"] = True
-            params["no_warnings"] = True
-
-        if no_archive and "download_archive" in params:
-            del params["download_archive"]
-
-        data: dict[str, Any] | None = YTDLP(params=params).extract_info(url, download=False)
-
-        if data and follow_redirect and "_type" in data and "url" == data["_type"]:
-            return extract_info_sync(
-                config,
-                data["url"],
-                debug=debug,
-                no_archive=no_archive,
-                follow_redirect=follow_redirect,
-                sanitize_info=sanitize_info,
-                capture_logs=capture_logs,
-                process_safe=process_safe,
-                captured_logs=captured_logs,
-                **kwargs,
-            )
-
-        if not data:
-            return (data, captured_logs)
-
-        try:
-            from app.features.ytdlp.mini_filter import match_str
-
-            data["is_premiere"] = match_str("media_type=video & duration & is_live", data)
-            if not data["is_premiere"]:
-                data["is_premiere"] = "video" == data.get("media_type") and "is_upcoming" == data.get("live_status")
-        except ImportError:
-            pass
-
-        result = YTDLP.sanitize_info(data, remove_private_keys=True) if sanitize_info else data
-
-        if process_safe and isinstance(result, dict):
-            result = _process_safe_info(result)
-
-        return (result, captured_logs)
-    finally:
-        logging.Logger.manager.loggerDict.pop(logger_name, None)
-
-
-async def fetch_info(
-    config: dict[str, Any],
-    url: str,
-    debug: bool = False,
-    no_archive: bool = False,
-    follow_redirect: bool = False,
-    sanitize_info: bool = False,
-    capture_logs: int | None = None,
-    extractor_config: ExtractorConfig | None = None,
-    budget_sleep: bool = False,
-    **kwargs,
-) -> tuple[dict[str, Any] | None, list[str]]:
-    """
-    Extract video information from a URL.
-
-    This function uses a process pool to avoid blocking the event loop.
-    If the process pool fails, it falls back to using a thread pool.
-
-    Args:
-        config: yt-dlp configuration options
-        url: URL to extract information from
-        debug: Enable debug logging
-        no_archive: Disable download archive
-        follow_redirect: Follow URL redirects
-        sanitize_info: Sanitize the extracted information
-        capture_logs: If provided (e.g., logging.WARNING), capture logs
-        extractor_config: Configuration for the extractor
-        budget_sleep: Whether to add extra timeout budget for request-sleep-heavy extraction
-        **kwargs: Additional arguments
-
-    Returns:
-        tuple[dict | None, list[str]]: Extracted information and captured logs.
-
-    """
-    if extractor_config is None:
-        from app.library.config import Config
-
-        conf = Config.get_instance()
-        extractor_config = ExtractorConfig(
-            concurrency=conf.extract_info_concurrency,
-            timeout=conf.extract_info_timeout,
-            wait_threshold=0.2,
-        )
-
-    pool_manager: ExtractorPool = ExtractorPool.get_instance()
-    semaphore: asyncio.Semaphore = pool_manager.get_semaphore(extractor_config)
-
-    await semaphore.acquire()
-    loop = asyncio.get_running_loop()
-
-    safe_config = _sanitize_config(config)
-    safe_kwargs = _sanitize_picklable(kwargs)
-    safe_kwargs.pop("process_safe", None)
-    timeout = _sleep_timeout(safe_config, extractor_config.timeout, budget_sleep)
-
-    try:
-        try:
-            executor: ProcessPoolExecutor = pool_manager.get_pool(extractor_config)
-
-            return await asyncio.wait_for(
-                fut=loop.run_in_executor(
-                    executor,
-                    functools.partial(
-                        extract_info_sync,
-                        config=safe_config,
-                        url=url,
-                        debug=debug,
-                        no_archive=no_archive,
-                        follow_redirect=follow_redirect,
-                        sanitize_info=sanitize_info,
-                        capture_logs=capture_logs,
-                        process_safe=True,
-                        **safe_kwargs,
-                    ),
-                ),
-                timeout=timeout,
-            )
-
-        except TimeoutError:
-            raise
-
-        except Exception as exc:
-            LOG.warning(
-                "yt-dlp extraction for '%s' fell back to the thread pool after the process pool failed.",
-                url,
-                extra={
-                    "url": url,
-                    "timeout": timeout,
-                    "concurrency": extractor_config.concurrency,
-                    "pool": "process",
-                    "fallback": "thread",
-                    "follow_redirect": follow_redirect,
-                    "no_archive": no_archive,
-                    "sanitize_info": sanitize_info,
-                    "capture_logs_level": capture_logs,
-                    "exception_type": type(exc).__name__,
-                },
-                exc_info=True,
-            )
-            return await asyncio.wait_for(
-                fut=loop.run_in_executor(
-                    None,
-                    functools.partial(
-                        extract_info_sync,
-                        config=config,
-                        url=url,
-                        debug=debug,
-                        no_archive=no_archive,
-                        follow_redirect=follow_redirect,
-                        sanitize_info=sanitize_info,
-                        capture_logs=capture_logs,
-                        **kwargs,
-                    ),
-                ),
-                timeout=timeout,
-            )
-    finally:
-        semaphore.release()

app/features/ytdlp/outtmpl.py

@@ -1,113 +0,0 @@
-from __future__ import annotations
-
-import re
-import secrets
-import string
-from typing import TYPE_CHECKING, Any
-
-from yt_dlp.utils._utils import STR_FORMAT_RE_TMPL, STR_FORMAT_TYPES
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-OUTTMPL_RX: re.Pattern[str] = re.compile(STR_FORMAT_RE_TMPL.format("[^)]*", f"[{STR_FORMAT_TYPES}ljhqBUDS]"))
-CALL_RX: re.Pattern[str] = re.compile(r"^(?P<name>ytp_[A-Za-z0-9_]+)(?P<args>(?::[A-Za-z0-9_]+)*)(?P<rest>.*)$")
-OPERATORS: tuple[str, ...] = (",", "&", "|", ">", "+", "-", "*")
-
-
-def random_text(args: tuple[str, ...], _info_dict: dict[str, Any], _state: dict[str, Any]) -> str:
-    if not args:
-        msg = "ytp_random requires a length argument. Use %(ytp_random:<length>)s."
-        raise ValueError(msg)
-
-    if len(args) > 2:
-        msg = "ytp_random accepts at most 2 arguments: length and optional mode."
-        raise ValueError(msg)
-
-    try:
-        length = int(args[0])
-    except ValueError as exc:
-        msg: str = f"ytp_random length must be an integer, got {args[0]!r}."
-        raise ValueError(msg) from exc
-
-    if length < 1:
-        msg = "ytp_random length must be greater than 0."
-        raise ValueError(msg)
-
-    mode = args[1].lower() if len(args) > 1 else "mixed"
-    if mode in ("mixed", "m"):
-        alphabet = string.ascii_letters + string.digits
-    elif mode in ("d", "digit", "digits", "int", "ints", "number", "numbers"):
-        alphabet = string.digits
-    elif mode in ("s", "str", "string", "strings", "alpha", "letter", "letters"):
-        alphabet = string.ascii_letters
-    else:
-        msg = f"ytp_random mode must be one of mixed, d, or s. Got {args[1]!r}."
-        raise ValueError(msg)
-
-    return "".join(secrets.choice(alphabet) for _ in range(length))
-
-
-CALLS: dict[str, Callable[[tuple[str, ...], dict[str, Any], dict[str, Any]], Any]] = {
-    "ytp_random": random_text,
-}
-
-
-def split_call(key: str) -> tuple[str, tuple[str, ...], str] | None:
-    if not key.startswith("ytp_"):
-        return None
-
-    if not (match := CALL_RX.match(key)):
-        msg = f"Invalid YTPTube output template callable {key!r}."
-        raise ValueError(msg)
-
-    name: str | Any = match.group("name")
-    rest: str | Any = match.group("rest") or ""
-    if rest and rest[0] not in OPERATORS:
-        msg = f"Invalid YTPTube output template callable {key!r}."
-        raise ValueError(msg)
-
-    if name not in CALLS:
-        msg = f"Unsupported YTPTube output template callable {name!r}."
-        raise ValueError(msg)
-
-    raw_args: str | Any = match.group("args")
-    args: tuple[str | Any, ...] = tuple(part for part in raw_args.split(":") if part)
-    return name, args, rest
-
-
-def rewrite_outtmpl(
-    outtmpl: str,
-    info_dict: dict[str, Any],
-    cache: dict[str, Any] | None = None,
-) -> tuple[str, dict[str, Any]]:
-    if "%(ytp_" not in outtmpl:
-        return outtmpl, info_dict
-
-    state: dict[str, Any] = {}
-    values: dict[str, Any] = {} if cache is None else cache
-    fields: dict[str, str] = {}
-    enriched = dict(info_dict)
-
-    def replace(match: re.Match[str]) -> str:
-        if not (key := match.group("key")):
-            return match.group(0)
-
-        parsed = split_call(key)
-        if not parsed:
-            return match.group(0)
-
-        name, args, rest = parsed
-        call_key: str = ":".join((name, *args)) if args else name
-
-        if call_key not in values:
-            values[call_key] = CALLS[name](args, enriched, state)
-
-        if call_key not in fields:
-            fields[call_key] = f"__ytptube_outtmpl_{len(fields)}"
-
-        synthetic_key: str = fields[call_key]
-        enriched[synthetic_key] = values[call_key]
-        return f"{match.group('prefix')}%({synthetic_key}{rest}){match.group('format')}"
-
-    return OUTTMPL_RX.sub(replace, outtmpl), enriched

app/features/ytdlp/patches.py

@@ -1,109 +0,0 @@
-import subprocess
-import sys
-from typing import Any
-
-from app.library.log import get_logger
-
-LOG = get_logger()
-
-
-def patch_metadataparser() -> None:
-    """
-    Patches yt_dlp MetadataParserPP action to handle subprocess pickling issues.
-    """
-    try:
-        from yt_dlp.postprocessor.metadataparser import MetadataParserPP
-        from yt_dlp.utils import Namespace
-    except Exception as exc:
-        LOG.warning(
-            "Unable to import yt-dlp metadata parser for patching: %s",
-            exc,
-            extra={"patch": "metadata_parser", "exception_type": type(exc).__name__},
-            exc_info=True,
-        )
-        return
-
-    if getattr(MetadataParserPP.Actions, "_ytptube_patched", False):
-        return
-
-    class _ActionNS(Namespace):
-        _ACTIONS_STR: list[str] = []
-
-        @staticmethod
-        def _get_name(func) -> str | None:
-            if not callable(func):
-                return None
-
-            target = getattr(func, "__func__", func)
-            module_name = getattr(target, "__module__", None)
-            qual_name = getattr(target, "__qualname__", getattr(target, "__name__", None))
-
-            return f"{module_name}.{qual_name}" if module_name and qual_name else None
-
-        def __contains__(self, candidate: object) -> bool:
-            if candidate in self.__dict__.values():
-                return True
-
-            if func_name := _ActionNS._get_name(candidate):
-                if len(_ActionNS._ACTIONS_STR) < 1:
-                    _ActionNS._ACTIONS_STR.extend(
-                        [value for value in (_ActionNS._get_name(value) for value in self.__dict__.values()) if value]
-                    )
-
-                return func_name in _ActionNS._ACTIONS_STR
-
-            return False
-
-    actions_dict: dict[str, Any] = dict(MetadataParserPP.Actions.items_)
-    MetadataParserPP.Actions = _ActionNS(**actions_dict)
-    MetadataParserPP.Actions._ytptube_patched = True
-    LOG.debug("MetadataParserPP action namespace patch applied successfully.")
-
-
-def patch_windows_popen_wait() -> None:
-    if sys.platform != "win32":
-        return
-
-    try:
-        from yt_dlp.utils import Popen
-    except Exception as exc:
-        LOG.warning(
-            "Unable to import yt-dlp Popen for patching: %s",
-            exc,
-            extra={"patch": "windows_popen_wait", "exception_type": type(exc).__name__},
-            exc_info=True,
-        )
-        return
-
-    if getattr(Popen, "_ytptube_wait_patched", False):
-        return
-
-    original_wait = Popen.wait
-
-    # Windows subprocess waits can swallow the synthetic interrupt we use to
-    # stop live downloads, especially while yt-dlp is blocked on ffmpeg.
-    def interruptible_wait(self, timeout=None):
-        if timeout is not None:
-            return original_wait(self, timeout=timeout)
-
-        while True:
-            try:
-                return original_wait(self, timeout=0.1)
-            except subprocess.TimeoutExpired:
-                continue
-
-    Popen.wait = interruptible_wait
-    Popen._ytptube_wait_patched = True
-    LOG.debug("yt_dlp Popen.wait Windows patch applied successfully.")
-
-
-def apply_ytdlp_patches() -> None:
-    try:
-        patch_metadataparser()
-    except Exception as exc:
-        LOG.debug("Metadata parser patch failed to apply: %s", exc)
-
-    try:
-        patch_windows_popen_wait()
-    except Exception as exc:
-        LOG.debug("Windows Popen wait patch failed to apply: %s", exc)

app/features/ytdlp/router.py

@@ -1,582 +0,0 @@
-import asyncio
-import json
-import logging
-import time
-from collections import OrderedDict
-from collections.abc import Iterable
-from typing import Any
-
-from aiohttp import web
-from aiohttp.web import Request, Response
-
-from app.features.presets.service import Presets
-from app.features.ytdlp.archiver import Archiver
-from app.features.ytdlp.extractor import fetch_info
-from app.features.ytdlp.utils import archive_read, arg_converter, get_archive_id
-from app.features.ytdlp.ytdlp_opts import YTDLPCli, YTDLPOpts
-from app.library.cache import Cache
-from app.library.config import Config
-from app.library.encoder import Encoder
-from app.library.ItemDTO import Item
-from app.library.log import get_logger
-from app.library.router import route
-from app.library.Utils import validate_url
-
-LOG = get_logger()
-
-
-def _get_preset_archive(preset: str) -> str | None:
-    """
-    Resolve the archive file path for a given preset.
-
-    Validates that the preset exists and that applying the preset results
-    in yt-dlp options that contain a 'download_archive' path.
-    """
-    if not preset or not Presets.get_instance().has(preset):
-        return None
-
-    try:
-        opts: dict = YTDLPOpts.get_instance().preset(preset).get_all()
-    except Exception as e:
-        LOG.exception(
-            "Failed to build yt-dlp options for preset '%s': %s.",
-            preset,
-            e,
-            extra={"preset": preset, "exception_type": type(e).__name__},
-        )
-        return None
-
-    if not (archive_file := opts.get("download_archive")):
-        return None
-
-    if not isinstance(archive_file, str) or len(archive_file.strip()) < 1:
-        return None
-
-    return archive_file.strip()
-
-
-def _normalize_ids(items: Iterable[str] | None) -> tuple[list[str], list[str]]:
-    """
-    Validate and normalize archive IDs.
-
-    - Trims whitespace
-    - Enforces that each ID has at least two whitespace-separated tokens
-      (e.g., "youtube ABC123") as required by yt-dlp's archive format
-    - De-duplicates while preserving order
-
-    Returns a tuple: (valid_ids, invalid_inputs)
-    """
-    if not items:
-        return ([], [])
-
-    seen: set[str] = set()
-    valid: list[str] = []
-    invalid: list[str] = []
-
-    for raw in items:
-        if raw is None:
-            continue
-
-        s = str(raw).strip()
-        if not s:
-            continue
-
-        if len(s.split()) < 2:
-            invalid.append(s)
-            continue
-
-        if s in seen:
-            continue
-
-        seen.add(s)
-        valid.append(s)
-
-    return (valid, invalid)
-
-
-@route("GET", "api/archiver/", "archiver")
-async def archiver_get(request: Request) -> Response:
-    """
-    Read IDs from the download archive for a given preset.
-
-    Query params:
-      - preset: required preset name/id
-      - ids: optional comma-separated list to filter; when omitted, returns all
-    """
-    preset: str | None = request.query.get("preset")
-    if not preset:
-        return web.json_response(data={"error": "preset is required."}, status=web.HTTPBadRequest.status_code)
-
-    archive_file: str | None = _get_preset_archive(preset)
-    if not archive_file:
-        return web.json_response(
-            data={"error": f"Preset '{preset}' does not provide a download_archive."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    ids_param: str | None = request.query.get("ids")
-    ids: list[str] = []
-    if ids_param:
-        ids_list = [s.strip() for s in ids_param.split(",") if s and s.strip()]
-        ids, invalid = _normalize_ids(ids_list)
-        if invalid:
-            return web.json_response(
-                data={"error": "invalid ids provided.", "invalid_items": invalid},
-                status=web.HTTPBadRequest.status_code,
-            )
-
-    try:
-        data: list[str] = Archiver.get_instance().read(archive_file, ids or None)
-        return web.json_response(
-            data={"file": archive_file, "items": data, "count": len(data)}, status=web.HTTPOk.status_code
-        )
-    except Exception as e:
-        LOG.exception(
-            "Failed to read archive file '%s' for preset '%s': %s.",
-            archive_file,
-            preset,
-            e,
-            extra={
-                "route": "api/archiver/",
-                "action": "read_archive",
-                "preset": preset,
-                "archive_file": archive_file,
-                "ids": ids,
-            },
-        )
-        return web.json_response(
-            data={"error": f"Failed to read archive file for preset '{preset}'.", "message": str(e)},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-
-@route("POST", "api/archiver/", "archiver_add")
-async def archiver_add(request: Request) -> Response:
-    """
-    Append IDs to the download archive for a given preset.
-
-    Body: { "preset": string, "items": [string, ...], "skip_check": bool? }
-    """
-    post = await request.json()
-    preset: str | None = post.get("preset") if isinstance(post, dict) else None
-    if not preset:
-        return web.json_response(data={"error": "preset is required."}, status=web.HTTPBadRequest.status_code)
-
-    archive_file: str | None = _get_preset_archive(preset)
-    if not archive_file:
-        return web.json_response(
-            data={"error": f"Preset '{preset}' does not provide a download_archive."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    items, invalid = _normalize_ids((post or {}).get("items", [])) if isinstance(post, dict) else ([], [])
-    if invalid:
-        return web.json_response(
-            data={"error": "invalid ids provided.", "invalid_items": invalid},
-            status=web.HTTPBadRequest.status_code,
-        )
-    if len(items) < 1:
-        return web.json_response(
-            data={"error": "items is required and must be a non-empty list."}, status=web.HTTPBadRequest.status_code
-        )
-
-    skip_check: bool = bool(post.get("skip_check", False)) if isinstance(post, dict) else False
-
-    try:
-        status: bool = Archiver.get_instance().add(archive_file, items, skip_check=skip_check)
-        return web.json_response(
-            data={"file": archive_file, "status": status, "items": items},
-            status=web.HTTPOk.status_code if status else web.HTTPNotModified.status_code,
-        )
-    except Exception as e:
-        LOG.exception(
-            "Failed to add %s item(s) to archive file '%s' for preset '%s': %s.",
-            len(items),
-            archive_file,
-            preset,
-            e,
-            extra={
-                "route": "api/archiver/",
-                "action": "add_archive_items",
-                "preset": preset,
-                "archive_file": archive_file,
-                "item_count": len(items),
-                "skip_check": skip_check,
-            },
-        )
-        return web.json_response(
-            data={"error": f"Failed to add items to archive for preset '{preset}'.", "message": str(e)},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-
-@route("DELETE", "api/archiver/", "archiver_delete")
-async def archiver_delete(request: Request) -> Response:
-    """
-    Remove IDs from the download archive for a given preset.
-
-    Body: { "preset": string, "items": [string, ...] }
-    """
-    post = await request.json()
-    preset: str | None = post.get("preset") if isinstance(post, dict) else None
-    if not preset:
-        return web.json_response(data={"error": "preset is required."}, status=web.HTTPBadRequest.status_code)
-
-    archive_file: str | None = _get_preset_archive(preset)
-    if not archive_file:
-        return web.json_response(
-            data={"error": f"Preset '{preset}' does not provide a download_archive."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    items, invalid = _normalize_ids((post or {}).get("items", [])) if isinstance(post, dict) else ([], [])
-    if invalid:
-        return web.json_response(
-            data={"error": "invalid ids provided.", "invalid_items": invalid},
-            status=web.HTTPBadRequest.status_code,
-        )
-    if len(items) < 1:
-        return web.json_response(
-            data={"error": "items is required and must be a non-empty list."}, status=web.HTTPBadRequest.status_code
-        )
-
-    try:
-        status: bool = Archiver.get_instance().delete(archive_file, items)
-        return web.json_response(
-            data={"file": archive_file, "status": status, "items": items},
-            status=web.HTTPOk.status_code if status else web.HTTPNotModified.status_code,
-        )
-    except Exception as e:
-        LOG.exception(
-            "Failed to delete %s item(s) from archive file '%s' for preset '%s': %s.",
-            len(items),
-            archive_file,
-            preset,
-            e,
-            extra={
-                "route": "api/archiver/",
-                "action": "delete_archive_items",
-                "preset": preset,
-                "archive_file": archive_file,
-                "item_count": len(items),
-            },
-        )
-        return web.json_response(
-            data={"error": f"Failed to delete items from archive for preset '{preset}'.", "message": str(e)},
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-
-@route("POST", "api/yt-dlp/convert/", "convert")
-async def convert(request: Request) -> Response:
-    """
-    Convert the yt-dlp args to a dict.
-
-    Args:
-        request (Request): The request object.
-
-    Returns:
-        Response: The response object.
-
-    """
-    post = await request.json()
-    args: str | None = post.get("args")
-
-    if not args:
-        return web.json_response(data={"error": "args param is required."}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        response: dict[str, Any] = {"opts": {}, "output_template": None, "download_path": None}
-
-        data = arg_converter(args, dumps=True)
-
-        if "outtmpl" in data and "default" in data["outtmpl"]:
-            response["output_template"] = data["outtmpl"]["default"]
-
-        if "paths" in data and "home" in data["paths"]:
-            response["download_path"] = data["paths"]["home"]
-
-        if "format" in data:
-            response["format"] = data["format"]
-
-        from app.features.ytdlp.utils import _DATA
-
-        bad_options = {k: v for d in _DATA.REMOVE_KEYS for k, v in d.items()}
-        removed_options = []
-
-        for key in data:
-            if key in bad_options.items():
-                removed_options.append(bad_options[key])
-                continue
-            if not key.startswith("_"):
-                response["opts"][key] = data[key]
-
-        if len(removed_options) > 0:
-            response["removed_options"] = removed_options
-
-        return web.json_response(data=response, status=web.HTTPOk.status_code)
-    except Exception as e:
-        err = str(e).strip()
-        err = err.split("\n")[-1] if "\n" in err else err
-        err = err.replace("main.py: error: ", "").strip().capitalize()
-        return web.json_response(
-            data={"error": f"Failed to parse command options for yt-dlp. '{err}'."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-
-@route("GET", "api/yt-dlp/url/info/", "get_info")
-async def get_info(request: Request, cache: Cache, config: Config) -> Response:
-    """
-    Get the video info.
-
-    Args:
-        request (Request): The request object.
-        cache (Cache): The cache instance.
-        config (Config): The config instance.
-
-    Returns:
-        Response: The response object
-
-    """
-    url: str | None = request.query.get("url")
-    if not url:
-        return web.json_response(
-            data={"status": False, "message": "URL is required.", "error": "URL is required."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        await asyncio.to_thread(validate_url, url, config.allow_internal_urls)
-    except ValueError as e:
-        return web.json_response(
-            data={"status": False, "message": str(e), "error": str(e)},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    opts: YTDLPOpts = YTDLPOpts.get_instance()
-
-    preset: str = request.query.get("preset", config.default_preset)
-    if not Presets.get_instance().get(preset):
-        msg: str = f"Preset '{preset}' does not exist."
-        return web.json_response(
-            data={"status": False, "message": msg, "error": msg},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    opts = opts.preset(preset)
-
-    if cli_args := request.query.get("args", None):
-        try:
-            arg_converter(cli_args, dumps=True)
-            opts = opts.add_cli(cli_args, from_user=True)
-        except Exception as e:
-            err = str(e).strip()
-            err = err.split("\n")[-1] if "\n" in err else err
-            err = err.replace("main.py: error: ", "").strip().capitalize()
-            return web.json_response(
-                data={"error": f"Failed to parse command options for yt-dlp. '{err}'."},
-                status=web.HTTPBadRequest.status_code,
-            )
-
-    try:
-        key: str = cache.hash(f"{preset}:{url}:{cli_args or ''}")
-
-        if cache.has(key) and not request.query.get("force", False):
-            data: Any | None = cache.get(key)
-            if data is None:
-                data = {}
-            data["_cached"] = {
-                "status": "hit",
-                "preset": preset,
-                "cli_args": cli_args,
-                "key": key,
-                "ttl": data.get("_cached", {}).get("ttl", 300),
-                "ttl_left": data.get("_cached", {}).get("expires", time.time() + 300) - time.time(),
-                "expires": data.get("_cached", {}).get("expires", time.time() + 300),
-            }
-            return web.json_response(text=json.dumps(data, indent=4, default=str), status=web.HTTPOk.status_code)
-
-        ytdlp_opts: dict = opts.get_all()
-
-        (data, logs) = await fetch_info(
-            config=ytdlp_opts,
-            url=url,
-            debug=False,
-            no_archive=True,
-            follow_redirect=True,
-            sanitize_info=True,
-            capture_logs=logging.WARNING,
-        )
-
-        if not data or not isinstance(data, dict):
-            return web.json_response(
-                data={
-                    "status": False,
-                    "error": f"Failed to extract video info. {'. '.join(logs)}",
-                    "message": "Failed to extract video info.",
-                },
-                status=web.HTTPInternalServerError.status_code,
-            )
-
-        if data and "formats" in data:
-            from yt_dlp.cookies import LenientSimpleCookie
-
-            for index, item in enumerate(data["formats"]):
-                if "cookies" in item and len(item["cookies"]) > 0:
-                    cookies: list[str] = [f"{c.key}={c.value}" for c in LenientSimpleCookie(item["cookies"]).values()]
-                    if len(cookies) > 0:
-                        data["formats"][index]["h_cookies"] = "; ".join(cookies)
-                        data["formats"][index]["h_cookies"] = data["formats"][index]["h_cookies"].strip()
-
-        data["_cached"] = {
-            "status": "miss",
-            "preset": preset,
-            "cli_args": cli_args,
-            "key": key,
-            "ttl": 300,
-            "ttl_left": 300,
-            "expires": time.time() + 300,
-        }
-
-        data["is_archived"] = False
-
-        archive_file: str | None = ytdlp_opts.get("download_archive")
-        data["archive_file"] = archive_file or None
-
-        if archive_file and (archive_id := get_archive_id(url=url).get("archive_id")):
-            data["archive_id"] = archive_id
-            data["is_archived"] = len(archive_read(archive_file, [archive_id])) > 0
-
-        data = OrderedDict(sorted(data.items(), key=lambda item: len(str(item[1]))))
-
-        cache.set(key=key, value=data, ttl=300)
-
-        return web.json_response(text=json.dumps(data, indent=4, default=str), status=web.HTTPOk.status_code)
-    except Exception as e:
-        LOG.exception(
-            "Failed to get video info for '%s': %s.",
-            url,
-            e,
-            extra={
-                "route": "api/yt-dlp/url/info/",
-                "action": "get_video_info",
-                "url": url,
-                "preset": preset,
-                "cache_key": key if "key" in locals() else None,
-                "has_cli_args": bool(cli_args),
-            },
-        )
-        return web.json_response(
-            data={
-                "error": "failed to get video info.",
-                "message": str(e),
-                "formats": [],
-            },
-            status=web.HTTPInternalServerError.status_code,
-        )
-
-
-@route("GET", "api/yt-dlp/options/", "get_options")
-async def get_options() -> Response:
-    """
-    Get the yt-dlp CLI options.
-
-    Returns:
-        Response: The response object with the yt-dlp CLI options.
-
-    """
-    from app.features.ytdlp.ytdlp import ytdlp_options
-
-    return web.json_response(text=json.dumps(ytdlp_options(), indent=4, default=str), status=web.HTTPOk.status_code)
-
-
-@route("POST", "api/yt-dlp/archive_id/", "get_archive_ids")
-async def get_archive_ids(request: Request, config: Config) -> Response:
-    """
-    Get the archive IDs for the given URLs.
-
-    Returns:
-        Response: The response object with the yt-dlp CLI options.
-
-    """
-    data = (await request.json()) if request.body_exists else None
-    if not data or not isinstance(data, list):
-        return web.json_response(
-            data={"error": "Invalid request. expecting list with URLs."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    response = []
-
-    for i, url in enumerate(data):
-        dct: dict[str, Any] = {"index": i, "url": url}
-        if not isinstance(url, str):
-            dct.update({"id": None, "ie_key": None, "archive_id": None, "error": "URL must be a string."})
-            response.append(dct)
-            continue
-        try:
-            await asyncio.to_thread(validate_url, url, config.allow_internal_urls)
-            dct.update(get_archive_id(url))
-        except ValueError as e:
-            dct.update({"id": None, "ie_key": None, "archive_id": None, "error": str(e)})
-
-        response.append(dct)
-
-    return web.json_response(data=response, status=web.HTTPOk.status_code)
-
-
-@route("POST", "api/yt-dlp/command/", "make_command")
-async def make_command(request: Request, config: Config, encoder: Encoder) -> Response:
-    """
-    Build yt-dlp CLI command.
-
-    Args:
-        request (Request): The request object.
-        config (Config): The config instance.
-        encoder (Encoder): The encoder instance.
-
-    Returns:
-        Response: The response object with the merged fields and final yt-dlp CLI command string.
-
-    """
-    if not config.console_enabled:
-        return web.json_response(data={"error": "Console is disabled."}, status=web.HTTPForbidden.status_code)
-
-    data = (await request.json()) if request.body_exists else None
-    if not data or not isinstance(data, dict):
-        return web.json_response(
-            data={"error": "Invalid request. expecting JSON body."},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    try:
-        it = Item.format(data)
-    except ValueError as e:
-        return web.json_response(data={"error": str(e), "data": data}, status=web.HTTPBadRequest.status_code)
-
-    try:
-        command, info = YTDLPCli(item=it, config=config).build()
-    except Exception as e:
-        LOG.exception(
-            "Failed to build yt-dlp command for '%s': %s.",
-            it.url,
-            e,
-            extra={
-                "route": "api/yt-dlp/command/",
-                "action": "build_command",
-                "url": it.url,
-                "preset": it.preset,
-                "has_cookies": bool(it.cookies),
-                "exception_type": type(e).__name__,
-            },
-        )
-        return web.json_response(
-            data={"error": "Failed to build CLI command"},
-            status=web.HTTPBadRequest.status_code,
-        )
-
-    if request.query.get("full", False):
-        return web.json_response(data=info, status=web.HTTPOk.status_code, dumps=encoder.encode)
-
-    return web.json_response(data={"command": command}, status=web.HTTPOk.status_code)

app/features/ytdlp/tests/test_ytdlp_extractor.py

@@ -1,232 +0,0 @@
-import logging
-import pickle
-from unittest.mock import MagicMock, patch
-
-from app.features.ytdlp.extractor import (
-    ExtractorConfig,
-    ExtractorPool,
-    REEXTRACT_INFO_KEY,
-    _LogCapture,
-    _get_process_pool_kwargs,
-    _process_safe_info,
-    _ytdlp_logger,
-    extract_info_sync,
-)
-from app.features.ytdlp.utils import LogWrapper
-
-
-class TestProcessPoolConfiguration:
-    def setup_method(self):
-        ExtractorPool._reset_singleton()
-
-    def test_uses_fork_context_for_frozen_linux(self, monkeypatch):
-        monkeypatch.setattr("app.features.ytdlp.extractor.sys.platform", "linux")
-        monkeypatch.setattr("app.features.ytdlp.extractor.sys.frozen", True, raising=False)
-
-        context = object()
-        get_context = MagicMock(return_value=context)
-        monkeypatch.setattr("app.features.ytdlp.extractor.multiprocessing.get_context", get_context)
-
-        kwargs = _get_process_pool_kwargs()
-
-        assert kwargs == {"mp_context": context}
-        get_context.assert_called_once_with("fork")
-
-    def test_default_context_linux(self, monkeypatch):
-        monkeypatch.setattr("app.features.ytdlp.extractor.sys.platform", "linux")
-        monkeypatch.delattr("app.features.ytdlp.extractor.sys.frozen", raising=False)
-
-        get_context = MagicMock()
-        monkeypatch.setattr("app.features.ytdlp.extractor.multiprocessing.get_context", get_context)
-
-        assert _get_process_pool_kwargs() == {}
-        get_context.assert_not_called()
-
-    def test_init_pool_kwargs(self, monkeypatch):
-        context = object()
-        monkeypatch.setattr("app.features.ytdlp.extractor._get_process_pool_kwargs", lambda: {"mp_context": context})
-
-        executor = MagicMock()
-        executor_cls = MagicMock(return_value=executor)
-        monkeypatch.setattr("app.features.ytdlp.extractor.ProcessPoolExecutor", executor_cls)
-
-        pool = ExtractorPool.get_instance()
-        pool._ensure_initialized(ExtractorConfig(concurrency=3))
-
-        executor_cls.assert_called_once_with(max_workers=3, mp_context=context)
-        assert pool.get_pool(ExtractorConfig(concurrency=3)) is executor
-
-
-class TestExtractInfo:
-    """Test the extract_info function."""
-
-    @patch("app.features.ytdlp.extractor.YTDLP")
-    def test_extract_info_basic(self, mock_ytdlp_class):
-        """Test basic extract_info functionality."""
-        mock_ytdlp = MagicMock()
-        mock_ytdlp.extract_info.return_value = {"title": "Test Video", "id": "test123"}
-        mock_ytdlp_class.return_value = mock_ytdlp
-
-        config = {"quiet": True}
-        url = "https://example.com/video"
-
-        (result, logs) = extract_info_sync(config, url)
-        assert isinstance(result, dict), "Result should be a dictionary"
-        assert isinstance(logs, list), "Logs should be a list"
-        mock_ytdlp.extract_info.assert_called_once()
-
-    @patch("app.features.ytdlp.extractor.YTDLP")
-    def test_extract_info_with_debug(self, mock_ytdlp_class):
-        """Test extract_info with debug enabled."""
-        mock_ytdlp = MagicMock()
-        mock_ytdlp.extract_info.return_value = {"title": "Test Video"}
-        mock_ytdlp_class.return_value = mock_ytdlp
-
-        config = {}
-        url = "https://example.com/video"
-
-        (result, logs) = extract_info_sync(config, url, debug=True)
-        assert isinstance(result, dict), "Result should be a dictionary"
-        assert isinstance(logs, list), "Logs should be a list"
-
-    @patch("app.features.ytdlp.extractor.YTDLP")
-    def test_extract_info_mirrors_debug_to_console(self, mock_ytdlp_class):
-        seen: list[tuple[int, str]] = []
-
-        def fake_extract_info(url, download=False):  # noqa: ARG001
-            logger = mock_ytdlp_class.call_args.kwargs["params"]["logger"]
-            logger.debug("[generic_browser] Using remote browser for https://example.com/video")
-            logger.debug("[debug] [generic_browser] Loading page https://example.com/video")
-            logger.warning("[generic_browser] Browser fallback warning")
-            return {"title": "Test Video", "id": "test123"}
-
-        mock_ytdlp = MagicMock()
-        mock_ytdlp.extract_info.side_effect = fake_extract_info
-        mock_ytdlp_class.return_value = mock_ytdlp
-
-        logger = logging.getLogger("yt-dlp.extract_info")
-        with patch.object(
-            logger, "info", side_effect=lambda msg, *a, **k: seen.append((logging.INFO, msg % a if a else msg))
-        ):
-            with patch.object(
-                logger,
-                "debug",
-                side_effect=lambda msg, *a, **k: seen.append((logging.DEBUG, msg % a if a else msg)),
-            ):
-                with patch.object(
-                    logger,
-                    "log",
-                    side_effect=lambda level, msg, *a, **k: seen.append((level, msg % a if a else msg)),
-                ):
-                    (result, logs) = extract_info_sync(
-                        {}, "https://example.com/video", debug=True, capture_logs=logging.WARNING
-                    )
-
-        assert result is not None
-        assert result["id"] == "test123"
-        assert logs == ["[generic_browser] Browser fallback warning"]
-        assert (logging.INFO, "[generic_browser] Using remote browser for https://example.com/video") in seen
-        assert (logging.DEBUG, "[generic_browser] Loading page https://example.com/video") in seen
-        assert (logging.WARNING, "[generic_browser] Browser fallback warning") in seen
-
-    @patch("app.features.ytdlp.extractor.YTDLP")
-    def test_extract_info_mirrors_screen_logs_without_debug(self, mock_ytdlp_class):
-        seen: list[tuple[int, str]] = []
-
-        def fake_extract_info(url, download=False):  # noqa: ARG001
-            logger = mock_ytdlp_class.call_args.kwargs["params"]["logger"]
-            logger.debug("[generic_browser] Using remote browser for https://example.com/video")
-            logger.warning("[generic_browser] Browser fallback warning")
-            return {"title": "Test Video", "id": "test123"}
-
-        mock_ytdlp = MagicMock()
-        mock_ytdlp.extract_info.side_effect = fake_extract_info
-        mock_ytdlp_class.return_value = mock_ytdlp
-
-        logger = logging.getLogger("yt-dlp.extract_info")
-        with patch.object(
-            logger, "info", side_effect=lambda msg, *a, **k: seen.append((logging.INFO, msg % a if a else msg))
-        ):
-            with patch.object(
-                logger,
-                "log",
-                side_effect=lambda level, msg, *a, **k: seen.append((level, msg % a if a else msg)),
-            ):
-                (result, logs) = extract_info_sync(
-                    {}, "https://example.com/video", debug=False, capture_logs=logging.WARNING
-                )
-
-        assert result is not None
-        assert result["id"] == "test123"
-        assert logs == ["[generic_browser] Browser fallback warning"]
-        assert (logging.INFO, "[generic_browser] Using remote browser for https://example.com/video") in seen
-        assert (logging.WARNING, "[generic_browser] Browser fallback warning") in seen
-
-    def test_process_safe_live(self) -> None:
-        data = {
-            "id": "live-id",
-            "is_live": True,
-            "formats": [{"format_id": "dash", "fragments": ({"url": "https://example.test/sq/1"} for _ in range(1))}],
-            "requested_formats": [{"format_id": "dash"}],
-        }
-
-        result = _process_safe_info(data)
-
-        assert result[REEXTRACT_INFO_KEY] is True
-        assert "formats" not in result
-        assert "requested_formats" not in result
-        pickle.dumps(result)
-
-    def test_process_safe_post_live(self) -> None:
-        data = {
-            "id": "post-live-id",
-            "live_status": "post_live",
-            "formats": [{"format_id": "dash", "fragments": ({"url": "https://example.test/sq/1"} for _ in range(1))}],
-        }
-
-        result = _process_safe_info(data)
-
-        assert result[REEXTRACT_INFO_KEY] is True
-        assert "formats" not in result
-        pickle.dumps(result)
-
-    def test_process_safe_lazy(self) -> None:
-        from yt_dlp.utils import LazyList
-
-        data = {"id": "video-id", "formats": LazyList({"format_id": str(i)} for i in range(2))}
-
-        result = _process_safe_info(data)
-
-        assert result["formats"] == [{"format_id": "0"}, {"format_id": "1"}]
-        pickle.dumps(result)
-
-
-class TestYtdlpLogger:
-    def test_debug_prefix_uses_debug(self) -> None:
-        logger = MagicMock()
-
-        _ytdlp_logger(logger)(logging.DEBUG, "[debug] hello")
-
-        logger.debug.assert_called_once_with("hello", stacklevel=4)
-
-    def test_screen_style_debug_uses_info(self) -> None:
-        logger = MagicMock()
-
-        _ytdlp_logger(logger)(logging.DEBUG, "screen line")
-
-        logger.info.assert_called_once_with("screen line", stacklevel=4)
-
-    def test_targets_are_picklable(self) -> None:
-        logs: list[str] = []
-        wrapper = LogWrapper()
-        wrapper.add_target(_ytdlp_logger(logging.getLogger("yt-dlp.test")), level=logging.DEBUG, name="yt-dlp.test")
-        wrapper.add_target(_LogCapture(logs), level=logging.WARNING, name="log-capture")
-
-        pickle.dumps(wrapper)
-
-    def test_capture_formats_args(self) -> None:
-        logs: list[str] = []
-
-        _LogCapture(logs)(logging.WARNING, "hello %s", "world")
-
-        assert logs == ["hello world"]

app/features/ytdlp/tests/test_ytdlp_module.py

@@ -1,465 +0,0 @@
-import importlib
-from pathlib import Path
-from typing import Any
-from unittest.mock import MagicMock, Mock, patch
-
-import pytest
-from yt_dlp.globals import extractors as ytdlp_extractors
-
-from app.features.ytdlp.outtmpl import rewrite_outtmpl
-from app.features.ytdlp.patches import patch_windows_popen_wait
-from app.features.ytdlp.utils import _DATA
-from app.features.ytdlp.ytdlp import YTDLP, _ArchiveProxy, ytdlp_options
-
-
-def _archive_path(tmp_path: Path) -> str:
-    return str(tmp_path / "archive.txt")
-
-
-class TestArchiveProxy:
-    def test_bool_and_falsey_cases(self, tmp_path: Path) -> None:
-        # No file path means proxy is falsey and operations return False
-        p = _ArchiveProxy(file=None)
-        assert bool(p) is False
-        assert ("id" in p) is False
-        assert p.add("id") is False
-
-        # Empty item also returns False
-        p2 = _ArchiveProxy(file=_archive_path(tmp_path))
-        assert bool(p2) is True
-        assert ("" in p2) is False
-        assert p2.add("") is False
-
-    @patch("app.features.ytdlp.archiver.Archiver.get_instance")
-    def test_delegates_to_archiver(self, mock_get_instance, tmp_path: Path) -> None:
-        arch = MagicMock()
-        mock_get_instance.return_value = arch
-
-        file = _archive_path(tmp_path)
-
-        p = _ArchiveProxy(file=file)
-
-        # contains -> read(file, [item]) and check membership
-        arch.read.return_value = ["abc"]
-        assert ("abc" in p) is True
-        arch.read.assert_called_with(file, ["abc"])
-
-        arch.read.return_value = []
-        assert ("xyz" in p) is False
-
-        # add -> add(file, [item]) returns boolean
-        arch.add.return_value = True
-        assert p.add("abc") is True
-        arch.add.assert_called_with(file, ["abc"])
-
-        arch.add.return_value = False
-        assert p.add("xyz") is False
-
-
-class TestYtDlpOptions:
-    def test_options_shape(self) -> None:
-        opts = ytdlp_options()
-
-        assert isinstance(opts, list)
-        assert len(opts) > 0
-
-        # Every entry should have required keys
-        for o in opts:
-            assert {"flags", "description", "group", "ignored"} <= set(o.keys())
-            assert isinstance(o["flags"], list)
-            assert len(o["flags"]) > 0
-            # Ensure SUPPRESSHELP has been normalized away
-            if isinstance(o.get("description"), str):
-                assert "SUPPRESSHELP" not in o["description"]
-
-    def test_ignored_flags_match_remove_keys(self) -> None:
-        # Collect the flags that should be ignored from REMOVE_KEYS
-        ignored_flags: set[str] = {
-            f.strip() for group in _DATA.REMOVE_KEYS for v in group.values() for f in v.split(",") if f.strip()
-        }
-
-        opts = ytdlp_options()
-
-        # Map flag -> ignored value as reported by our function (first match wins)
-        flag_to_ignored: dict[str, bool] = {}
-        for o in opts:
-            for f in o["flags"]:
-                if f not in flag_to_ignored:
-                    flag_to_ignored[f] = bool(o["ignored"])  # normalize to bool
-
-        # For any ignored flag that actually exists in yt-dlp parser, ensure it is marked ignored
-        present_ignored_flags = [f for f in ignored_flags if f in flag_to_ignored]
-        assert len(present_ignored_flags) > 0, "We expect at least one to be present (e.g., -P / --paths, etc.)"
-        assert all(flag_to_ignored[f] is True for f in present_ignored_flags)
-
-
-class TestYTDLP:
-    """Test the YTDLP class overridden methods."""
-
-    def _create_ytdlp(self, params=None):
-        """Helper to create a YTDLP instance with mocked parent __init__."""
-        with patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL.__init__", return_value=None):
-            ytdlp = YTDLP(params=params)
-            ytdlp.params = params or {}
-            return ytdlp
-
-    @patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL.__init__")
-    def test_init_archive_param(self, mock_super_init, tmp_path: Path) -> None:
-        """Test that __init__ removes download_archive before calling super, then restores it."""
-        mock_super_init.return_value = None
-
-        file = _archive_path(tmp_path)
-        params = {"download_archive": file, "quiet": True}
-
-        ytdlp = YTDLP(params=params, auto_init=True)
-        # Set params as it would be after super().__init__
-        ytdlp.params = {}
-
-        # Verify super().__init__ was called without download_archive
-        mock_super_init.assert_called_once()
-        call_kwargs = mock_super_init.call_args[1]
-        assert "download_archive" not in call_kwargs["params"]
-        assert call_kwargs["params"]["quiet"] is True
-        assert call_kwargs["auto_init"] is True
-
-        # Our __init__ code manually sets these after super()
-        ytdlp.params["download_archive"] = file
-
-        assert ytdlp.params["download_archive"] == file, "Verify download_archive was restored to params"
-
-        # Verify archive proxy was set up
-        assert isinstance(ytdlp.archive, _ArchiveProxy)
-        assert ytdlp.archive._file == file
-
-    @patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL.__init__")
-    def test_init_no_archive(self, mock_super_init) -> None:
-        """Test __init__ works correctly when download_archive is not in params."""
-        mock_super_init.return_value = None
-
-        params = {"quiet": True}
-
-        ytdlp = YTDLP(params=params, auto_init=False)
-
-        # Verify super().__init__ was called with original params
-        mock_super_init.assert_called_once()
-        call_kwargs = mock_super_init.call_args[1]
-        assert call_kwargs["params"]["quiet"] is True
-        assert call_kwargs["auto_init"] is False
-
-        assert isinstance(ytdlp.archive, _ArchiveProxy), "Verify archive proxy is falsey"
-        assert not ytdlp.archive
-
-    @patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL.__init__")
-    def test_init_none_params(self, mock_super_init) -> None:
-        """Test __init__ handles None params gracefully."""
-        mock_super_init.return_value = None
-
-        ytdlp = YTDLP(params=None)
-
-        mock_super_init.assert_called_once_with(params=None, auto_init=True)
-        assert isinstance(ytdlp.archive, _ArchiveProxy)
-        assert not ytdlp.archive
-
-    @patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL.__init__")
-    def test_init_patches_wait(self, mock_super_init) -> None:
-        mock_super_init.return_value = None
-
-        class FakePopen:
-            def wait(self, timeout=None):
-                return timeout
-
-        with patch("app.features.ytdlp.patches.sys.platform", "win32"):
-            with patch("yt_dlp.utils.Popen", FakePopen):
-                YTDLP(params={})
-
-        assert getattr(FakePopen, "_ytptube_wait_patched", False) is True
-
-    def test_wait_patch_polls(self) -> None:
-        calls: list[float | None] = []
-
-        class FakePopen:
-            _ytptube_wait_patched = False
-
-            def wait(self, timeout=None):
-                calls.append(timeout)
-                if len(calls) < 3:
-                    raise TimeoutError
-                return 0
-
-        with patch("app.features.ytdlp.patches.sys.platform", "win32"):
-            with (
-                patch("yt_dlp.utils.Popen", FakePopen),
-                patch("app.features.ytdlp.patches.subprocess.TimeoutExpired", TimeoutError),
-            ):
-                patch_windows_popen_wait()
-                result = FakePopen().wait()
-
-        assert result == 0
-        assert calls == [0.1, 0.1, 0.1]
-
-    def test_wait_patch_timeout(self) -> None:
-        calls: list[float | None] = []
-
-        class FakePopen:
-            _ytptube_wait_patched = False
-
-            def wait(self, timeout=None):
-                calls.append(timeout)
-                return 0
-
-        with patch("app.features.ytdlp.patches.sys.platform", "win32"):
-            with patch("yt_dlp.utils.Popen", FakePopen):
-                patch_windows_popen_wait()
-                result = FakePopen().wait(timeout=5)
-
-        assert result == 0
-        assert calls == [5]
-
-    @patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL._delete_downloaded_files")
-    def test_delete_interrupted(self, mock_super_delete) -> None:
-        """Test _delete_downloaded_files skips cleanup when _interrupted is True."""
-        with patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL.__init__", return_value=None):
-            ytdlp = YTDLP(params={})
-            mock_obj: Any = ytdlp
-            mock_obj.to_screen = Mock()
-
-            # Set interrupted flag
-            ytdlp._interrupted = True
-
-            result = ytdlp._delete_downloaded_files("arg1", "arg2", kwarg1="value1")
-
-            # Should not call super method
-            mock_super_delete.assert_not_called()
-            # Should show message
-            mock_obj.to_screen.assert_called_once_with("[info] Cancelled — skipping temp cleanup.")
-            # Should return None
-            assert result is None
-
-    @patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL._delete_downloaded_files")
-    def test_delete_calls_super(self, mock_super_delete) -> None:
-        """Test _delete_downloaded_files calls super when not interrupted."""
-        mock_super_delete.return_value = "cleanup_result"
-
-        with patch("app.features.ytdlp.ytdlp.yt_dlp.YoutubeDL.__init__", return_value=None):
-            ytdlp = YTDLP(params={})
-            ytdlp._interrupted = False
-
-            result = ytdlp._delete_downloaded_files("arg1", kwarg1="value1")
-
-            # Should call super method with same args
-            mock_super_delete.assert_called_once_with("arg1", kwarg1="value1")
-            # Should return super's result
-            assert result == "cleanup_result"
-
-    def test_record_archive_missing(self) -> None:
-        """Test record_download_archive returns early when download_archive is not set."""
-        ytdlp = self._create_ytdlp(params={})
-        ytdlp.archive = Mock()
-
-        ytdlp.record_download_archive({"id": "test123"})
-
-        # Should not interact with archive
-        ytdlp.archive.add.assert_not_called()
-
-    def test_record_archive_adds_id(self, tmp_path: Path) -> None:
-        """Test record_download_archive adds the archive ID."""
-        ytdlp = self._create_ytdlp(params={"download_archive": _archive_path(tmp_path)})
-        ytdlp.write_debug = Mock()
-        ytdlp.archive = Mock()
-        ytdlp._make_archive_id = Mock(return_value="youtube test123")
-
-        info_dict = {"id": "test123", "ie_key": "Youtube"}
-
-        ytdlp.record_download_archive(info_dict)
-
-        # Verify _make_archive_id was called
-        ytdlp._make_archive_id.assert_called_once_with(info_dict)
-
-        # Verify archive.add was called with the archive_id
-        ytdlp.archive.add.assert_called_once_with("youtube test123")
-        ytdlp.write_debug.assert_called_with("Adding to archive: youtube test123")
-
-    def test_record_archive_old_ids(self, tmp_path: Path) -> None:
-        """Test record_download_archive adds _old_archive_ids when present."""
-        ytdlp = self._create_ytdlp(params={"download_archive": _archive_path(tmp_path)})
-        ytdlp.write_debug = Mock()
-        ytdlp.archive = Mock()
-        ytdlp._make_archive_id = Mock(return_value="youtube new123")
-
-        info_dict = {
-            "id": "new123",
-            "ie_key": "Youtube",
-            "_old_archive_ids": ["youtube old123", "youtube old456", "youtube new123"],
-        }
-
-        ytdlp.record_download_archive(info_dict)
-
-        # Should add main archive_id
-        assert ytdlp.archive.add.call_count == 3
-        calls = [call[0][0] for call in ytdlp.archive.add.call_args_list]
-
-        assert calls[0] == "youtube new123", "First call is main archive_id"
-
-        # Should add old IDs except the duplicate
-        assert "youtube old123" in calls
-        assert "youtube old456" in calls
-        # Should not add duplicate (youtube new123 appears only once)
-        assert calls.count("youtube new123") == 1
-
-    def test_record_archive_empty_old_ids(self, tmp_path: Path) -> None:
-        """Test record_download_archive handles empty or invalid _old_archive_ids."""
-        ytdlp = self._create_ytdlp(params={"download_archive": _archive_path(tmp_path)})
-        ytdlp.write_debug = Mock()
-        ytdlp.archive = Mock()
-        ytdlp._make_archive_id = Mock(return_value="youtube test123")
-
-        # Test with empty list
-        info_dict = {"id": "test123", "ie_key": "Youtube", "_old_archive_ids": []}
-        ytdlp.record_download_archive(info_dict)
-        assert ytdlp.archive.add.call_count == 1  # Only main ID
-
-        ytdlp.archive.reset_mock()
-
-        # Test with None
-        info_dict = {"id": "test123", "ie_key": "Youtube", "_old_archive_ids": None}
-        ytdlp.record_download_archive(info_dict)
-        assert ytdlp.archive.add.call_count == 1  # Only main ID
-
-        ytdlp.archive.reset_mock()
-
-        # Test with non-list value
-        info_dict = {"id": "test123", "ie_key": "Youtube", "_old_archive_ids": "not a list"}
-        ytdlp.record_download_archive(info_dict)
-        assert ytdlp.archive.add.call_count == 1  # Only main ID
-
-    def test_record_archive_empty_id(self, tmp_path: Path) -> None:
-        """Test record_download_archive returns early when _make_archive_id returns empty."""
-        ytdlp = self._create_ytdlp(params={"download_archive": _archive_path(tmp_path)})
-        ytdlp.archive = Mock()
-        ytdlp._make_archive_id = Mock(return_value=None)
-
-        ytdlp.record_download_archive({"id": "test123"})
-
-        # Should not add anything
-        ytdlp.archive.add.assert_not_called()
-
-    def test_outtmpl_callable(self) -> None:
-        ytdlp = YTDLP(params={"outtmpl": {"default": "%(title)s"}})
-
-        result = ytdlp.evaluate_outtmpl("%(ytp_random:8)s", {"title": "x"})
-
-        assert len(result) == 8
-        assert result.isalnum()
-
-    def test_exec_init(self) -> None:
-        YTDLP(
-            params={
-                "compat_opts": set(),
-                "postprocessors": [{"key": "Exec", "exec_cmd": "echo %(title)q"}],
-            }
-        )
-
-    def test_outtmpl_reuses_value(self) -> None:
-        ytdlp = YTDLP(params={"outtmpl": {"default": "%(title)s"}})
-
-        result = ytdlp.evaluate_outtmpl("%(ytp_random:8)s/%(ytp_random:8)s", {"title": "x"})
-        first, second = result.split("/")
-
-        assert first == second
-
-    def test_outtmpl_new_value(self) -> None:
-        ytdlp = YTDLP(params={"outtmpl": {"default": "%(title)s"}})
-
-        first = ytdlp.evaluate_outtmpl("%(ytp_random:8)s", {"title": "x"})
-        second = ytdlp.evaluate_outtmpl("%(ytp_random:8)s", {"title": "y"})
-
-        assert first != second
-
-    def test_prepare_filename_sidecars(self) -> None:
-        ytdlp = YTDLP(
-            params={
-                "outtmpl": {
-                    "default": "%(ytp_random:6)s.%(ext)s",
-                    "thumbnail": "%(ytp_random:6)s.%(ext)s",
-                    "subtitle": "%(ytp_random:6)s.%(ext)s",
-                    "infojson": "%(ytp_random:6)s.%(ext)s",
-                }
-            }
-        )
-
-        info = {"id": "abc123", "title": "Example", "ext": "mp4"}
-
-        default_name = ytdlp.prepare_filename(info)
-        thumbnail_name = ytdlp.prepare_filename(info, "thumbnail")
-        subtitle_name = ytdlp.prepare_filename(info, "subtitle")
-        infojson_name = ytdlp.prepare_filename(info, "infojson")
-
-        default_base = default_name.rsplit(".", 1)[0]
-        thumbnail_base = thumbnail_name.rsplit(".", 1)[0]
-        subtitle_base = subtitle_name.rsplit(".", 1)[0]
-        infojson_base = infojson_name.removesuffix(".info.json")
-
-        assert default_base == thumbnail_base
-        assert default_base == subtitle_base
-        assert default_base == infojson_base
-
-    def test_prepare_filename_resets(self) -> None:
-        ytdlp = YTDLP(params={"outtmpl": {"default": "%(ytp_random:8)s.%(ext)s"}})
-
-        first = ytdlp.prepare_filename({"id": "one", "title": "One", "ext": "mp4"})
-        second = ytdlp.prepare_filename({"id": "two", "title": "Two", "ext": "mp4"})
-
-        assert first != second
-
-    @pytest.mark.parametrize(
-        ("template", "expected"),
-        [
-            ("%(ytp_random:8|fallback)s", 8),
-            ("%(ytp_random:8&{} - |)s", 11),
-            ("%(ytp_random:8)S", 8),
-        ],
-    )
-    def test_outtmpl_suffix(self, template: str, expected: int) -> None:
-        ytdlp = YTDLP(
-            params={
-                "outtmpl": {"default": "%(title)s"},
-                "restrictfilenames": True,
-            },
-        )
-
-        result = ytdlp.evaluate_outtmpl(template, {"title": "x"})
-
-        assert len(result) == expected
-
-    def test_outtmpl_modes(self) -> None:
-        ytdlp = YTDLP(params={"outtmpl": {"default": "%(title)s"}})
-
-        digits = ytdlp.evaluate_outtmpl("%(ytp_random:6:d)s", {"title": "x"})
-        letters = ytdlp.evaluate_outtmpl("%(ytp_random:6:s)s", {"title": "x"})
-
-        assert digits.isdigit()
-        assert letters.isalpha()
-
-    def test_outtmpl_unknown_callable(self) -> None:
-        ytdlp = YTDLP(params={"outtmpl": {"default": "%(title)s"}})
-
-        with pytest.raises(ValueError, match="Unsupported YTPTube output template callable"):
-            ytdlp.prepare_outtmpl("%(ytp_unknown:8)s", {"title": "x"})
-
-    def test_outtmpl_invalid_length(self) -> None:
-        ytdlp = YTDLP(params={"outtmpl": {"default": "%(title)s"}})
-
-        with pytest.raises(ValueError, match="ytp_random length must be an integer"):
-            ytdlp.prepare_outtmpl("%(ytp_random:nope)s", {"title": "x"})
-
-
-class TestOuttmpl:
-    def test_rewrite_outtmpl_cache(self) -> None:
-        cache: dict[str, object] = {}
-        template = "%(ytp_random:8)s/%(ytp_random:8)s.%(ext)s"
-
-        rewritten, info = rewrite_outtmpl(template, {"ext": "mp4"}, cache=cache)
-
-        assert rewritten == "%(__ytptube_outtmpl_0)s/%(__ytptube_outtmpl_0)s.%(ext)s"
-        assert len(cache) == 1
-        assert info["__ytptube_outtmpl_0"] == next(iter(cache.values()))

app/features/ytdlp/tests/test_ytdlp_utils.py

@@ -1,592 +0,0 @@
-import logging
-from pathlib import Path
-import re
-from typing import Any
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from app.features.ytdlp.utils import (
-    LogWrapper,
-    extract_ytdlp_logs,
-    get_archive_id,
-    ytdlp_reject,
-    parse_outtmpl,
-    get_extras,
-    get_thumbnail,
-    get_ytdlp,
-    archive_delete,
-    archive_add,
-    archive_read,
-)
-from app.tests.helpers import make_test_temp_dir
-
-
-class CaptureHandler(logging.Handler):
-    def __init__(self) -> None:
-        super().__init__()
-        self.records: list[logging.LogRecord] = []
-
-    def emit(self, record: logging.LogRecord) -> None:
-        self.records.append(record)
-
-
-def make_logger(name: str = "lw_test") -> tuple[logging.Logger, CaptureHandler]:
-    logger = logging.getLogger(name)
-    logger.setLevel(logging.DEBUG)
-    handler = CaptureHandler()
-    # Avoid duplicate handlers when tests run multiple times
-    for h in list(logger.handlers):
-        logger.removeHandler(h)
-    logger.addHandler(handler)
-    return logger, handler
-
-
-class TestLogWrapper:
-    def test_add_target_type_validation(self) -> None:
-        lw = LogWrapper()
-        with pytest.raises(TypeError, match=r"Target must be a logging\.Logger instance or a callable"):
-            bad: Any = 123
-            lw.add_target(bad)
-
-    def test_add_target_names(self) -> None:
-        lw = LogWrapper()
-        logger, _ = make_logger("one")
-
-        # Name inferred from logger
-        lw.add_target(logger)
-        assert lw.targets[-1].name == "one"
-        assert lw.has_targets()
-
-        # Name inferred from callable
-        def sink(level: int, msg: str, *args: Any, **kwargs: Any) -> None:  # noqa: ARG001
-            return None
-
-        lw.add_target(sink)
-        assert lw.targets[-1].name == "sink"
-
-        # Custom name overrides
-        lw.add_target(logger, name="custom")
-        assert lw.targets[-1].name == "custom"
-
-    def test_level_filtering_and_dispatch(self) -> None:
-        lw = LogWrapper()
-        logger, cap = make_logger("cap")
-        calls: list[tuple[int, str, tuple, dict]] = []
-
-        def sink(level: int, msg: str, *args: Any, **kwargs: Any) -> None:
-            calls.append((level, msg, args, kwargs))
-
-        # Logger target at INFO, callable target at WARNING
-        lw.add_target(logger, level=logging.INFO)
-        lw.add_target(sink, level=logging.WARNING)
-
-        # DEBUG should hit none
-        lw.debug("d1")
-        assert len(cap.records) == 0
-        assert len(calls) == 0
-
-        # INFO hits logger only
-        lw.info("hello %s", "X")
-        assert len(cap.records) == 1
-        assert cap.records[0].levelno == logging.INFO
-        assert cap.records[0].getMessage() == "hello X"
-        assert cap.records[0].funcName == "test_level_filtering_and_dispatch"
-        assert len(calls) == 0
-
-        # WARNING hits both
-        lw.warning("warn %s", "Y", extra={"k": 1})
-        assert len(cap.records) == 2
-        assert cap.records[1].levelno == logging.WARNING
-        assert cap.records[1].getMessage() == "warn Y"
-        assert len(calls) == 1
-        lvl, msg, args, kwargs = calls[0]
-        assert lvl == logging.WARNING
-        assert msg == "warn %s"
-        assert args == ("Y",)
-        assert "extra" in kwargs
-        assert kwargs["extra"] == {"k": 1}
-
-        # ERROR still hits both; CRITICAL too
-        lw.error("err")
-        lw.critical("boom")
-        assert any(r.levelno == logging.ERROR for r in cap.records)
-        assert any(r.levelno == logging.CRITICAL for r in cap.records)
-        assert any(c[0] == logging.ERROR for c in calls)
-        assert any(c[0] == logging.CRITICAL for c in calls)
-
-
-class TestExtractYtdlpLogs:
-    """Test YTDLP log extraction function."""
-
-    def test_extract_ytdlp_logs_basic(self):
-        """Test basic log extraction."""
-        logs = ["This live event will begin soon", "ERROR: Failed", "WARNING: Deprecated"]
-        result = extract_ytdlp_logs(logs)
-        assert isinstance(result, list)
-        assert len(result) >= 1  # Should match "This live event will begin"
-
-    def test_extract_ytdlp_logs_with_filters(self):
-        """Test log extraction with filters."""
-        logs = ["INFO: Downloading", "ERROR: Failed", "WARNING: Deprecated"]
-        filters: list[str | re.Pattern[str]] = [re.compile(r"ERROR")]
-        result = extract_ytdlp_logs(logs, filters)
-        assert result == ["ERROR: Failed"]
-
-    def test_extract_ytdlp_logs_empty(self):
-        """Test with empty logs."""
-        result = extract_ytdlp_logs([])
-        assert result == []
-
-
-class TestYtdlpReject:
-    """Test the ytdlp_reject function."""
-
-    def test_ytdlp_reject_basic(self):
-        """Test basic rejection logic."""
-        entry = {"title": "Test Video", "view_count": 1000}
-        yt_params = {}
-
-        passed, message = ytdlp_reject(entry, yt_params)
-        assert passed is True
-        assert message == ""
-
-    def test_ytdlp_reject_with_filters(self):
-        """Test rejection with filters."""
-        entry = {"title": "Test Video", "upload_date": "20230101"}
-        yt_params = {"daterange": MagicMock()}
-
-        # Mock daterange to simulate rejection
-        yt_params["daterange"].__contains__ = MagicMock(return_value=False)
-
-        passed, message = ytdlp_reject(entry, yt_params)
-        assert passed is False
-        assert "20230101" in message
-        assert "not in range" in message
-
-
-class TestParseOuttmpl:
-    """Test the parse_outtmpl function."""
-
-    def setup_method(self):
-        """Reset YTDLP singleton state before each test."""
-        from app.features.ytdlp.utils import _DATA
-
-        _DATA.YTDLP_INFO_CLS = None
-
-    def test_parse_outtmpl_basic(self):
-        """Test basic template parsing with simple placeholders."""
-
-        template = "%(title)s.%(ext)s"
-        info_dict = {
-            "title": "Test Video",
-            "ext": "mp4",
-        }
-
-        result = parse_outtmpl(template, info_dict)
-
-        assert result == "Test Video.mp4"
-
-    def test_parse_outtmpl_with_id(self):
-        """Test template parsing with video ID."""
-
-        template = "[%(id)s] %(title)s.%(ext)s"
-        info_dict = {
-            "id": "dQw4w9WgXcQ",
-            "title": "Never Gonna Give You Up",
-            "ext": "webm",
-        }
-
-        result = parse_outtmpl(template, info_dict)
-
-        assert result == "[dQw4w9WgXcQ] Never Gonna Give You Up.webm"
-
-    def test_parse_outtmpl_with_uploader(self):
-        """Test template parsing with uploader information."""
-
-        template = "%(uploader)s - %(title)s.%(ext)s"
-        info_dict = {
-            "uploader": "Rick Astley",
-            "title": "Never Gonna Give You Up",
-            "ext": "mp4",
-        }
-
-        result = parse_outtmpl(template, info_dict)
-
-        assert result == "Rick Astley - Never Gonna Give You Up.mp4"
-
-    def test_parse_outtmpl_with_nested_path(self):
-        """Test template parsing with nested directory structure."""
-
-        template = "%(uploader)s/%(title)s.%(ext)s"
-        info_dict = {
-            "uploader": "Test Channel",
-            "title": "Test Video",
-            "ext": "mkv",
-        }
-
-        result = parse_outtmpl(template, info_dict)
-
-        assert result == "Test Channel/Test Video.mkv"
-
-    def test_parse_outtmpl_with_missing_field(self):
-        """Test template parsing with missing field defaults to NA."""
-
-        template = "%(title)s - %(upload_date)s.%(ext)s"
-        info_dict = {
-            "title": "Test Video",
-            "ext": "mp4",
-        }
-
-        result = parse_outtmpl(template, info_dict)
-
-        assert result == "Test Video - NA.mp4", "Missing field upload_date should default to NA"
-
-    def test_parse_outtmpl_complex(self):
-        """Test complex template with multiple fields."""
-
-        template = "%(uploader)s/%(playlist_title)s/%(playlist_index)03d - %(title)s [%(id)s].%(ext)s"
-        info_dict = {
-            "uploader": "Test Channel",
-            "playlist_title": "Best Videos",
-            "playlist_index": 5,
-            "title": "Amazing Content",
-            "id": "abc123xyz",
-            "ext": "mp4",
-        }
-
-        result = parse_outtmpl(template, info_dict)
-
-        assert result == "Test Channel/Best Videos/005 - Amazing Content [abc123xyz].mp4"
-
-    def test_parse_outtmpl_special_chars(self):
-        """Test template parsing handles special characters in values."""
-
-        template = "%(title)s.%(ext)s"
-        info_dict = {
-            "title": "Test: Video / With \\ Special | Characters",
-            "ext": "mp4",
-        }
-
-        result = parse_outtmpl(template, info_dict)
-
-        assert ".mp4" in result, "yt-dlp should sanitize special characters but preserve extension"
-        assert "Test" in result, "yt-dlp should preserve safe parts of title"
-
-    def test_parse_outtmpl_with_playlist_info(self):
-        """Test template parsing with playlist information."""
-
-        template = "%(playlist)s/%(title)s.%(ext)s"
-        info_dict = {
-            "playlist": "My Playlist",
-            "title": "Video Title",
-            "ext": "webm",
-        }
-
-        result = parse_outtmpl(template, info_dict)
-
-        assert result == "My Playlist/Video Title.webm"
-
-    def test_parse_outtmpl_restrict(self):
-        """Test template parsing with restrict_filename parameter."""
-
-        template = "%(uploader)s/%(title)s.%(ext)s"
-        info_dict = {
-            "uploader": "Foobar's Workshop",
-            "title": "Test Video",
-            "ext": "mp4",
-        }
-
-        result_unrestricted: str = parse_outtmpl(template, info_dict)
-        assert result_unrestricted == "Foobar's Workshop/Test Video.mp4"
-
-        result_restricted: str = parse_outtmpl(template, info_dict, params={"restrictfilenames": True})
-        assert result_restricted == "Foobar_s_Workshop/Test_Video.mp4"
-
-
-class TestGetThumbnail:
-    def test_empty_list(self):
-        """Test that None is returned for an empty thumbnail list."""
-
-        assert get_thumbnail([]) is None
-
-    def test_non_list(self):
-        """Test that None is returned for non-list input."""
-
-        bad_none: Any = None
-        bad_str: Any = "not a list"
-        bad_dict: Any = {"not": "list"}
-        assert get_thumbnail(bad_none) is None
-        assert get_thumbnail(bad_str) is None
-        assert get_thumbnail(bad_dict) is None
-
-    def test_thumbnail_preference(self):
-        """Test that the thumbnail with highest preference is returned."""
-
-        thumbnails = [
-            {"url": "low.jpg", "preference": 1, "width": 100, "height": 100},
-            {"url": "high.jpg", "preference": 10, "width": 200, "height": 200},
-            {"url": "medium.jpg", "preference": 5, "width": 150, "height": 150},
-        ]
-
-        result = get_thumbnail(thumbnails)
-        assert result == {"url": "high.jpg", "preference": 10, "width": 200, "height": 200}
-
-    def test_thumbnail_width(self):
-        """Test that the thumbnail with highest width is returned when preference is equal."""
-
-        thumbnails = [
-            {"url": "small.jpg", "preference": 1, "width": 100, "height": 100},
-            {"url": "large.jpg", "preference": 1, "width": 200, "height": 200},
-            {"url": "medium.jpg", "preference": 1, "width": 150, "height": 150},
-        ]
-
-        result = get_thumbnail(thumbnails)
-        assert result == {"url": "large.jpg", "preference": 1, "width": 200, "height": 200}
-
-    def test_missing_attrs(self):
-        """Test that thumbnails with missing attributes are handled correctly."""
-
-        thumbnails = [
-            {"url": "no_pref.jpg", "width": 100},
-            {"url": "with_pref.jpg", "preference": 5, "width": 50},
-        ]
-
-        result = get_thumbnail(thumbnails)
-        assert result is not None
-        assert result["url"] == "with_pref.jpg"
-
-    def test_all_equal(self):
-        """Test that any thumbnail is returned when all attributes are equal."""
-
-        thumbnails = [
-            {"url": "first.jpg"},
-            {"url": "second.jpg"},
-        ]
-
-        assert get_thumbnail(thumbnails) == {"url": "second.jpg"}
-
-
-class TestGetExtras:
-    def test_none(self):
-        """Test that empty dict is returned for None input."""
-        bad: Any = None
-        assert get_extras(bad) == {}
-
-    def test_non_dict(self):
-        """Test that empty dict is returned for non-dict input."""
-        bad_str: Any = "not a dict"
-        bad_list: Any = []
-        assert get_extras(bad_str) == {}
-        assert get_extras(bad_list) == {}
-
-    def test_extracts_video_information(self):
-        """Test extracting information from a video entry."""
-
-        entry = {
-            "id": "test123",
-            "title": "Test Video",
-            "uploader": "Test Uploader",
-            "channel": "Test Channel",
-            "thumbnails": [{"url": "thumb.jpg", "preference": 1}],
-            "duration": 120,
-        }
-
-        result = get_extras(entry, kind="video")
-
-        assert result["uploader"] == "Test Uploader"
-        assert result["channel"] == "Test Channel"
-        assert result["thumbnail"] == "thumb.jpg"
-        assert result["duration"] == 120
-        assert result["is_premiere"] is False
-
-    def test_extracts_playlist_information(self):
-        """Test extracting information from a playlist entry."""
-
-        entry = {
-            "id": "playlist123",
-            "title": "Test Playlist",
-            "uploader": "Playlist Owner",
-            "uploader_id": "owner123",
-        }
-
-        result = get_extras(entry, kind="playlist")
-
-        assert result["playlist_id"] == "playlist123"
-        assert result["playlist_title"] == "Test Playlist"
-        assert result["playlist_uploader"] == "Playlist Owner"
-        assert result["playlist_uploader_id"] == "owner123"
-
-    def test_release_timestamp(self):
-        """Test handling of release_timestamp for upcoming content."""
-
-        entry = {
-            "release_timestamp": 1234567890,
-        }
-
-        result = get_extras(entry)
-
-        assert "release_in" in result
-        assert result["release_in"] == "Fri, 13 Feb 2009 23:31:30 GMT"
-
-    def test_upcoming_live(self):
-        """Test handling of upcoming live stream."""
-
-        entry = {
-            "release_timestamp": 1234567890,
-            "live_status": "is_upcoming",
-        }
-
-        result = get_extras(entry)
-
-        assert result["is_live"] == 1234567890
-        assert "release_in" in result
-
-    def test_premiere_flag(self):
-        """Test handling of is_premiere flag."""
-
-        entry = {
-            "is_premiere": True,
-        }
-
-        result = get_extras(entry)
-        assert result["is_premiere"] is True
-
-        entry2 = {"is_premiere": False}
-        result2 = get_extras(entry2)
-        assert result2["is_premiere"] is False
-
-    def test_youtube_fallback_thumbnail(self):
-        """Test fallback thumbnail generation for YouTube videos."""
-
-        entry = {
-            "id": "dQw4w9WgXcQ",
-            "ie_key": "Youtube",
-        }
-
-        result = get_extras(entry)
-
-        assert result["thumbnail"] == "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
-
-    def test_thumbnail_string_fallback(self):
-        """Test fallback to thumbnail string when thumbnails list not available."""
-
-        entry = {
-            "thumbnail": "https://example.com/thumb.jpg",
-        }
-
-        result = get_extras(entry)
-
-        assert result["thumbnail"] == "https://example.com/thumb.jpg"
-
-
-class TestGetStaticYtdlp:
-    """Test the get_static_ytdlp function."""
-
-    def setup_method(self):
-        """Reset YTDLP singleton state before each test."""
-        from app.features.ytdlp.utils import _DATA
-
-        _DATA.YTDLP_INFO_CLS = None
-
-    def test_instance(self):
-        """Test that get_static_ytdlp returns a YTDLP instance."""
-        from app.features.ytdlp.ytdlp import YTDLP
-
-        # Get the cached instance
-        instance = get_ytdlp()
-
-        assert instance is not None
-        assert isinstance(instance, YTDLP)
-
-    def test_get_static_ytdlp_same(self):
-        """Test that get_static_ytdlp returns the same cached instance."""
-
-        instance1 = get_ytdlp()
-        instance2 = get_ytdlp()
-
-        assert instance1 is instance2
-
-    def test_get_static_ytdlp_with_params(self):
-        """Test that get_static_ytdlp returns a new instance when params are provided."""
-
-        instance1 = get_ytdlp()
-        instance2 = get_ytdlp(params={"quiet": False})
-
-        assert instance1 is not instance2
-        assert instance2 is not None
-
-    def test_get_static_ytdlp_params(self):
-        """Test that get_static_ytdlp initializes with correct parameters."""
-
-        instance = get_ytdlp()
-
-        # Access the internal params
-        params = instance.params
-
-        assert params.get("color") == "no_color"
-        assert params.get("extract_flat") is True
-        assert params.get("skip_download") is True
-        assert params.get("ignoreerrors") is True
-        assert params.get("ignore_no_formats_error") is True
-        assert params.get("quiet") is True
-
-
-class TestGetArchiveId:
-    """Test the get_archive_id function."""
-
-    @patch("app.features.ytdlp.utils._DATA.YTDLP_INFO_CLS")
-    def test_get_archive_id_basic(self, mock_ytdlp):
-        """Test basic archive ID extraction."""
-        mock_ytdlp._ies = {}
-
-        result = get_archive_id("https://youtube.com/watch?v=test123")
-        assert isinstance(result, dict)
-        assert "id" in result
-        assert "ie_key" in result
-        assert "archive_id" in result
-
-    def test_get_archive_id_invalid_url(self):
-        """Test with invalid URL."""
-        result = get_archive_id("invalid-url")
-        assert isinstance(result, dict)
-
-
-class TestArchiveFunctions:
-    """Test archive-related functions."""
-
-    def setup_method(self):
-        """Set up test archive file."""
-        self.temp_dir = str(make_test_temp_dir("ytdlp-archive"))
-        self.archive_file = Path(self.temp_dir) / "archive.txt"
-
-    def teardown_method(self):
-        """Clean up after tests."""
-        import shutil
-
-        shutil.rmtree(self.temp_dir, ignore_errors=True)
-
-    def test_archive_add_and_read(self):
-        """Test adding and reading archive entries."""
-        ids = ["youtube id1", "youtube id2", "youtube id3"]
-
-        result = archive_add(self.archive_file, ids)
-        assert result is True
-
-        read_ids = archive_read(self.archive_file)
-        assert set(read_ids) == set(ids)
-
-    def test_archive_delete(self):
-        """Test deleting archive entries."""
-        archive_add(self.archive_file, ["youtube id1", "youtube id2", "youtube id3"])
-
-        delete_ids = ["youtube id2"]
-        result = archive_delete(self.archive_file, delete_ids)
-        assert result is True
-        assert set(archive_read(self.archive_file)) == {"youtube id1", "youtube id3"}
-
-    def test_archive_read_nonexistent(self):
-        """Test reading from non-existent archive."""
-        nonexistent = Path(self.temp_dir) / "nonexistent.txt"
-        result = archive_read(nonexistent)
-        assert result == []

app/features/ytdlp/utils.py

@@ -1,529 +0,0 @@
-import json
-import logging
-import os
-import re
-import shlex
-from collections.abc import Callable
-from dataclasses import dataclass
-from email.utils import formatdate
-from pathlib import Path
-from typing import Any
-
-from app.features.ytdlp.patches import apply_ytdlp_patches
-from app.features.ytdlp.ytdlp import YTDLP
-from app.library.log import get_logger
-from app.library.Utils import merge_dict, timed_lru_cache
-
-LOG = get_logger()
-
-
-class _DATA:
-    YTDLP_INFO_CLS: Any = None
-    YTDLP_PARAMS: dict[str, Any] = {
-        "simulate": True,
-        "color": "no_color",
-        "extract_flat": True,
-        "skip_download": True,
-        "ignoreerrors": True,
-        "ignore_no_formats_error": True,
-        "quiet": True,
-    }
-    REMOVE_KEYS: list = [
-        {
-            "paths": "-P, --paths",
-            "outtmpl": "-o, --output",
-            "progress_hooks": "--progress_hooks",
-            "postprocessor_hooks": "--postprocessor_hooks",
-            "post_hooks": "--post_hooks",
-        },
-        {
-            "quiet": "-q, --quiet",
-            "no_warnings": "--no-warnings",
-            "forceprint": "-O, --print",
-            "noprogress": "--no-progress",
-            "wait_for_video": "--wait-for-video",
-            "progress_delta": " --progress-delta",
-            "progress_template": "--progress-template",
-            "consoletitle": "--console-title",
-            "progress_with_newline": "--newline",
-            "forcejson": "-j, --dump-single-json",
-            "opt_update_to": "--update-to",
-            "opt_ap_list_mso": "--ap-list-mso",
-            "opt_batch_file": "-a, --batch-file",
-            "opt_alias": "--alias",
-            "opt_list_extractors": "--list-extractors",
-            "opt_version": "--version",
-            "opt_help": "-h, --help",
-            "opt_update": "-U, --update",
-            "opt_list_subtitles": "--list-subs",
-            "opt_list_thumbnails": "--list-thumbnails",
-            "opt_list_format": "-F, --list-formats",
-            "opt_dump_agent": "--dump-user-agent",
-            "opt_extractor_descriptions": "--extractor-descriptions",
-            "opt_list_impersonate_targets": "--list-impersonate-targets",
-        },
-    ]
-    "Keys to remove from yt-dlp options at various levels."
-
-
-@dataclass(kw_only=True)
-class LogTarget:
-    """
-    A data class that represents a logging target with its level and type.
-
-    Attributes:
-        name (str): The name of the logging target.
-        target: The logging target, which can be a logging.Logger instance or a callable.
-        level (int): The logging level for the target.
-        logger (bool): True if the target is a logging.Logger instance, False otherwise.
-        type: The type of the target.
-
-    """
-
-    name: str | None = None
-    target: logging.Logger | Callable
-    level: int
-    logger: bool
-
-
-class LogWrapper:
-    def __init__(self, suppress: list[str] | tuple[str, ...] | None = None):
-        self.targets: list[LogTarget] = []
-        self.suppress: tuple[str, ...] = tuple(value for value in (suppress or ()) if isinstance(value, str) and value)
-
-    def add_target(self, target: logging.Logger | Callable, level: int = logging.DEBUG, name: str | None = None):
-        """
-        Adds a new logging target with the specified logging level.
-
-        Args:
-            target (logging.Logger|Callable): The logging target, which can be a logging.Logger instance or a Callable.
-            level (int): The logging level for the target. Defaults to logging.DEBUG.
-            name (str|None): The name of the logging target. Defaults to None.
-
-        """
-        if not isinstance(target, logging.Logger) and not callable(target):
-            msg = "Target must be a logging.Logger instance or a callable."
-            raise TypeError(msg)
-
-        if name is None:
-            name = target.name if isinstance(target, logging.Logger) else getattr(target, "__name__", "callable")
-
-        self.targets.append(
-            LogTarget(
-                name=name,
-                target=target,
-                level=level,
-                logger=isinstance(target, logging.Logger),
-            )
-        )
-
-    def has_targets(self):
-        return len(self.targets) > 0
-
-    def _skip(self, msg: Any) -> bool:
-        return isinstance(msg, str) and any(value in msg for value in self.suppress)
-
-    def _log(self, level, msg, *args, **kwargs):
-        if self._skip(msg):
-            return
-
-        for target in self.targets:
-            if level < target.level:
-                continue
-
-            if isinstance(target.target, logging.Logger):
-                log_kwargs: dict[str, Any] = {**kwargs}
-                log_kwargs.setdefault("stacklevel", 3)
-                target.target.log(level, msg, *args, **log_kwargs)
-            elif callable(target.target):
-                target.target(level, msg, *args, **kwargs)
-
-    def debug(self, msg, *args, **kwargs):
-        self._log(logging.DEBUG, msg, *args, **kwargs)
-
-    def info(self, msg, *args, **kwargs):
-        self._log(logging.INFO, msg, *args, **kwargs)
-
-    def warning(self, msg, *args, **kwargs):
-        self._log(logging.WARNING, msg, *args, **kwargs)
-
-    def error(self, msg, *args, **kwargs):
-        self._log(logging.ERROR, msg, *args, **kwargs)
-
-    def critical(self, msg, *args, **kwargs):
-        self._log(logging.CRITICAL, msg, *args, **kwargs)
-
-
-def arg_converter(
-    args: str,
-    level: int | bool | None = None,
-    dumps: bool = False,
-    removed_options: list | None = None,
-    keep_defaults: bool = False,
-) -> dict:
-    """
-    Convert yt-dlp options to a dictionary.
-
-    Args:
-        args (str): yt-dlp options string.
-        level (int|bool|None): Level of options to remove, True for all.
-        dumps (bool): Dump options as JSON.
-        removed_options (list|None): List of removed options.
-        keep_defaults (bool): Keep default options.
-
-    Returns:
-        dict: yt-dlp options dictionary.
-
-    """
-    import yt_dlp.options
-
-    create_parser = yt_dlp.options.create_parser
-
-    def _default_opts(args: str | list[str]):
-        patched_parser = create_parser()
-
-        def patched_create_parser():
-            return patched_parser
-
-        try:
-            yt_dlp.options.__dict__["create_parser"] = patched_create_parser
-            return yt_dlp.parse_options(args)
-        finally:
-            yt_dlp.options.__dict__["create_parser"] = create_parser
-
-    apply_ytdlp_patches()
-
-    default_opts = _default_opts([]).ydl_opts
-
-    if args:
-        # important to ignore external config files.
-        args = "--ignore-config " + args
-
-    opts = yt_dlp.parse_options(shlex.split(args, posix=os.name != "nt")).ydl_opts
-    diff = {k: v for k, v in opts.items() if default_opts[k] != v} if not keep_defaults else opts.items()
-    if "postprocessors" in diff:
-        diff["postprocessors"] = [pp for pp in diff["postprocessors"] if pp not in default_opts["postprocessors"]]
-
-    if "_warnings" in diff:
-        diff.pop("_warnings", None)
-
-    if level is True or isinstance(level, int):
-        bad_options = {}
-        if isinstance(level, bool) or not isinstance(level, int):
-            level = len(_DATA.REMOVE_KEYS)
-
-        for i, item in enumerate(_DATA.REMOVE_KEYS):
-            if i > level:
-                break
-
-            bad_options.update(item.items())
-
-        for key in diff.copy():
-            if key not in bad_options:
-                continue
-
-            if isinstance(removed_options, list):
-                removed_options.append(bad_options[key])
-
-            diff.pop(key, None)
-
-    if dumps is True:
-        from app.library.encoder import Encoder
-
-        if "match_filter" in diff:
-            import inspect
-
-            matchFilter = inspect.getclosurevars(diff["match_filter"].func).nonlocals["filters"]
-            if isinstance(matchFilter, set):
-                diff["match_filter"] = {"filters": list(matchFilter)}
-
-        return json.loads(json.dumps(diff, cls=Encoder, default=str))
-
-    return diff
-
-
-def extract_ytdlp_logs(logs: list[str], filters: list[str | re.Pattern[str]] | None = None) -> list[str]:
-    """
-    Extract yt-dlp log lines matching built-in filters plus any extras.
-
-    Args:
-        logs (list): log strings.
-        filters (list[str|Re.Pattern]): Optional extra filters of strings and/or regex.
-
-    Returns:
-        (list): List of matching log lines.
-
-    """
-    all_patterns: list[str | re.Pattern] = [
-        "This live event will begin",
-        "Video unavailable. This video is private",
-        "This video is available to this channel",
-        "Private video. Sign in if you've been granted access to this video",
-        "[youtube] Premieres in",
-        "Falling back on generic information extractor",
-        "URL could be a direct video link, returning it as such",
-    ] + (filters or [])
-
-    compiled: list[re.Pattern] = [
-        p if isinstance(p, re.Pattern) else re.compile(re.escape(p), re.IGNORECASE) for p in all_patterns
-    ]
-
-    matched: list[str] = []
-    matched.extend(line for line in logs if line and any(p.search(line) for p in compiled))
-
-    return list(dict.fromkeys(matched))
-
-
-def ytdlp_reject(entry: dict, yt_params: dict) -> tuple[bool, str]:
-    """
-    Implement yt-dlp reject filter logic.
-
-    Args:
-        entry (dict): The entry to check.
-        yt_params (dict): The yt-dlp parameters containing filters.
-
-    Returns:
-        tuple[bool, str]: A tuple where the first element is True if the entry passes the filters, or False if it does not,
-                          and the second element is a message explaining the reason for rejection or an empty string if it passes.
-
-    """
-    if title := entry.get("title"):
-        if (matchtitle := yt_params.get("matchtitle")) and not re.search(matchtitle, title, re.IGNORECASE):
-            return (False, f'"{title}" title did not match pattern "{matchtitle}". Skipping download.')
-
-        if (rejecttitle := yt_params.get("rejecttitle")) and re.search(rejecttitle, title, re.IGNORECASE):
-            return (False, f'"{title}" title matched reject pattern "{rejecttitle}". Skipping download.')
-
-    date = entry.get("upload_date")
-    date_range = yt_params.get("daterange")
-    if (date and date_range) and date not in date_range:
-        return (False, f"Upload date '{date}' is not in range '{date_range}'.")
-
-    view_count = entry.get("view_count")
-    if view_count is not None:
-        min_views = yt_params.get("min_views")
-        if min_views is not None and view_count < min_views:
-            return (
-                False,
-                f"Skipping {entry.get('title', 'video')}, because it has not reached minimum view count ({view_count}/{min_views}).",
-            )
-
-        max_views = yt_params.get("max_views")
-        if max_views is not None and view_count > max_views:
-            return (
-                False,
-                f"Skipping {entry.get('title', 'video')}, because it has exceeded maximum view count ({view_count}/{max_views}).",
-            )
-
-    try:
-        from yt_dlp.utils import age_restricted
-
-        if entry.get("age_limit") and age_restricted(entry.get("age_limit"), yt_params.get("age_limit")):
-            return (False, f'Video "{entry.get("title", "unknown")}" is age restricted.')
-    except ImportError:
-        pass
-
-    return (True, "")
-
-
-def get_ytdlp(params: dict | None = None) -> YTDLP:
-    if params:
-        return YTDLP(params=merge_dict(params, _DATA.YTDLP_PARAMS))
-
-    if _DATA.YTDLP_INFO_CLS is None:
-        _DATA.YTDLP_INFO_CLS = YTDLP(params=_DATA.YTDLP_PARAMS)
-
-    return _DATA.YTDLP_INFO_CLS
-
-
-def get_thumbnail(thumbnails: list) -> dict | None:
-    """
-    Extract thumbnail URL from a yt-dlp entry.
-
-    Args:
-        thumbnails (list): The list of thumbnail dictionaries from yt-dlp entry.
-
-    Returns:
-        dict | None: The best thumbnail dict if available, otherwise None.
-
-    """
-    if not thumbnails or not isinstance(thumbnails, list):
-        return None
-
-    def _thumb_sort_key(thumb: dict) -> tuple:
-        return (
-            thumb.get("preference") if thumb.get("preference") is not None else -1,
-            thumb.get("width") if thumb.get("width") is not None else -1,
-            thumb.get("height") if thumb.get("height") is not None else -1,
-            thumb.get("id") if thumb.get("id") is not None else "",
-            thumb.get("url"),
-        )
-
-    return max(thumbnails, key=_thumb_sort_key, default=None)
-
-
-def get_extras(entry: dict, kind: str = "video") -> dict:
-    """
-    Extract useful information from a yt-dlp entry.
-
-    Args:
-        entry (dict): The entry data from yt-dlp.
-        kind (str): The type of the item (e.g., "video", "playlist").
-
-    Returns:
-        dict: The extracted data.
-
-    """
-    extras = {}
-
-    if not entry or not isinstance(entry, dict):
-        return extras
-
-    if "playlist" == kind:
-        for property in ("id", "title", "uploader", "uploader_id"):
-            if val := entry.get(property):
-                extras[f"playlist_{property}"] = val
-
-    if thumbnail := get_thumbnail(entry.get("thumbnails", [])):
-        extras["thumbnail"] = thumbnail.get("url") if isinstance(thumbnail, dict) else thumbnail
-    elif thumbnail := entry.get("thumbnail"):
-        extras["thumbnail"] = thumbnail
-
-    for property in ("uploader", "channel"):
-        if val := entry.get(property):
-            extras[property] = val
-
-    if release_in := entry.get("release_timestamp"):
-        extras["release_in"] = formatdate(release_in, usegmt=True)
-
-    if release_in and "is_upcoming" == entry.get("live_status"):
-        extras["is_live"] = release_in
-
-    if duration := entry.get("duration"):
-        extras["duration"] = duration
-
-    extras["is_premiere"] = bool(entry.get("is_premiere", False))
-
-    extractor_key = entry.get("ie_key") or entry.get("extractor_key") or entry.get("extractor") or ""
-    if "thumbnail" not in extras and "youtube" in str(extractor_key).lower():
-        extras["thumbnail"] = "https://img.youtube.com/vi/{id}/maxresdefault.jpg".format(**entry)
-
-    return extras
-
-
-def parse_outtmpl(output_template: str, info_dict: dict, params: dict | None = None) -> str:
-    """
-    Parse yt-dlp output template with given info_dict.
-
-    Args:
-        output_template (str): The output template string.
-        info_dict (dict): The info dictionary from yt-dlp.
-        params (dict|None): Additional parameters for yt-dlp.
-
-    Returns:
-        str: The parsed output string.
-
-    """
-    return get_ytdlp(params=params).prepare_filename(info_dict=info_dict, outtmpl=output_template)
-
-
-@timed_lru_cache(ttl_seconds=300, max_size=256)
-def get_archive_id(url: str) -> dict[str, str | None]:
-    """
-    Get the archive ID for a given URL.
-
-    Args:
-        url (str): URL to check.
-
-    Returns:
-        dict: {
-            "id": str | None,
-            "ie_key": str | None,
-            "archive_id": str | None
-        }
-
-    """
-    idDict: dict[str, str | None] = {
-        "id": None,
-        "ie_key": None,
-        "archive_id": None,
-    }
-    from yt_dlp.utils import make_archive_id
-
-    for key, _ie in get_ytdlp()._ies.items():
-        try:
-            if not _ie.suitable(url):
-                continue
-
-            if not _ie.working():
-                continue
-
-            temp_id = _ie.get_temp_id(url)
-            if not temp_id:
-                continue
-
-            idDict["id"] = temp_id
-            idDict["ie_key"] = key
-            idDict["archive_id"] = make_archive_id(_ie, temp_id)
-            break
-        except Exception as e:
-            LOG.exception(
-                "Failed to get archive ID for '%s' with extractor '%s'.",
-                url,
-                key,
-                extra={"url": url, "extractor": key, "exception_type": type(e).__name__},
-            )
-
-    return idDict
-
-
-def archive_add(file: str | Path, ids: list[str], skip_check: bool = False) -> bool:
-    """
-    Add IDs to an archive file (delegates to the global Archiver).
-
-    Args:
-        file (str|Path): The archive file path.
-        ids (list[str]): List of IDs to add.
-        skip_check (bool): If True, skip checking for existing IDs.
-
-    Returns:
-        bool: True if any new IDs were appended, False otherwise.
-
-    """
-    from app.features.ytdlp.archiver import Archiver
-
-    return Archiver.get_instance().add(file, ids, skip_check)
-
-
-def archive_read(file: str | Path, ids: list[str] | None = None) -> list[str]:
-    """
-    Read IDs from an archive file with optional filtering (delegates to Archiver).
-
-    Args:
-        file (str|Path): The archive file path.
-        ids (list[str]|None): Optional list of IDs to query; None/empty returns all.
-
-    Returns:
-        list[str]: IDs present in the archive, optionally filtered.
-
-    """
-    from app.features.ytdlp.archiver import Archiver
-
-    return Archiver.get_instance().read(file, ids)
-
-
-def archive_delete(file: str | Path, ids: list[str]) -> bool:
-    """
-    Delete IDs from an archive file (delegates to Archiver).
-
-    Args:
-        file (str|Path): The archive file path.
-        ids (list[str]): List of IDs to remove.
-
-    Returns:
-        bool: True on success (including no-op), False on error.
-
-    """
-    from app.features.ytdlp.archiver import Archiver
-
-    return Archiver.get_instance().delete(file, ids)