siftlode/backend/app/routes/_common.py

"""Route-layer shared helpers for the API contract.

Small, dependency-light guards that several route modules had hand-rolled with subtle
drift. Keeping them here (imported by the route modules) means the "fetch a row or 404"
and "fetch a row this user owns or 404" idioms have one definition, one status code, and
one existence-leak policy.
"""

from typing import Any, Protocol, TypeVar

from fastapi import HTTPException, Request
from pydantic import BaseModel, ConfigDict, Field
from sqlalchemy.orm import Session

from app.db import Base
from app.models import POSITION_MAX_S, User
from app.issues import gitea
from app.refusal import refused
from app.youtube.client import YouTubeError, refusal_reason

M = TypeVar("M", bound=Base)

# Resume-position thresholds of a player that only keeps a resume point (the YouTube player, the
# library's): positions below this are "didn't really start" and within this of the end are
# "basically finished" — neither is worth storing, so the position is cleared instead (no progress
# bar). The client's local resume (`lib/resume.ts`) keeps the same two numbers, held equal by
# `resume.contract.test.ts` beside it. NB: the Plex player intentionally uses a LARGER finish margin
# (30s) because it marks long-form items watched, not just clears a resume bar — see
# routes/plex/playback.py.
PROGRESS_MIN_SECONDS = 5
FINISH_MARGIN_SECONDS = 10


class ProgressIn(BaseModel):
    """A player's resume checkpoint (sent every few seconds while it plays, and as a beacon when the
    page goes away)."""

    # Finite only: JSON parsing here accepts `Infinity`/`NaN`, and the handler's `int()` turned
    # one into a 500.
    model_config = ConfigDict(allow_inf_nan=False)

    # Accept a float and truncate (`kept_position`) — the player may post a raw currentTime (a float),
    # which the old `int(payload.get(...))` silently truncated. A plain `int` field would 422 that on
    # the progress hot path, losing the resume position; `float` keeps the old tolerance.
    # Bounded above by the int4 column (see POSITION_MAX_S): past it the flush was a 500.
    position_seconds: float = Field(0, le=POSITION_MAX_S)
    duration_seconds: float = Field(0, le=POSITION_MAX_S)


def kept_position(body: ProgressIn) -> int:
    """The whole-second resume point worth storing for `body`, or 0 for "clear it" (too early to
    count as started, or close enough to the end to count as finished)."""
    position = max(0, int(body.position_seconds))
    duration = int(body.duration_seconds)
    near_end = duration > 0 and position > duration - FINISH_MARGIN_SECONDS
    return position if position >= PROGRESS_MIN_SECONDS and not near_end else 0


def not_found(what: str = "generic") -> HTTPException:
    """The 404 for a row that is gone — structured, so the bilingual UI says it in the reader's
    language (`errors.notFound.<what>`, generic fallback). This is the 404 a user actually meets: the
    thing was deleted in another tab or on another device. It used to be a bare English string
    ("Unknown view", "Not found"), which the Hungarian UI toasted verbatim."""
    return HTTPException(status_code=404, detail={"code": "not_found", "reason": what})


def get_or_404(
    db: Session, model: type[M], id_: Any, *, what: str = "generic", lock: bool = False
) -> M:
    """Fetch a row by primary key or raise 404. Replaces the `db.get(Model, id); if None: 404`
    idiom repeated across routes. `lock` takes it FOR UPDATE (bypassing the identity map), so two
    requests that read-then-write its children (a playlist's item positions) run one after the other."""
    obj = db.get(model, id_, with_for_update=True if lock else None)
    if obj is None:
        raise not_found(what)
    return obj


def owned_or_404(
    db: Session,
    model: type[M],
    id_: Any,
    user: User,
    *,
    owner_attr: str = "user_id",
    what: str = "generic",
    lock: bool = False,
) -> M:
    """Fetch a row by primary key that `user` owns, or raise 404 (`lock`: see `get_or_404`). A row owned by someone
    else 404s (NOT 403) on purpose — a 403 would confirm the id exists to a stranger.
    It replaced the near-identical per-route ownership helpers, and is called directly — a thin
    `_own_x` wrapper around it is the ad-hoc shape CLAUDE.md's patterns table rules out."""
    obj = get_or_404(db, model, id_, what=what, lock=lock)
    if getattr(obj, owner_attr) != user.id:
        raise not_found(what)
    return obj


def youtube_refusal(exc: Exception, *, playlist: bool = False) -> HTTPException:
    """The answer to an action YouTube refused: a 422 whose reason the UI translates
    (`errors.youtube.<reason>`). One definition, because the routes had grown three shapes of it —
    a bare English string quoting the upstream message, a playlist-scoped reason, and nothing at
    all (a raw 500 from the manual syncs). The upstream failure is already logged where it
    happened (`youtube.api.error`). A failure that is not the Data API's (the search scraper's) is
    YouTube being unavailable to us — the retryable answer. `playlist`: the route acts on one
    playlist the user picked, so a missing playlist is THAT one, gone (`refusal_reason`)."""
    reason = (
        refusal_reason(exc, playlist=playlist) if isinstance(exc, YouTubeError) else "unavailable"
    )
    return HTTPException(status_code=422, detail={"code": "youtube", "reason": reason})


async def capped_body(request: Request, limit: int) -> bytes:
    """The request body, refused (413 `too_large`) the moment it passes `limit` bytes while still
    arriving. Counted, not taken from Content-Length: a declared length can be absent (chunked) or
    wrong, and counting stops reading at the same point a declared-length check would have."""
    body = bytearray()
    async for chunk in request.stream():
        body += chunk
        if len(body) > limit:
            raise HTTPException(status_code=413, detail={"code": "too_large"})
    return bytes(body)


class ByteSink(Protocol):
    """Where `capped_stream_to` writes: a file, or anything that takes the bytes on their way to one."""

    def write(self, data: bytes, /) -> object: ...


async def capped_stream_to(
    request: Request, out: ByteSink, limit: int, refusal: HTTPException
) -> int:
    """`capped_body`'s sibling for a body too large to hold: the same counting rule, written
    straight to `out` instead of accumulated, returning the size.

    Two deliberate differences from `capped_body`. It never builds a `bytearray` — the upload route
    admits 500 MiB by default, so holding the body would trade a disk problem for a memory one. And
    the refusal is the CALLER'S, passed in rather than assumed: `capped_body`'s flat 413 is right
    for a screenshot, while the upload route answers 422 `upload_too_large` carrying the admin
    knob's own number, which is what its dialog shows the user. One counting rule, two answers,
    neither of them a second copy of the loop.

    The caller owns `out` and owns cleaning it up: a body refused half-way has already written what
    arrived before the limit was passed.

    **The refusal DRAINS the rest of the body before it is raised, and that is not politeness.**
    Answering mid-upload and closing the connection is what the client sees as a network failure,
    not as a refusal: the browser's XHR fires `onerror` before it can read the response, so a file
    over the limit reported itself as "the server couldn't be reached" instead of naming the limit —
    measured in a real browser, not reasoned about. Reading the remainder to nowhere lets the client
    finish sending, read the 422 and say the true thing.

    The bytes are discarded, never written, and the whole request is already bounded by
    `bodylimit`'s per-route ceiling — so the worst case is bandwidth an authenticated caller was
    sending anyway, against the old behaviour which wrote exactly those bytes to disk."""
    size = 0
    over = False
    async for chunk in request.stream():
        size += len(chunk)
        if over:
            continue  # draining — see the docstring; counted, not stored
        if size > limit:
            over = True
            continue
        out.write(chunk)
    if over:
        raise refusal
    return size


def issue_refused(exc: gitea.GiteaError) -> HTTPException:
    """The refusal an issue-tracker failure answers as — the send, the preview and the
    admin's connection test alike. Literal reasons, one per case: the frontend's contract test reads
    them to require a sentence for each in both languages."""
    match exc.reason:
        case "not_configured":
            return refused(400, "issues_not_configured")
        case "unreachable":
            return refused(422, "issues_unreachable")
        case "bad_token":
            return refused(422, "issues_bad_token")
        case "repo_not_found":
            return refused(422, "issues_repo_not_found")
        case "public_repo":
            return refused(422, "issues_public_repo")
        case "issues_disabled":
            return refused(422, "issues_disabled")
        case _:
            return refused(422, "issues_rejected")