timothyandClaude Opus 5
980da6db00
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 10s
PR Gates / Docs update reminder (pull_request) Successful in 16s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 15s
PR Gates / decisions lifecycle (pull_request) Successful in 22s
Review verdict / Set review-verdict status (pull_request_target) Successful in 21s
PR Gates / Script tests (pytest) (pull_request) Successful in 1m15s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 1m29s
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 17m25s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 20m3s
review-verdict/h10 Review-verdict: MERGEABLE @ 980da6d (base: main)
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 22m44s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
.codex/ is generated by `codex exec` as a machine-local mirror of the .claude hooks. It is deliberately NOT tracked even though .claude/ is (17 files): its config.toml embeds a plaintext Gitea credential and absolute /Users paths, so committing it would leak the credential and would not be portable anyway. Ignoring it also unblocks scripts/refresh-shared-checkout.sh, which refuses on a dirty tree. Separately, docs/handoffs/rest-api.md carried the same credential inline; it now references $ETV_GITEA_BASICAUTH like every other doc. NOTE this does not purge git history — the literal appears in 12 earlier commits and is still recoverable there. Refs: #698 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
88 lines
8.4 KiB
Markdown
88 lines
8.4 KiB
Markdown
# Handoff — ersatztv#2: REST API for channel / collection / schedule / playout CRUD
|
|
|
|
**How to use:** start a **fresh, parallel** session and say something like
|
|
*"Read `docs/handoffs/rest-api.md` and execute ersatztv#2 — do Phase 1 (investigate + determine the API shape) first and stop for sign-off before writing code."*
|
|
Read **ersatztv#2** in full (Gitea, `timothy/ersatztv`) before acting. This runs **in parallel** with smaller work happening on `main` in another session — coordinate via branches/PRs, don't assume exclusive ownership of the tree.
|
|
|
|
This is a **large greenfield feature**, deliberately split into two phases. Do **not** start coding in Phase 1.
|
|
|
|
---
|
|
|
|
## Why (from the issue)
|
|
|
|
ErsatzTV has no REST API for create/update/delete of channels, collections, schedules, or playouts — management is via the Blazor UI or fragile direct SQLite writes. Direct DB writes are dangerous because:
|
|
- EF Core uses **TPT inheritance** (e.g. `ProgramScheduleItem` → `ProgramScheduleOneItem`/…): must insert into the right subtype.
|
|
- Many NOT NULL / enum constraints (ScheduleKind, PlaybackOrder, CollectionType, …); wrong values produce broken playouts ("Cannot build playout type None").
|
|
- WAL mode → container must be stopped for safe external writes.
|
|
- No validation → easy to create unbuildable state.
|
|
|
|
The API closes this by routing all mutations through EF + existing domain validation, returning proper HTTP codes.
|
|
|
|
---
|
|
|
|
## Phase 1 — Investigate & determine the shape (DESIGN ONLY, get sign-off)
|
|
|
|
Goal: produce a short **design doc** (`docs/rest-api.md`) + an **increment split into sub-issues**, then stop for the user to approve before any implementation. Mirror the rigor we used on #1: ground every claim in the actual code, don't assume.
|
|
|
|
### 1a. Map what already exists (the issue says `GET /api/channels` already exists — find it)
|
|
- Locate the **existing API controller(s)** under `ErsatzTV/Controllers/` (there is already at least one read endpoint — find the route prefix, base class, content negotiation, and any auth/`access_token` handling). The new CRUD endpoints must match this style, not invent a new one.
|
|
- The **MediatR CQRS pattern**: queries/commands live in `ErsatzTV.Application/<Area>/{Queries,Commands}/`. Many handlers already return `Either<BaseError, T>`; there is a `.ToActionResult()` extension (used in `IptvController`) that maps `Either` → HTTP. Confirm the exact error/success mapping and reuse it (don't hand-roll status codes).
|
|
- The **Blazor pages** that already create/update/delete each resource (under `ErsatzTV/Pages/`): they call MediatR commands and carry the real validation. The API should call the **same** commands/handlers where they exist, and only add new ones where a Blazor flow doesn't map cleanly. Enumerate, per resource, which commands already exist vs. which are net-new.
|
|
- The **domain model + EF mapping**: `ErsatzTV.Core/Domain/` entities + `ErsatzTV.Infrastructure/Data/TvContext.cs`. Note the TPT hierarchies (ProgramScheduleItem subtypes, Collection kinds, StreamingMode/ScheduleKind enums). Determine whether any CRUD operation needs a **schema change** (most should not — pure CRUD over existing tables). **If a model change IS needed → dual-provider migration via `scripts/add-migration.sh` (Sqlite + MySql), enforced by the `migrations` CI job.** Flag this explicitly; CRUD-only likely needs none.
|
|
- **Auth**: how are existing endpoints secured (the IPTV ones use an `access_token` query param)? Decide the API's auth story and state it. Don't ship unauthenticated mutation endpoints without calling that out.
|
|
|
|
### 1b. Decide conventions (write them down)
|
|
- Route layout (`/api/channels`, `/api/collections/{id}/items`, …) — keep consistent with the existing controller.
|
|
- Status codes: 201 Created (+ Location), 200/204, 404, 422 validation. Map from `Either<BaseError,_>`.
|
|
- Request/response **DTOs** vs. reusing existing `*ViewModel`s — pick one and be consistent.
|
|
- Validation: reuse domain/handler validation; where Blazor validated in the page code-behind, that logic must move into (or already live in) the handler so the API gets it too.
|
|
- OpenAPI/Swagger? Pagination for list endpoints? Idempotency of deletes? — decide or explicitly defer.
|
|
- **URL emission caveat (from #1):** if any API response includes absolute URLs (logos, stream URLs), they inherit the request-`Host` fragility documented in `docs/m3u-xmltv.md`. Note how the API will handle it (probably: same request-derived host; don't bake).
|
|
|
|
### 1c. Increment plan (the sub-issues)
|
|
Split #2 into vertical slices, **Channels first** as the pattern-setter (it's the simplest full CRUD and the others copy its shape):
|
|
- **#2a Channels** — POST/PUT/DELETE (+ confirm existing GETs).
|
|
- **#2b Collections** — CRUD + item add/remove.
|
|
- **#2c Schedules** — CRUD + schedule-item add/remove (this is the TPT-heavy one; budget for it).
|
|
- **#2d Playouts** — create (link channel↔schedule) / delete (+ existing reset).
|
|
|
|
Each slice = one branch = one PR. Open the sub-issues, link them to #2 (which becomes the tracker), and **stop for sign-off**.
|
|
|
|
---
|
|
|
|
## Phase 2 — Implement (workflows / ultracode, one slice at a time)
|
|
|
|
Only after Phase 1 sign-off. Per slice (start with #2a Channels):
|
|
|
|
**Shape of the work per resource** (good fit for a `Workflow` pipeline or `ultracode`):
|
|
1. For each endpoint: Command + Handler in `ErsatzTV.Application/<Resource>/Commands/` (reuse existing where found), returning `Either<BaseError, T>`.
|
|
2. Controller action in `ErsatzTV/Controllers/` mapping via `.ToActionResult()`.
|
|
3. Validation reused from the corresponding Blazor flow / domain.
|
|
4. **NUnit** tests (+ Shouldly + NSubstitute) — handler unit tests for success + each failure (404/validation), and a controller/integration test for status-code mapping. (No xUnit.)
|
|
5. Run the suite locally with `TZ=UTC` (matches CI; see the known TZ-sensitive filler tests, #24).
|
|
|
|
**Suggested workflow pattern:** pipeline over the endpoints of the slice — stage 1 author handler+test, stage 2 adversarially review each (does it actually go through EF? does it handle TPT/enum constraints? does delete cascade correctly?). Adversarial verify is worth it here because broken writes corrupt playouts. Use `ultracode` if the user opts in, otherwise a single `Workflow` per slice.
|
|
|
|
**Regression nets already in place — lean on them:**
|
|
- **Architecture tests (#12)** enforce layering: controllers in `ErsatzTV`, business logic in `ErsatzTV.Application`, no concrete-provider leakage. New code must pass `ErsatzTV.Architecture.Tests` (will fail the PR if you put logic in the wrong layer).
|
|
- **M3U goldens (#11)** guard `ToM3U` output if a channel change touches it.
|
|
- Add focused tests for new behavior; consider an integration test that creates→reads→deletes through the real EF stack (SQLite) to prove TPT/cascade correctness.
|
|
|
|
---
|
|
|
|
## Process (non-negotiable — CLAUDE.md + `docs/contributing.md`)
|
|
- Follow established patterns; diverge only with a stated reason (contributors guide #10).
|
|
- Dependencies via **Central Package Management** (`Directory.Packages.props`); never re-add `Version=` to a `<PackageReference>`.
|
|
- **One branch = one PR.** PR runs `test` + `migrations` (both **required** to merge). Merge to `main` runs `test`+`migrations`+`build`+smoke/E2E. Verify green before closing each sub-issue.
|
|
- Migrations only if the model changes — `scripts/add-migration.sh <Name>` does **both** providers.
|
|
- Adversarial self-review of the diff before closing (see memory: adversarial-self-review-at-milestones). Then Task Completion Protocol / `/done <sub-issue>`.
|
|
- CI poll: `curl -u "$ETV_GITEA_BASICAUTH" …/api/v1/repos/timothy/ersatztv/actions/tasks` (jobs by name), or the runs API.
|
|
|
|
## Repo state at handoff
|
|
- `main` is green; #1 closed (config/topology, not code — see `docs/m3u-xmltv.md`). #5 triaged as Jellyfin/infra (→ server-management).
|
|
- `main` requires `Build & test (.NET)` **and** `EF migration integrity (SQLite + MySql)` to merge a PR.
|
|
- Test framework is **NUnit** (+ Shouldly + NSubstitute), not xUnit.
|
|
- Versioning is CalVer `vYY.N.P`; only tag when the user asks. The API is the first real app-feature work → first such release would be `v26.4.0`.
|
|
- Infra: Docker host **bumblebee** `192.168.1.99`; container `ersatztv` (port 8409); registry `192.168.1.95:3000/timothy/ersatztv`. Plain `ssh timothy@192.168.1.99` works; ssh-mcp/docker-mcp need `--key=~/.ssh/id_rsa` + client restart if they 401.
|
|
- This session runs **in parallel** with smaller tasks (#28 XMLTV/logo goldens, #24 TZ tests) landing on `main` — rebase before opening PRs.
|