| | @@ -0,0 +1,2032 @@ |
| + | # DropHawk - Binding Contracts (Addendum to SPEC.md) |
| + | |
| + | > **Status:** BINDING. Where this file and SPEC.md disagree, **this file wins**. |
| + | > **Purpose:** Close every ambiguity in SPEC.md. Pin every version. Specify every schema byte. No settling. |
| + | > **Reading order:** Read SPEC.md sections 1-6 for context, then read this entire file before writing any code. Every section here overrides any soft language in SPEC.md. |
| + | |
| + | This document corrects the original spec to current upstream versions (verified June 2026): |
| + | - **Next.js 16.2.9** (not 14) - App Router, Server Components, React 19 |
| + | - **Tailwind CSS 4.3.1** (not v3) - CSS-first config via `@theme`, **no `tailwind.config.ts`** |
| + | - **React 19.2** - Server Actions, `use()` hook, `useFormState` |
| + | - **Grafana 13.0.2**, **NATS 2.14.2**, **Caddy 2.11.4**, **Axum 0.8.9**, **Meilisearch 1.47.0** |
| + | |
| + | --- |
| + | |
| + | ## §A. Pinned Versions (exact - do not bump without re-running CI matrix) |
| + | |
| + | ### A.1 Backend (Rust) - `backend/Cargo.toml` |
| + | ```toml |
| + | [package] |
| + | name = "drophawk-backend" |
| + | version = "0.1.0" |
| + | edition = "2021" |
| + | rust-version = "1.96" |
| + | |
| + | [dependencies] |
| + | tokio = { version = "=1.45.1", features = ["full", "parking_lot", "tracing"] } |
| + | axum = { version = "=0.8.4", features = ["macros", "tokio", "ws"] } |
| + | tower = "=0.5.2" |
| + | tower-http = { version = "=0.6.6", features = ["cors", "trace", "compression-br", "compression-gzip", "timeout", "request-id"] } |
| + | hyper = { version = "=1.6.0", features = ["full"] } |
| + | reqwest = { version = "=0.12.22", default-features = false, features = ["json", "gzip", "brotli", "rustls-tls", "http2", "stream"] } |
| + | rquest = { version = "=5.0.0", features = ["impersonate", "json"] } # TLS fingerprinting, Phase 3+ |
| + | sqlx = { version = "=0.8.6", features = ["runtime-tokio-rustls", "postgres", "macros", "migrate", "chrono", "json", "ipnetwork"] } |
| + | async-nats = "=0.41.0" |
| + | redis = { version = "=0.32.3", features = ["tokio-rustls-comp", "connection-manager"] } |
| + | serde = { version = "=1.0.219", features = ["derive"] } |
| + | serde_json = { version = "=1.0.140", features = ["preserve_key_order", "raw_value"] } |
| + | chrono = { version = "=0.4.41", features = ["serde", "clock"], default-features = false } |
| + | uuid = { version = "=1.17.0", features = ["v7", "serde"] } |
| + | sha2 = "=0.10.9" |
| + | hex = "=0.4.3" |
| + | tracing = "=0.1.41" |
| + | tracing-subscriber = { version = "=0.3.19", features = ["env-filter", "json", "registry"] } |
| + | opentelemetry = "=0.29.0" |
| + | opentelemetry-otlp = "=0.29.0" |
| + | opentelemetry_sdk = { version = "=0.29.0", features = ["rt-tokio"] } |
| + | thiserror = "=2.0.12" |
| + | async-trait = "=0.1.88" |
| + | validator = { version = "=0.20.0", features = ["derive"] } |
| + | figment = { version = "=0.10.19", features = ["env", "toml"] } |
| + | anyhow = "=1.0.98" # binary entry only |
| + | prometheus = "=0.14.0" |
| + | once_cell = "=1.21.3" |
| + | parking_lot = "=0.12.3" |
| + | futures = "=0.3.31" |
| + | bytes = "=1.10.1" |
| + | mime = "=0.3.17" |
| + | url = { version = "=2.5.4", features = ["serde"] } |
| + | |
| + | [dev-dependencies] |
| + | wiremock = "=0.6.3" |
| + | tokio-test = "=0.4.4" |
| + | pretty_assertions = "=1.4.1" |
| + | insta = "=1.43.1" |
| + | ``` |
| + | |
| + | **Build profile:** |
| + | ```toml |
| + | [profile.release] |
| + | lto = "fat" |
| + | codegen-units = 1 |
| + | strip = "symbols" |
| + | panic = "abort" |
| + | opt-level = 3 |
| + | ``` |
| + | |
| + | ### A.2 Python scrapers - `scrapers/pyproject.toml` |
| + | ```toml |
| + | [project] |
| + | name = "drophawk-scrapers" |
| + | version = "0.1.0" |
| + | requires-python = "==3.11.*" |
| + | |
| + | [tool.uv] |
| + | dev-dependencies = [ |
| + | "pytest==8.4.1", |
| + | "pytest-asyncio==0.26.0", |
| + | "pytest-cov==6.2.1", |
| + | "vcrpy==7.0.0", |
| + | "respx==0.22.0", |
| + | "ruff==0.12.0", |
| + | "mypy==1.16.0", |
| + | ] |
| + | |
| + | dependencies = [ |
| + | "httpx==0.28.1", |
| + | "curl-cffi==0.11.1", |
| + | "selectolax==0.3.29", |
| + | "beautifulsoup4==4.13.4", |
| + | "playwright==1.61.0", |
| + | "playwright-stealth==1.0.6", |
| + | "async-nats==0.41.0", |
| + | "pydantic==2.11.7", |
| + | "tenacity==9.1.2", |
| + | "python-dotenv==1.1.0", |
| + | "orjson==3.11.0", |
| + | "structlog==25.4.0", |
| + | "fake-useragent==2.2.0", |
| + | "cssselect==1.3.0", |
| + | ] |
| + | ``` |
| + | |
| + | **Lockfile:** Commit `uv.lock`. CI runs `uv sync --frozen`. |
| + | |
| + | ### A.3 Frontend - `frontend/package.json` |
| + | ```json |
| + | { |
| + | "name": "drophawk-frontend", |
| + | "private": true, |
| + | "type": "module", |
| + | "engines": { "node": ">=20.9.0", "pnpm": ">=9.0.0" }, |
| + | "packageManager": "pnpm@9.18.2", |
| + | "scripts": { |
| + | "dev": "next dev --turbopack", |
| + | "build": "next build", |
| + | "start": "next start -H 0.0.0.0 -p 3000", |
| + | "lint": "next lint", |
| + | "typecheck": "tsc --noEmit", |
| + | "test": "vitest run", |
| + | "test:e2e": "playwright test", |
| + | "format": "prettier --write ." |
| + | }, |
| + | "dependencies": { |
| + | "next": "16.2.9", |
| + | "react": "19.2.0", |
| + | "react-dom": "19.2.0", |
| + | "@tanstack/react-query": "5.101.0", |
| + | "@tanstack/react-virtual": "3.13.12", |
| + | "zustand": "5.0.8", |
| + | "react-hook-form": "7.62.0", |
| + | "@hookform/resolvers": "3.10.0", |
| + | "zod": "3.25.76", |
| + | "framer-motion": "12.40.0", |
| + | "lucide-react": "0.475.0", |
| + | "cmdk": "1.1.1", |
| + | "sonner": "1.7.4", |
| + | "date-fns": "4.1.0", |
| + | "clsx": "2.1.1", |
| + | "tailwind-merge": "3.3.1", |
| + | "class-variance-authority": "0.7.1", |
| + | "@radix-ui/react-dialog": "1.1.17", |
| + | "@radix-ui/react-dropdown-menu": "2.1.16", |
| + | "@radix-ui/react-popover": "1.1.16", |
| + | "@radix-ui/react-select": "2.1.16", |
| + | "@radix-ui/react-switch": "1.1.16", |
| + | "@radix-ui/react-tabs": "1.1.16", |
| + | "@radix-ui/react-tooltip": "1.1.17", |
| + | "@radix-ui/react-toast": "1.2.16", |
| + | "@radix-ui/react-label": "2.1.14", |
| + | "@radix-ui/react-slot": "1.3.0", |
| + | "recharts": "3.2.1" |
| + | }, |
| + | "devDependencies": { |
| + | "@types/node": "22.19.0", |
| + | "@types/react": "19.2.0", |
| + | "@types/react-dom": "19.2.0", |
| + | "typescript": "5.9.2", |
| + | "tailwindcss": "4.3.1", |
| + | "@tailwindcss/postcss": "4.3.1", |
| + | "postcss": "8.5.6", |
| + | "autoprefixer": "10.4.21", |
| + | "prettier": "3.6.2", |
| + | "prettier-plugin-tailwindcss": "0.7.1", |
| + | "eslint": "9.32.0", |
| + | "eslint-config-next": "16.2.9", |
| + | "@eslint/js": "9.32.0", |
| + | "typescript-eslint": "8.38.0", |
| + | "vitest": "3.2.4", |
| + | "@vitejs/plugin-react": "5.0.0", |
| + | "@testing-library/react": "16.3.0", |
| + | "@testing-library/jest-dom": "6.6.3", |
| + | "@playwright/test": "1.61.0" |
| + | } |
| + | } |
| + | ``` |
| + | |
| + | > **Note on Tremor:** Original spec mentioned `@tremor/react` but it's stale (last release Jan 2025). Use **Recharts 3.2.1 + custom shadcn-style chart wrappers** instead. This is the upgraded choice. |
| + | |
| + | ### A.4 Infrastructure - `docker-compose.yml` image tags |
| + | ```yaml |
| + | postgres: postgres:16.10-bookworm # with timescaledb-tsl via build |
| + | redis: redis:7.4.3-alpine3.21 |
| + | nats: nats:2.14.2-alpine3.21 # with -js flag for JetStream |
| + | meilisearch: getmeili/meilisearch:v1.47.0 |
| + | ntfy: binwiederhier/ntfy:v2.14.0 |
| + | minio: minio/minio:RELEASE.2026-01-15T01-00-00Z |
| + | prometheus: prom/prometheus:v3.4.1 |
| + | grafana: grafana/grafana-oss:13.0.2 |
| + | loki: grafana/loki:3.5.5 |
| + | caddy: caddy:2.11.4-alpine |
| + | ``` |
| + | |
| + | ### A.5 Tools |
| + | - Rust: `1.96.0` via `rustup toolchain install 1.96.0` |
| + | - Node: `20.20.2` (LTS Iron, already installed) - frontend requires `>=20.9.0` ✓ |
| + | - pnpm: `9.18.2` (install via `corepack enable && corepack prepare pnpm@9.18.2 --activate`) |
| + | - Python: `3.11.2` (already installed) |
| + | - uv: `0.7.0` (install via `curl -LsSf https://astral.sh/uv/0.7.0/install.sh | sh`) |
| + | - Docker: `>=24.0` on homelab host |
| + | - Docker Compose: `v2.30+` (plugin form) |
| + | |
| + | --- |
| + | |
| + | ## §B. Exact API Contracts |
| + | |
| + | All paths under `/api`. All request bodies `application/json; charset=utf-8`. All responses `application/json; charset=utf-8` (except SSE). Timestamps RFC3339 UTC with `Z` suffix. Money fields in **minor units** (cents) as integer. Money formatting for display happens client-side. |
| + | |
| + | ### B.1 Response envelope |
| + | |
| + | **Success (single resource):** |
| + | ```json |
| + | { "data": { /* resource */ }, "meta": { "request_id": "uuid-v7", "version": "v1" } } |
| + | ``` |
| + | |
| + | **Success (collection):** |
| + | ```json |
| + | { |
| + | "data": [ /* resources */ ], |
| + | "meta": { |
| + | "request_id": "01HXY...", |
| + | "version": "v1", |
| + | "page": 1, |
| + | "per_page": 50, |
| + | "total": 1234, |
| + | "total_pages": 25 |
| + | } |
| + | } |
| + | ``` |
| + | |
| + | **Error:** |
| + | ```json |
| + | { |
| + | "error": { |
| + | "code": "SOURCE_NOT_FOUND", |
| + | "message": "No source with id 'stubhub'", |
| + | "request_id": "01HXY...", |
| + | "details": { /* optional, schema-specific */ } |
| + | } |
| + | } |
| + | ``` |
| + | |
| + | ### B.2 Error code → HTTP status table (complete) |
| + | |
| + | | Code | HTTP | When | |
| + | |---|---|---| |
| + | | `BAD_REQUEST` | 400 | Malformed JSON, missing required field | |
| + | | `VALIDATION_FAILED` | 422 | Zod-equivalent schema fail; `details.fields[]` lists errors | |
| + | | `UNAUTHORIZED` | 401 | Missing/invalid session token (Phase 7+ auth) | |
| + | | `FORBIDDEN` | 403 | Authenticated but not allowed | |
| + | | `NOT_FOUND` | 404 | Resource id does not exist | |
| + | | `CONFLICT` | 409 | Watchlist rule duplicate | |
| + | | `RATE_LIMITED` | 429 | Client rate limited (per IP, 100 req/min) | |
| + | | `INTERNAL` | 500 | Unhandled; full trace in logs only, never response | |
| + | | `UPSTREAM_UNAVAILABLE` | 503 | DB/NATS/Redis unreachable | |
| + | | `NOT_IMPLEMENTED` | 501 | v2+ endpoint called in v1 build | |
| + | |
| + | ### B.3 Endpoints - full contracts |
| + | |
| + | #### `GET /api/events` |
| + | Query params (all optional): |
| + | | Param | Type | Default | Notes | |
| + | |---|---|---|---| |
| + | | `page` | int ≥1 | 1 | | |
| + | | `per_page` | int 1-100 | 50 | | |
| + | | `category` | enum | - | `concert,sports,festival,theater,other` (comma list) | |
| + | | `sport` | enum | - | `nfl,nba,nhl,mlb,tennis,f1,soccer,other` | |
| + | | `source_id` | enum | - | comma list | |
| + | | `status` | enum | - | `announced,presale,onsale,soldout,cancelled` | |
| + | | `price_min_usd_cents` | int | - | filters `price_min >=` | |
| + | | `price_max_usd_cents` | int | - | filters `price_max <=` | |
| + | | `starts_after` | RFC3339 | - | `starts_at >=` | |
| + | | `starts_before` | RFC3339 | - | `starts_at <=` | |
| + | | `on_sale_after` | RFC3339 | - | `on_sale_at >=` | |
| + | | `q` | string | - | trigram search on title | |
| + | | `sort` | enum | `on_sale` | `on_sale,-starts_at,price_min,-first_seen_at` | |
| + | |
| + | Response `data[]` element: |
| + | ```json |
| + | { |
| + | "id": 12345, |
| + | "source_id": "ticketmaster", |
| + | "source_event_id": "Z1p2q3r4s5t6", |
| + | "title": "Taylor Swift | The Eras Tour", |
| + | "subtitle": "with Paramore", |
| + | "category": "concert", |
| + | "sport": null, |
| + | "starts_at": "2026-08-12T23:59:00Z", |
| + | "venue_name": "Hard Rock Stadium", |
| + | "city": "Miami Gardens", |
| + | "country": "US", |
| + | "latitude": 25.958, |
| + | "longitude": -80.239, |
| + | "image_url": "https://.../eras.jpg", |
| + | "on_sale_at": "2026-06-22T15:00:00Z", |
| + | "presale_on_sale_at": "2026-06-19T15:00:00Z", |
| + | "status": "onsale", |
| + | "price_min": 4950, |
| + | "price_max": 89900, |
| + | "currency": "USD", |
| + | "inventory_remaining": 15234, |
| + | "buy_url": "https://www.ticketmaster.com/event/Z1p2q3r4s5t6", |
| + | "first_seen_at": "2026-06-15T10:00:00Z", |
| + | "updated_at": "2026-06-22T15:00:03Z" |
| + | } |
| + | ``` |
| + | |
| + | #### `GET /api/events/:id` |
| + | Single event + `price_history[]` (last 30 days, max 1000 points) + `cross_source_links[]` (see §Q). |
| + | |
| + | #### `GET /api/drops` |
| + | Query params: `page`, `per_page`, `drop_type` (`new,status,price,inventory,announcement`), `category`, `source_id`, `since` (RFC3339), `until`. Sort fixed `detected_at DESC`. |
| + | |
| + | Response `data[]` element: |
| + | ```json |
| + | { |
| + | "id": 987654, |
| + | "event_id": 12345, |
| + | "drop_type": "status", |
| + | "from_state": { "status": "announced" }, |
| + | "to_state": { "status": "onsale" }, |
| + | "detected_at": "2026-06-22T15:00:01.234Z", |
| + | "notified": true, |
| + | "notified_at": "2026-06-22T15:00:02.891Z", |
| + | "event": { /* embedded Event, same shape as B.3 */ } |
| + | } |
| + | ``` |
| + | |
| + | #### `GET /api/drops/stream` (SSE) |
| + | Response headers: |
| + | ``` |
| + | Content-Type: text/event-stream; charset=utf-8 |
| + | Cache-Control: no-cache, no-transform |
| + | Connection: keep-alive |
| + | X-Accel-Buffering: no # disable proxy buffering |
| + | ``` |
| + | |
| + | Wire protocol - each event: |
| + | ``` |
| + | event: drop.status |
| + | id: 987654 |
| + | data: {"id":987654,"event_id":12345,"drop_type":"status","detected_at":"2026-06-22T15:00:01.234Z","event":{...}} |
| + | |
| + | ``` |
| + | |
| + | (trailing blank line mandatory) |
| + | |
| + | Heartbeat every 15s: |
| + | ``` |
| + | : heartbeat 1719064800 |
| + | |
| + | ``` |
| + | |
| + | Reconnect: client reads `Last-Event-ID` header → server replays from that drop id forward on reconnect (query `drops WHERE id > $last_event_id ORDER BY id ASC LIMIT 500`), then switches to live tail. |
| + | |
| + | Event types (complete enum): `drop.new`, `drop.status`, `drop.price`, `drop.inventory`, `drop.announcement`, `source.health` (status changes), `system.info`. |
| + | |
| + | #### `GET /api/watchlist` |
| + | Response `data[]`: |
| + | ```json |
| + | { |
| + | "id": 12, |
| + | "kind": "artist", |
| + | "pattern": "(?i)\\btaylor\\s+swift\\b", |
| + | "label": "Taylor Swift", |
| + | "active": true, |
| + | "priority": "critical", |
| + | "matches_30d": 47, |
| + | "created_at": "2026-06-01T00:00:00Z" |
| + | } |
| + | ``` |
| + | |
| + | #### `POST /api/watchlist` |
| + | Request: |
| + | ```json |
| + | { |
| + | "kind": "artist", |
| + | "pattern": "(?i)\\btaylor\\s+swift\\b", |
| + | "label": "Taylor Swift", |
| + | "priority": "critical" |
| + | } |
| + | ``` |
| + | - `kind` ∈ {`artist`, `team`, `venue`, `sport`, `category`, `keyword`, `twitter_account`} |
| + | - `pattern` is a Rust regex (`regex` crate syntax). Server validates by compiling it; 422 on failure. |
| + | - `priority` ∈ {`low`, `normal`, `high`, `critical`}, default `normal`. |
| + | - 409 if `(kind, pattern)` already exists. |
| + | |
| + | #### `PATCH /api/watchlist/:id` |
| + | Partial update: `active`, `priority`, `label`. Cannot change `kind` or `pattern` (delete and recreate). |
| + | |
| + | #### `DELETE /api/watchlist/:id` → 204 No Content |
| + | |
| + | #### `POST /api/watchlist/bulk` |
| + | Request: `{ "rules": [{ "kind":"keyword","label":"Coldplay" }, ...] }` |
| + | For each rule, server auto-generates pattern as `(?i)\b<escaped_label>\b`. Returns `{ "data": { "created": N, "skipped_duplicates": M } }`. |
| + | |
| + | #### `GET /api/sources` |
| + | Response `data[]`: |
| + | ```json |
| + | { |
| + | "id": "ticketmaster", |
| + | "name": "Ticketmaster Discovery API", |
| + | "category": "primary", |
| + | "enabled": true, |
| + | "status": "healthy", |
| + | "last_poll_at": "2026-06-22T15:05:01Z", |
| + | "last_success_at": "2026-06-22T15:05:01Z", |
| + | "last_error": null, |
| + | "consecutive_failures": 0, |
| + | "poll_interval_s": 300, |
| + | "tight_interval_s": 10, |
| + | "latency_ms_p50": 142, |
| + | "latency_ms_p95": 380, |
| + | "events_seen_24h": 1842 |
| + | } |
| + | ``` |
| + | `status` ∈ {`healthy`, `degraded`, `down`, `disabled`}. |
| + | |
| + | #### `GET /api/sources/:id` |
| + | One source + timeseries `health[]` (last 24h, 5-min buckets) for sparkline. |
| + | |
| + | #### `PATCH /api/sources/:id` |
| + | Body: `{ "enabled": true }`. Toggles polling. |
| + | |
| + | #### `GET /api/stats` |
| + | Response: |
| + | ```json |
| + | { |
| + | "drops_24h": 87, |
| + | "drops_7d": 612, |
| + | "sources_healthy": 14, |
| + | "sources_total": 18, |
| + | "sources_down": 1, |
| + | "watchlist_matches_24h": 23, |
| + | "detection_latency_ms_p50": 412, |
| + | "detection_latency_ms_p99": 8200, |
| + | "events_tracked": 28471, |
| + | "events_onsale_now": 318 |
| + | } |
| + | ``` |
| + | |
| + | #### `GET /api/explore?q=` |
| + | Proxy to Meilisearch `POST /indexes/events/search` with `{ "q": "<q>", "limit": 25 }`. Return matches with highlight. |
| + | |
| + | #### `GET /api/health` → `200 {"status":"ok"}` |
| + | #### `GET /api/ready` → 200 only if Postgres + NATS + Redis all reachable; else 503. |
| + | |
| + | #### `POST /api/notifications/test` |
| + | Triggers a test push to ntfy. Returns `{ "data": { "sent": true, "topic": "drophawk-drops" } }`. |
| + | |
| + | --- |
| + | |
| + | ## §C. Exact Polling Algorithm |
| + | |
| + | Per-source task pseudocode (Rust). This is the canonical scheduler loop. Implement exactly. |
| + | |
| + | ```rust |
| + | // pseudo-Rust, every detail matters |
| + | async fn run_source_loop(adapter: Arc<dyn SourceAdapter>, state: Arc<AppState>) { |
| + | let mut backoff = ExponentialBackoff::new(Duration::from_secs(2), Duration::from_secs(600)); |
| + | let mut last_known_drops_within_window: Vec<DateTime<Utc>> = vec![]; |
| + | |
| + | loop { |
| + | // 1. Compute next interval using adapter hint |
| + | let now = Utc::now(); |
| + | let ctx = PollContext { now, /* ... */ }; |
| + | let base_interval = adapter.next_poll_hint(&ctx); |
| + | let interval = backoff.next_or(base_interval); |
| + | |
| + | // 2. Acquire rate-limit token from Redis (block until available) |
| + | state.cache.acquire_token(&format!("rl:{}", adapter.id())).await; |
| + | |
| + | // 3. Poll |
| + | let t0 = Instant::now(); |
| + | let result = adapter.poll(&ctx).await; |
| + | let latency = t0.elapsed(); |
| + | |
| + | match result { |
| + | Ok(candidates) => { |
| + | backoff.reset(); |
| + | |
| + | // 4. Persist source_health row (TimescaleDB) |
| + | state.store.record_source_health(SourceHealth { |
| + | source_id: adapter.id().into(), |
| + | observed_at: now, |
| + | ok: true, |
| + | latency_ms: latency.as_millis() as i32, |
| + | events_returned: candidates.len() as i32, |
| + | error: None, |
| + | }).await; |
| + | |
| + | // 5. Detect + emit (see §D, §E) |
| + | for candidate in candidates { |
| + | detect::ingest_candidate(&state, &candidate).await; |
| + | } |
| + | |
| + | // 6. Update sources table |
| + | state.store.mark_source_success(adapter.id(), now).await; |
| + | |
| + | // 7. Reset circuit breaker |
| + | state.metrics.source_poll_total |
| + | .with_label_values(&[adapter.id(), "ok"]).inc(); |
| + | } |
| + | Err(SourceError::RateLimited { retry_after }) => { |
| + | // Honor Retry-After, even if it overrides base interval |
| + | backoff.force_retry_after(retry_after.unwrap_or(Duration::from_secs(60))); |
| + | state.store.mark_source_failure(adapter.id(), "rate_limited").await; |
| + | state.metrics.source_poll_total |
| + | .with_label_values(&[adapter.id(), "rate_limited"]).inc(); |
| + | } |
| + | Err(e) => { |
| + | let failures = state.store.mark_source_failure(adapter.id(), &e.to_string()).await; |
| + | state.metrics.source_poll_total |
| + | .with_label_values(&[adapter.id(), "error"]).inc(); |
| + | // Circuit breaker: 3 → degraded, 10 → down + alert |
| + | if failures == 3 { |
| + | state.store.set_source_status(adapter.id(), "degraded").await; |
| + | state.bus.publish("source.health", SourceHealthEvent::degraded(adapter.id())); |
| + | } else if failures == 10 { |
| + | state.store.set_source_status(adapter.id(), "down").await; |
| + | state.bus.publish("source.health", SourceHealthEvent::down(adapter.id())); |
| + | notify::push_critical(&state, format!("Source {} is DOWN", adapter.name())).await; |
| + | } |
| + | tokio::time::sleep(backoff.next()).await; |
| + | continue; |
| + | } |
| + | } |
| + | |
| + | tokio::time::sleep(interval).await; |
| + | } |
| + | } |
| + | ``` |
| + | |
| + | `ExponentialBackoff`: |
| + | - start: 2s, factor: 2, max: 600s, jitter: ±15% (use `rand` crate `SmallRng` seeded from `Instant::now()`) |
| + | - `force_retry_after(d)` overrides next sleep to exactly `d` (no jitter). |
| + | |
| + | ### C.1 Adaptive interval rule (`next_poll_hint` default impl) |
| + | |
| + | ```rust |
| + | fn next_poll_hint(&self, ctx: &PollContext) -> Duration { |
| + | // Find nearest known on_sale_at for this source within ±24h |
| + | let nearest = ctx.upcoming_drops_for(self.id()) |
| + | .min_by_key(|d| (d - ctx.now()).abs()); |
| + | |
| + | match nearest { |
| + | Some(t) if (t - ctx.now()).num_seconds().abs() <= 900 => Duration::from_secs(10), |
| + | Some(t) if (t - ctx.now()).num_seconds().abs() <= 3600 => Duration::from_secs(30), |
| + | Some(t) if (t - ctx.now()).num_seconds().abs() <= 14400 => Duration::from_secs(60), |
| + | _ => Duration::from_secs(300), |
| + | } |
| + | } |
| + | ``` |
| + | |
| + | Distance-to-drop → interval: |
| + | | Distance | Interval | |
| + | |---|---| |
| + | | ≤ 15 min | **10 s** | |
| + | | ≤ 1 h | 30 s | |
| + | | ≤ 4 h | 60 s | |
| + | | else | 5 min | |
| + | |
| + | ### C.2 Fast-path shock drop detection (Phase 6+) |
| + | For sources where shock drops are likely (FIFA last-minute, Twitter monitor), the source adapter may publish a "wake" signal on NATS subject `wake.{source_id}`. Any Rust poll loop subscribed to its own wake channel short-circuits its sleep. This gives **sub-10-second** detection when a shock drop is detected by a different signal (e.g. tweet lands). |
| + | |
| + | --- |
| + | |
| + | ## §D. Hash Canonicalization (exact bytes) |
| + | |
| + | The `content_hash` is SHA-256 over the canonical JSON of a **fixed field set** in **alphabetical key order** with **specific normalizations**. Implement exactly. |
| + | |
| + | ### D.1 Field set (these and ONLY these participate in hash) |
| + | 1. `source_event_id` (string, trimmed) |
| + | 2. `status` (lowercase enum string) |
| + | 3. `on_sale_at` (RFC3339 UTC, millisecond precision, `null` if None) |
| + | 4. `presale_on_sale_at` (same format) |
| + | 5. `price_min` (int cents, `null` if None) |
| + | 6. `price_max` (int cents, `null` if None) |
| + | 7. `inventory_remaining` (int, `null` if None) |
| + | |
| + | ### D.2 Normalization rules |
| + | - Datetime → format as `YYYY-MM-DDTHH:MM:SS.sssZ` (always 3 ms digits, always `Z`). Strip sub-millisecond precision. |
| + | - Integers stay as integers, never scientific notation. |
| + | - None → JSON `null`. |
| + | - Strings → UTF-8, trimmed of leading/trailing whitespace. |
| + | - All keys sorted lexicographically (use `BTreeMap<&str, Value>`). |
| + | - No whitespace between tokens: `serde_json::to_string` with compact formatter. |
| + | - Output hex lowercase. |
| + | |
| + | ### D.3 Reference implementation |
| + | ```rust |
| + | use serde_json::{json, Value}; |
| + | use sha2::{Digest, Sha256}; |
| + | |
| + | pub fn content_hash(c: &EventCandidate) -> String { |
| + | let canonical = json!({ |
| + | "inventory_remaining": c.inventory_remaining.map(|v| v as i64), |
| + | "on_sale_at": c.on_sale_at.map(|dt| dt.to_rfc3339_opts(SecondsFormat::Millis, true)), |
| + | "presale_on_sale_at": c.presale_on_sale_at.map(|dt| dt.to_rfc3339_opts(SecondsFormat::Millis, true)), |
| + | "price_max": c.price_max, |
| + | "price_min": c.price_min, |
| + | "source_event_id": c.source_event_id.trim(), |
| + | "status": c.status.as_str().to_lowercase(), |
| + | }); |
| + | // serde_json::Map preserves insertion order with preserve_key_order feature. |
| + | // We built it in alphabetical order above to guarantee. |
| + | let bytes = serde_json::to_vec(&canonical).expect("canonical serializable"); |
| + | let mut hasher = Sha256::new(); |
| + | hasher.update(&bytes); |
| + | hex::encode(hasher.finalize()) |
| + | } |
| + | ``` |
| + | |
| + | ### D.4 Golden test (must pass) |
| + | Add `backend/tests/hash_golden.rs` with vectors: |
| + | ```json |
| + | {"inventory_remaining":15234,"on_sale_at":"2026-06-22T15:00:00.000Z","presale_on_sale_at":null,"price_max":89900,"price_min":4950,"source_event_id":"Z1p2q3r4s5t6","status":"onsale"} |
| + | ``` |
| + | → expected hash: `a3f1e8...` (commit the exact hash once the impl is verified; this is the regression gate). |
| + | |
| + | --- |
| + | |
| + | ## §E. Drop Detection & Classification |
| + | |
| + | On every `EventCandidate` ingest: |
| + | |
| + | ```rust |
| + | async fn ingest_candidate(state: &AppState, c: &EventCandidate) { |
| + | let new_hash = content_hash(c); |
| + | |
| + | // 1. Lookup existing event by (source_id, source_event_id) |
| + | let existing = state.store.find_event(c.source_id, &c.source_event_id).await?; |
| + | |
| + | match existing { |
| + | None => { |
| + | // NEW EVENT |
| + | let event_id = state.store.insert_event(c, &new_hash).await?; |
| + | emit_drop(state, DropEvent { |
| + | event_id, |
| + | drop_type: "new", |
| + | from_state: json!(null), |
| + | to_state: json!({"status": c.status, "on_sale_at": c.on_sale_at}), |
| + | }).await; |
| + | } |
| + | Some(prev) if prev.content_hash == new_hash => { |
| + | // UNCHANGED - no-op, just touch updated_at? No, don't even touch. |
| + | return Ok(()); |
| + | } |
| + | Some(prev) => { |
| + | // CHANGED - diff fields, emit one or more drops |
| + | state.store.update_event(prev.id, c, &new_hash).await?; |
| + | |
| + | if prev.status != c.status { |
| + | emit_drop(state, DropEvent { |
| + | event_id: prev.id, |
| + | drop_type: "status", |
| + | from_state: json!({"status": prev.status}), |
| + | to_state: json!({"status": c.status}), |
| + | }).await; |
| + | } |
| + | if let (Some(prev_min), Some(new_min)) = (prev.price_min, c.price_min) { |
| + | if new_min < prev_min && (prev_min - new_min) * 100 / prev_min.max(1) >= 10 { |
| + | emit_drop(state, DropEvent { |
| + | event_id: prev.id, |
| + | drop_type: "price", |
| + | from_state: json!({"price_min": prev_min}), |
| + | to_state: json!({"price_min": new_min}), |
| + | }).await; |
| + | } |
| + | } |
| + | if let (Some(prev_inv), Some(new_inv)) = (prev.inventory_remaining, c.inventory_remaining) { |
| + | if new_inv < prev_inv && (prev_inv - new_inv) * 100 / prev_inv.max(1) >= 25 { |
| + | emit_drop(state, DropEvent { |
| + | event_id: prev.id, |
| + | drop_type: "inventory", |
| + | from_state: json!({"inventory_remaining": prev_inv}), |
| + | to_state: json!({"inventory_remaining": new_inv}), |
| + | }).await; |
| + | } |
| + | } |
| + | } |
| + | } |
| + | } |
| + | ``` |
| + | |
| + | `emit_drop` writes to `drops` table, publishes to NATS `drop.{type}`, broadcasts via SSE channel, and triggers `notify::on_drop`. |
| + | |
| + | A single candidate change can emit multiple drops (e.g. status + price). That's intentional. |
| + | |
| + | --- |
| + | |
| + | ## §F. TLS Fingerprint & Header Coherence |
| + | |
| + | ### F.1 Sources requiring browser impersonation (use `rquest`) |
| + | - FIFA portal, AXS, StubHub, Vivid Seats, Twitter/X scrape, festival portals, all per-club soccer adapters. |
| + | |
| + | ### F.2 Impersonation target rotation |
| + | Use `rquest::Impersonate`: |
| + | - `Chrome131` (default) |
| + | - `Chrome130` |
| + | - `Safari18` |
| + | - `Safari17` |
| + | - `Firefox133` |
| + | |
| + | **Rotation rule:** Each scraper process picks ONE impersonation per session at startup (process-wide). Rotate at restart, not per request - fingerprint stability per IP is what looks human. |
| + | |
| + | ### F.3 Header coherence (CRITICAL) |
| + | The following must always come from the SAME impersonation set - never mix: |
| + | - TLS JA3/JA4 (controlled by rquest) |
| + | - User-Agent |
| + | - `sec-ch-ua`, `sec-ch-ua-mobile`, `sec-ch-ua-platform` |
| + | - `accept-language` |
| + | - `accept-encoding` |
| + | - HTTP/2 settings (controlled by rquest) |
| + | |
| + | Source `scrapers/anti_bot/fingerprints.py` defines named bundles. Each bundle is one tuple. Bundles are checked into the repo as `fingerprints.json`. Update bundles **monthly** by running `scripts/refresh-fingerprints.py` (pulls latest from `wrappers.json` or hand-curated). |
| + | |
| + | ### F.4 Proxy rotation (Phase 6+) |
| + | - Interface: `ProxyPool.pick() -> ProxySpec`. |
| + | - Default impl: single proxy from env (`PROXY_POOL_URL`), or `Direct` if unset. |
| + | - Future impls: BrightData, Smartproxy, self-hosted rotating. |
| + | - Per-source proxy affinity: hash `source_id` → fixed proxy within a 24h window. This gives IP stability per source (looks human) while distributing load across sources. |
| + | |
| + | ### F.5 robots.txt enforcement |
| + | On first poll of any source, fetch and parse `/robots.txt`. Cache in Redis for 24h. If the requested path is disallowed for our UA, **mark source `disabled` and alert operator**. Do not bypass. |
| + | |
| + | --- |
| + | |
| + | ## §G. Complete Database DDL |
| + | |
| + | Replace §8 of SPEC.md with this complete, runnable SQL. |
| + | |
| + | ### G.1 `backend/migrations/20260101000000_extensions.sql` |
| + | ```sql |
| + | CREATE EXTENSION IF NOT EXISTS "pg_trgm"; |
| + | CREATE EXTENSION IF NOT EXISTS timescaledb; |
| + | CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; |
| + | ``` |
| + | |
| + | ### G.2 `20260101000001_sources.sql` |
| + | ```sql |
| + | CREATE TABLE sources ( |
| + | id TEXT PRIMARY KEY, |
| + | name TEXT NOT NULL, |
| + | category TEXT NOT NULL CHECK (category IN ('primary','resale','sports','festival','social')), |
| + | enabled BOOLEAN NOT NULL DEFAULT TRUE, |
| + | status TEXT NOT NULL DEFAULT 'healthy' |
| + | CHECK (status IN ('healthy','degraded','down','disabled')), |
| + | poll_interval_s INTEGER NOT NULL DEFAULT 300 CHECK (poll_interval_s BETWEEN 1 AND 86400), |
| + | tight_interval_s INTEGER NOT NULL DEFAULT 10 CHECK (tight_interval_s BETWEEN 1 AND 3600), |
| + | last_poll_at TIMESTAMPTZ, |
| + | last_success_at TIMESTAMPTZ, |
| + | last_error TEXT, |
| + | consecutive_failures INTEGER NOT NULL DEFAULT 0 CHECK (consecutive_failures >= 0), |
| + | created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), |
| + | updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() |
| + | ); |
| + | |
| + | CREATE TRIGGER sources_set_updated_at |
| + | BEFORE UPDATE ON sources |
| + | FOR EACH ROW EXECUTE FUNCTION set_updated_at(); |
| + | ``` |
| + | |
| + | ### G.3 `20260101000002_set_updated_at_fn.sql` |
| + | ```sql |
| + | CREATE OR REPLACE FUNCTION set_updated_at() RETURNS TRIGGER AS $$ |
| + | BEGIN |
| + | NEW.updated_at := NOW(); |
| + | RETURN NEW; |
| + | END; |
| + | $$ LANGUAGE plpgsql; |
| + | ``` |
| + | |
| + | ### G.4 `20260101000003_events.sql` |
| + | ```sql |
| + | CREATE TABLE events ( |
| + | id BIGSERIAL PRIMARY KEY, |
| + | source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE RESTRICT, |
| + | source_event_id TEXT NOT NULL, |
| + | title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 512), |
| + | subtitle TEXT, |
| + | category TEXT NOT NULL CHECK (category IN ('concert','sports','festival','theater','other')), |
| + | sport TEXT CHECK (sport IS NULL OR sport IN ('nfl','nba','nhl','mlb','tennis','f1','soccer','golf','boxing','other')), |
| + | starts_at TIMESTAMPTZ, |
| + | venue_name TEXT, |
| + | city TEXT, |
| + | country CHAR(2), -- ISO 3166-1 alpha-2 |
| + | latitude DOUBLE PRECISION CHECK (latitude IS NULL OR (latitude BETWEEN -90 AND 90)), |
| + | longitude DOUBLE PRECISION CHECK (longitude IS NULL OR (longitude BETWEEN -180 AND 180)), |
| + | image_url TEXT, |
| + | on_sale_at TIMESTAMPTZ, |
| + | presale_on_sale_at TIMESTAMPTZ, |
| + | status TEXT NOT NULL CHECK (status IN ('announced','presale','onsale','soldout','cancelled')), |
| + | price_min INTEGER CHECK (price_min IS NULL OR price_min >= 0), |
| + | price_max INTEGER CHECK (price_max IS NULL OR price_max >= 0), |
| + | currency CHAR(3), -- ISO 4217 |
| + | inventory_remaining INTEGER CHECK (inventory_remaining IS NULL OR inventory_remaining >= 0), |
| + | buy_url TEXT NOT NULL, |
| + | raw JSONB, |
| + | content_hash CHAR(64) NOT NULL, |
| + | first_seen_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), |
| + | updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), |
| + | UNIQUE (source_id, source_event_id), |
| + | CONSTRAINT price_range CHECK (price_min IS NULL OR price_max IS NULL OR price_min <= price_max) |
| + | ); |
| + | |
| + | CREATE INDEX idx_events_status ON events(status); |
| + | CREATE INDEX idx_events_on_sale ON events(on_sale_at) WHERE on_sale_at IS NOT NULL; |
| + | CREATE INDEX idx_events_category ON events(category); |
| + | CREATE INDEX idx_events_sport ON events(sport) WHERE sport IS NOT NULL; |
| + | CREATE INDEX idx_events_starts_at ON events(starts_at) WHERE starts_at IS NOT NULL; |
| + | CREATE INDEX idx_events_source_status ON events(source_id, status); |
| + | CREATE INDEX idx_events_updated_at ON events(updated_at DESC); |
| + | CREATE INDEX idx_events_title_trgm ON events USING gin (title gin_trgm_ops); |
| + | CREATE INDEX idx_events_starts_at_source ON events(starts_at, source_id); |
| + | |
| + | CREATE TRIGGER events_set_updated_at |
| + | BEFORE UPDATE ON events |
| + | FOR EACH ROW EXECUTE FUNCTION set_updated_at(); |
| + | ``` |
| + | |
| + | ### G.5 `20260101000004_drops.sql` |
| + | ```sql |
| + | CREATE TABLE drops ( |
| + | id BIGSERIAL PRIMARY KEY, |
| + | event_id BIGINT NOT NULL REFERENCES events(id) ON DELETE CASCADE, |
| + | drop_type TEXT NOT NULL CHECK (drop_type IN ('new','status','price','inventory','announcement')), |
| + | from_state JSONB, |
| + | to_state JSONB NOT NULL, |
| + | detected_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), |
| + | detected_at_ms BIGINT GENERATED ALWAYS AS (EXTRACT(EPOCH FROM detected_at) * 1000) STORED, |
| + | notified BOOLEAN NOT NULL DEFAULT FALSE, |
| + | notified_at TIMESTAMPTZ |
| + | ); |
| + | |
| + | CREATE INDEX idx_drops_detected_desc ON drops(detected_at DESC); |
| + | CREATE INDEX idx_drops_event ON drops(event_id); |
| + | CREATE INDEX idx_drops_type ON drops(drop_type); |
| + | CREATE INDEX idx_drops_type_detected ON drops(drop_type, detected_at DESC); |
| + | |
| + | -- TimescaleDB hypertable (drops grow fast; partition by time) |
| + | SELECT create_hypertable('drops', 'detected_at', chunk_time_interval => INTERVAL '1 day'); |
| + | ``` |
| + | |
| + | ### G.6 `20260101000005_watchlist.sql` |
| + | ```sql |
| + | CREATE TABLE watchlist ( |
| + | id BIGSERIAL PRIMARY KEY, |
| + | kind TEXT NOT NULL CHECK (kind IN ('artist','team','venue','sport','category','keyword','twitter_account')), |
| + | pattern TEXT NOT NULL, -- Rust regex syntax |
| + | label TEXT NOT NULL CHECK (length(label) BETWEEN 1 AND 128), |
| + | active BOOLEAN NOT NULL DEFAULT TRUE, |
| + | priority TEXT NOT NULL DEFAULT 'normal' CHECK (priority IN ('low','normal','high','critical')), |
| + | created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), |
| + | updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), |
| + | UNIQUE (kind, pattern) |
| + | ); |
| + | |
| + | CREATE INDEX idx_watchlist_active_kind ON watchlist(active, kind); |
| + | CREATE TRIGGER watchlist_set_updated_at |
| + | BEFORE UPDATE ON watchlist |
| + | FOR EACH ROW EXECUTE FUNCTION set_updated_at(); |
| + | ``` |
| + | |
| + | ### G.7 `20260101000006_notifications.sql` |
| + | ```sql |
| + | CREATE TABLE notifications_log ( |
| + | id BIGSERIAL PRIMARY KEY, |
| + | drop_id BIGINT REFERENCES drops(id) ON DELETE SET NULL, |
| + | channel TEXT NOT NULL CHECK (channel IN ('ntfy','telegram','email','browser')), |
| + | title TEXT NOT NULL, |
| + | body TEXT NOT NULL, |
| + | priority TEXT NOT NULL CHECK (priority IN ('min','low','default','high','urgent')), |
| + | sent_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), |
| + | success BOOLEAN NOT NULL, |
| + | response TEXT, |
| + | topic TEXT |
| + | ); |
| + | |
| + | CREATE INDEX idx_notif_sent_desc ON notifications_log(sent_at DESC); |
| + | CREATE INDEX idx_notif_drop ON notifications_log(drop_id); |
| + | SELECT create_hypertable('notifications_log', 'sent_at', chunk_time_interval => INTERVAL '7 days'); |
| + | ``` |
| + | |
| + | ### G.8 `20260101000007_timeseries.sql` |
| + | ```sql |
| + | CREATE TABLE price_history ( |
| + | event_id BIGINT NOT NULL REFERENCES events(id) ON DELETE CASCADE, |
| + | source TEXT NOT NULL, |
| + | observed_at TIMESTAMPTZ NOT NULL, |
| + | price_min INTEGER, |
| + | price_max INTEGER, |
| + | currency CHAR(3) |
| + | ); |
| + | SELECT create_hypertable('price_history', 'observed_at', chunk_time_interval => INTERVAL '7 days'); |
| + | CREATE INDEX idx_price_event_time ON price_history(event_id, observed_at DESC); |
| + | |
| + | CREATE TABLE source_health ( |
| + | source_id TEXT NOT NULL, |
| + | observed_at TIMESTAMPTZ NOT NULL, |
| + | ok BOOLEAN NOT NULL, |
| + | latency_ms INTEGER NOT NULL CHECK (latency_ms >= 0), |
| + | events_returned INTEGER NOT NULL DEFAULT 0, |
| + | error TEXT |
| + | ); |
| + | SELECT create_hypertable('source_health', 'observed_at', chunk_time_interval => INTERVAL '1 day'); |
| + | CREATE INDEX idx_health_source_time ON source_health(source_id, observed_at DESC); |
| + | |
| + | -- Continuous aggregates for UI sparklines |
| + | CREATE MATERIALIZED VIEW source_health_5min |
| + | WITH (timescaledb.continuous) AS |
| + | SELECT |
| + | source_id, |
| + | time_bucket('5 minutes', observed_at) AS bucket, |
| + | AVG(latency_ms) AS latency_ms_p50, |
| + | MAX(latency_ms) AS latency_ms_p95, |
| + | COUNT(*) FILTER (WHERE ok) AS ok_count, |
| + | COUNT(*) FILTER (WHERE NOT ok) AS err_count |
| + | FROM source_health |
| + | GROUP BY source_id, bucket |
| + | WITH NO DATA; |
| + | |
| + | SELECT add_continuous_aggregate_policy('source_health_5min', |
| + | start_offset => INTERVAL '1 hour', |
| + | end_offset => INTERVAL '5 minutes', |
| + | schedule_interval => INTERVAL '1 minute'); |
| + | ``` |
| + | |
| + | ### G.9 `20260101000008_detection_latency.sql` |
| + | ```sql |
| + | -- Histogram for the detection_latency_ms metric (SLO §O.3) |
| + | CREATE TABLE detection_latency ( |
| + | drop_id BIGINT PRIMARY KEY REFERENCES drops(id) ON DELETE CASCADE, |
| + | latency_ms INTEGER NOT NULL CHECK (latency_ms >= 0) |
| + | ); |
| + | CREATE INDEX idx_latency ON detection_latency(latency_ms); |
| + | ``` |
| + | |
| + | ### G.10 `20260101000009_cross_source_links.sql` (see §Q) |
| + | ```sql |
| + | CREATE TABLE cross_source_links ( |
| + | cluster_id BIGSERIAL PRIMARY KEY, |
| + | event_id BIGINT NOT NULL REFERENCES events(id) ON DELETE CASCADE, |
| + | confidence REAL NOT NULL CHECK (confidence BETWEEN 0 AND 1), |
| + | match_basis TEXT NOT NULL, -- 'date+venue' | 'performer_id' | 'title+date' |
| + | created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), |
| + | UNIQUE (cluster_id, event_id) |
| + | ); |
| + | CREATE INDEX idx_xsrc_event ON cross_source_links(event_id); |
| + | CREATE INDEX idx_xsrc_cluster ON cross_source_links(cluster_id); |
| + | ``` |
| + | |
| + | ### G.11 `20260101000010_seed_sources.sql` |
| + | ```sql |
| + | INSERT INTO sources (id, name, category, enabled, poll_interval_s, tight_interval_s) VALUES |
| + | ('ticketmaster', 'Ticketmaster Discovery API', 'primary', TRUE, 300, 10), |
| + | ('seatgeek', 'SeatGeek', 'primary', TRUE, 300, 10), |
| + | ('fifa', 'FIFA World Cup Portal', 'sports', TRUE, 60, 30), |
| + | ('axs', 'AXS', 'primary', FALSE, 300, 10), |
| + | ('seetickets', 'See Tickets', 'primary', FALSE, 300, 10), |
| + | ('stubhub', 'StubHub (resale)', 'resale', FALSE, 600, 30), |
| + | ('vividseats', 'Vivid Seats (resale)', 'resale', FALSE, 600, 30), |
| + | ('twitter', 'Twitter/X Shock Drop', 'social', FALSE, 120, 15), |
| + | ('nfl', 'NFL (Ticketmaster Sports)', 'sports', FALSE, 300, 10), |
| + | ('nba', 'NBA', 'sports', FALSE, 300, 10), |
| + | ('nhl', 'NHL', 'sports', FALSE, 300, 10), |
| + | ('mlb', 'MLB', 'sports', FALSE, 300, 10), |
| + | ('atp_wta', 'ATP / WTA Tennis', 'sports', FALSE, 600, 30), |
| + | ('f1', 'Formula 1', 'sports', FALSE, 600, 30), |
| + | ('uefa', 'UEFA', 'sports', FALSE, 600, 30), |
| + | ('epl', 'Premier League (Big 6)', 'sports', FALSE, 600, 30), |
| + | ('coachella', 'Coachella', 'festival',FALSE, 600, 30), |
| + | ('glastonbury', 'Glastonbury', 'festival',FALSE, 600, 30), |
| + | ('tomorrowland', 'Tomorrowland', 'festival',FALSE, 600, 30), |
| + | ('edc', 'EDC', 'festival',FALSE, 600, 30), |
| + | ('lollapalooza', 'Lollapalooza', 'festival',FALSE, 600, 30) |
| + | ON CONFLICT (id) DO NOTHING; |
| + | |
| + | INSERT INTO watchlist (kind, pattern, label, priority) VALUES |
| + | ('keyword', '(?i)\btaylor\s+swift\b', 'Taylor Swift', 'critical'), |
| + | ('keyword', '(?i)\bworld\s+cup\b', 'World Cup', 'critical'), |
| + | ('keyword', '(?i)\bsuper\s+bowl\b', 'Super Bowl', 'critical'), |
| + | ('keyword', '(?i)\bwimbledon\b', 'Wimbledon', 'high'), |
| + | ('keyword', '(?i)\bchampions\s+league\s+final\b', 'UCL Final', 'high') |
| + | ON CONFLICT (kind, pattern) DO NOTHING; |
| + | ``` |
| + | |
| + | ### G.12 Retention policy |
| + | ```sql |
| + | -- Drop old data automatically (TimescaleDB) |
| + | SELECT add_retention_policy('drops', INTERVAL '90 days'); |
| + | SELECT add_retention_policy('price_history', INTERVAL '1 year'); |
| + | SELECT add_retention_policy('source_health', INTERVAL '30 days'); |
| + | SELECT add_retention_policy('notifications_log', INTERVAL '90 days'); |
| + | ``` |
| + | |
| + | ### G.13 Migration runner |
| + | - sqlx migrate run on startup, before Axum binds. |
| + | - Migrations are immutable. Never edit. Always forward-only. |
| + | |
| + | --- |
| + | |
| + | ## §H. Design Tokens (exact, OKLCH) |
| + | |
| + | ### H.1 Tailwind 4 setup - `frontend/app/globals.css` |
| + | **Tailwind v4 is CSS-first. There is no `tailwind.config.ts`.** Configuration lives in `@theme` blocks. This is the full theme file. |
| + | |
| + | ```css |
| + | @import "tailwindcss"; |
| + | |
| + | @theme { |
| + | /* === Color system (OKLCH, dark-first) === */ |
| + | /* Backgrounds */ |
| + | --color-bg-base: oklch(0.16 0.012 264); /* page bg, deep navy-black */ |
| + | --color-bg-elevated: oklch(0.20 0.014 264); /* card bg */ |
| + | --color-bg-overlay: oklch(0.23 0.014 264); /* modal/sheet */ |
| + | --color-bg-inset: oklch(0.14 0.012 264); /* recessed area */ |
| + | |
| + | /* Foregrounds */ |
| + | --color-fg-primary: oklch(0.96 0.005 264); |
| + | --color-fg-secondary: oklch(0.78 0.008 264); |
| + | --color-fg-tertiary: oklch(0.60 0.010 264); |
| + | --color-fg-disabled: oklch(0.42 0.008 264); |
| + | |
| + | /* Borders */ |
| + | --color-border-subtle: oklch(0.28 0.014 264 / 0.6); |
| + | --color-border-default: oklch(0.34 0.014 264); |
| + | --color-border-strong: oklch(0.46 0.014 264); |
| + | |
| + | /* Accents (semantic) */ |
| + | --color-accent-teal: oklch(0.78 0.16 184); /* primary action */ |
| + | --color-accent-teal-hover: oklch(0.72 0.18 184); |
| + | --color-accent-teal-soft: oklch(0.78 0.16 184 / 0.12); |
| + | --color-accent-amber: oklch(0.82 0.16 75); /* warnings */ |
| + | --color-accent-red: oklch(0.66 0.22 25); /* sold out / error */ |
| + | --color-accent-violet: oklch(0.70 0.18 300); /* presale */ |
| + | --color-accent-green: oklch(0.74 0.18 145); /* healthy / on-sale */ |
| + | --color-accent-blue: oklch(0.70 0.16 240); /* informational */ |
| + | |
| + | /* Status pills map */ |
| + | --color-status-announced: var(--color-accent-blue); |
| + | --color-status-presale: var(--color-accent-violet); |
| + | --color-status-onsale: var(--color-accent-green); |
| + | --color-status-soldout: var(--color-accent-red); |
| + | --color-status-cancelled: var(--color-fg-tertiary); |
| + | |
| + | /* === Typography === */ |
| + | --font-sans: "Inter", "Inter Placeholder", ui-sans-serif, system-ui, sans-serif; |
| + | --font-mono: "JetBrains Mono", ui-monospace, "SF Mono", monospace; |
| + | |
| + | /* Type scale (1.250 major third) */ |
| + | --text-xs: 0.64rem; --text-xs--line-height: 1rem; |
| + | --text-sm: 0.80rem; --text-sm--line-height: 1.25rem; |
| + | --text-base: 1.00rem; --text-base--line-height: 1.5rem; |
| + | --text-lg: 1.25rem; --text-lg--line-height: 1.75rem; |
| + | --text-xl: 1.56rem; --text-xl--line-height: 2rem; |
| + | --text-2xl: 1.95rem; --text-2xl--line-height: 2.25rem; |
| + | --text-3xl: 2.44rem; --text-3xl--line-height: 2.75rem; |
| + | --text-4xl: 3.05rem; --text-4xl--line-height: 3.25rem; |
| + | |
| + | /* Letter spacing for headings */ |
| + | --tracking-tight: -0.02em; |
| + | --tracking-display: -0.04em; |
| + | |
| + | /* === Spacing scale (4px base) === */ |
| + | --spacing: 0.25rem; /* 4px - Tailwind v4 default, do not change */ |
| + | |
| + | /* === Radii === */ |
| + | --radius-sm: 0.375rem; |
| + | --radius: 0.5rem; |
| + | --radius-md: 0.625rem; |
| + | --radius-lg: 0.875rem; |
| + | --radius-xl: 1.25rem; |
| + | |
| + | /* === Shadows (use sparingly; prefer borders) === */ |
| + | --shadow-card: 0 1px 2px 0 oklch(0 0 0 / 0.06), 0 1px 3px 0 oklch(0 0 0 / 0.10); |
| + | --shadow-pop: 0 8px 24px -8px oklch(0 0 0 / 0.40); |
| + | --shadow-glow-teal: 0 0 0 1px var(--color-accent-teal-soft), 0 0 24px -4px var(--color-accent-teal-soft); |
| + | |
| + | /* === Motion === */ |
| + | /* Framer Motion springs (exported to TS) */ |
| + | --motion-spring-snappy: cubic-bezier(0.22, 1, 0.36, 1); /* ease-out-expo */ |
| + | --motion-spring-natural: cubic-bezier(0.16, 1, 0.3, 1); |
| + | --motion-spring-entrance: cubic-bezier(0.34, 1.56, 0.64, 1); /* slight overshoot */ |
| + | |
| + | /* Durations */ |
| + | --duration-instant: 80ms; |
| + | --duration-fast: 150ms; |
| + | --duration-base: 240ms; |
| + | --duration-slow: 400ms; |
| + | --duration-cinematic: 800ms; |
| + | |
| + | /* === Z-index scale === */ |
| + | --z-base: 0; |
| + | --z-sticky: 10; |
| + | --z-dropdown:1000; |
| + | --z-sheet: 2000; |
| + | --z-modal: 3000; |
| + | --z-toast: 4000; |
| + | --z-tooltip: 5000; |
| + | } |
| + | |
| + | /* === Base layer === */ |
| + | @layer base { |
| + | html { color-scheme: dark; } |
| + | body { |
| + | background-color: var(--color-bg-base); |
| + | color: var(--color-fg-primary); |
| + | font-family: var(--font-sans); |
| + | font-feature-settings: "cv11", "ss01", "ss03"; |
| + | -webkit-font-smoothing: antialiased; |
| + | text-rendering: optimizeLegibility; |
| + | } |
| + | |
| + | /* Numeric data uses tabular figures */ |
| + | .tabular { font-variant-numeric: tabular-nums; } |
| + | |
| + | /* Selection */ |
| + | ::selection { background-color: var(--color-accent-teal-soft); } |
| + | |
| + | /* Scrollbar (WebKit) */ |
| + | ::-webkit-scrollbar { width: 10px; height: 10px; } |
| + | ::-webkit-scrollbar-track { background: var(--color-bg-base); } |
| + | ::-webkit-scrollbar-thumb { |
| + | background: var(--color-border-default); |
| + | border-radius: 999px; |
| + | border: 2px solid var(--color-bg-base); |
| + | } |
| + | ::-webkit-scrollbar-thumb:hover { background: var(--color-border-strong); } |
| + | |
| + | /* Reduced motion */ |
| + | @media (prefers-reduced-motion: reduce) { |
| + | *, *::before, *::after { |
| + | animation-duration: 0.01ms !important; |
| + | animation-iteration-count: 1 !important; |
| + | transition-duration: 0.01ms !important; |
| + | } |
| + | } |
| + | } |
| + | |
| + | /* === Utilities === */ |
| + | @layer utilities { |
| + | .animate-shimmer { |
| + | background: linear-gradient(90deg, |
| + | transparent 0%, |
| + | var(--color-accent-teal-soft) 50%, |
| + | transparent 100%); |
| + | background-size: 200% 100%; |
| + | animation: shimmer 1.2s ease-out; |
| + | } |
| + | @keyframes shimmer { |
| + | 0% { background-position: 200% 0; } |
| + | 100% { background-position: -200% 0; } |
| + | } |
| + | |
| + | .pulse-ring::after { |
| + | content: ""; |
| + | position: absolute; |
| + | inset: 0; |
| + | border-radius: inherit; |
| + | box-shadow: 0 0 0 0 var(--color-accent-green); |
| + | animation: pulse-ring 2s var(--motion-spring-natural) infinite; |
| + | } |
| + | @keyframes pulse-ring { |
| + | 0% { box-shadow: 0 0 0 0 oklch(0.74 0.18 145 / 0.6); } |
| + | 100% { box-shadow: 0 0 0 12px oklch(0.74 0.18 145 / 0); } |
| + | } |
| + | } |
| + | ``` |
| + | |
| + | ### H.2 Type scale → Tailwind utility mapping |
| + | Use Tailwind v4's automatic theme→utility mapping: `text-xs`, `text-sm`, …, `text-4xl` are auto-generated from the `--text-*` vars above. No `tailwind.config.ts` needed. |
| + | |
| + | ### H.3 Framer Motion spring presets (`frontend/lib/motion.ts`) |
| + | ```ts |
| + | export const springs = { |
| + | snappy: { type: "spring", stiffness: 580, damping: 32, mass: 0.8 }, |
| + | natural: { type: "spring", stiffness: 320, damping: 28, mass: 1.0 }, |
| + | entrance: { type: "spring", stiffness: 240, damping: 18, mass: 1.2 }, // slight overshoot |
| + | sheet: { type: "spring", stiffness: 280, damping: 34, mass: 1.0 }, |
| + | stagger: { type: "spring", stiffness: 480, damping: 30, mass: 0.6 }, |
| + | } as const; |
| + | |
| + | export const dropCardVariants = { |
| + | initial: { opacity: 0, y: -16, scale: 0.96 }, |
| + | animate: { opacity: 1, y: 0, scale: 1, transition: springs.entrance }, |
| + | exit: { opacity: 0, x: 24, scale: 0.92, transition: { duration: 0.18 } }, |
| + | } as const; |
| + | |
| + | export const flashAccentKeyframes = { |
| + | boxShadow: [ |
| + | "0 0 0 0 oklch(0.78 0.16 184 / 0)", |
| + | "0 0 0 4px oklch(0.78 0.16 184 / 0.5)", |
| + | "0 0 0 0 oklch(0.78 0.16 184 / 0)", |
| + | ], |
| + | transition: { duration: 1.6, ease: "easeOut", times: [0, 0.2, 1] }, |
| + | }; |
| + | ``` |
| + | |
| + | ### H.4 Status pill component (`components/ui/StatusPill.tsx`) |
| + | - Padding `px-2.5 py-0.5`, radius `--radius-sm`, font `text-xs font-medium`, tabular nums off. |
| + | - Bg = `color-status-{status}` at 12% alpha. Text = same color at 100%. |
| + | - Border = same color at 25% alpha. |
| + | - Includes leading 6px dot. |
| + | - All variants tested against contrast ratio ≥ 4.5:1 against `--color-bg-elevated` (WCAG §U). |
| + | |
| + | ### H.5 DropCard layout (canonical) |
| + | ``` |
| + | ┌──────────────────────────────────────────────────────┐ |
| + | │ [●] On Sale 3s ago │ ← status pill + relative time (mono) |
| + | ├──────────────────────────────────────────────────────┤ |
| + | │ [IMG 64×64] Taylor Swift | The Eras Tour │ |
| + | │ with Paramore │ |
| + | │ Hard Rock Stadium · Miami Gardens │ |
| + | ├──────────────────────────────────────────────────────┤ |
| + | │ $49.50 - $899.00 [TM] [ Buy → ] │ ← price + source chip + button |
| + | └──────────────────────────────────────────────────────┘ |
| + | ``` |
| + | - Card padding `p-3.5`, gap between sections `gap-2`. |
| + | - New cards: animate in from top with `entrance` spring; flash teal ring for 1.6s. |
| + | - Source chip: 24×24 logo or initials; tooltip shows source name. |
| + | |
| + | ### H.6 Motion budget (do not exceed) |
| + | - Max simultaneous animations on dashboard: **40** (use `will-change: transform` sparingly). |
| + | - No animation longer than 1.6s except skeleton shimmer (3s loop max). |
| + | - Exit animations: ≤200ms. |
| + | |
| + | --- |
| + | |
| + | ## §I. ntfy Payload Templates (exact) |
| + | |
| + | ### I.1 Per drop type - full HTTP request |
| + | |
| + | **Status flip (Announced → OnSale), watchlist match:** |
| + | ```http |
| + | POST /drophawk-drops HTTP/1.1 |
| + | Host: ntfy |
| + | Authorization: Bearer tk_xxxxxxxxxxxxxxxxxxxxxxxx |
| + | Title: 🎟️ ON SALE NOW: Taylor Swift - Miami |
| + | Priority: urgent |
| + | Tags: ticket,ticket,concert,ticketmaster |
| + | Click: https://www.ticketmaster.com/event/Z1p2q3r4s5t6?drophawk=1 |
| + | Actions: [{"action":"view","label":"Buy","url":"https://www.ticketmaster.com/event/Z1p2q3r4s5t6?drophawk=1"}] |
| + | Cache: no |
| + | |
| + | Floor seats from $49.50 · 15,234 remaining |
| + | Hard Rock Stadium · Aug 12 2026, 7:00 PM ET |
| + | Source: Ticketmaster · detected in 1.2s |
| + | ``` |
| + | |
| + | **New event (matching watchlist):** |
| + | ``` |
| + | Title: 🆕 NEW: FIFA World Cup 2026 Final - NYC |
| + | Priority: high |
| + | Tags: soccer,fifa,world_cup |
| + | Click: https://tickets.fifa.com/... |
| + | ``` |
| + | |
| + | **Price drop ≥25%:** |
| + | ``` |
| + | Title: 📉 -32%: Adele - Munich (StubHub) |
| + | Priority: high |
| + | Tags: arrow_down,concert,stubhub |
| + | ``` |
| + | |
| + | **Shock drop (Twitter-triggered, on_sale_at within ±5min of now):** |
| + | ``` |
| + | Title: ⚡ SHOCK DROP: Beyoncé added second London show |
| + | Priority: urgent |
| + | Tags: zap,concert,twitter |
| + | ``` |
| + | |
| + | **Test push (`POST /api/notifications/test`):** |
| + | ``` |
| + | Title: ✅ DropHawk ntfy test |
| + | Priority: default |
| + | Tags: white_check_mark |
| + | Body: If you can read this, your pipeline works. Detected at {RFC3339 now}. |
| + | ``` |
| + | |
| + | ### I.2 Priority mapping (LOCKED) |
| + | | Drop signal | Watchlist priority | ntfy Priority | |
| + | |---|---|---| |
| + | | status→onsale | critical | `urgent` | |
| + | | status→onsale | high | `high` | |
| + | | status→onsale | normal/low | `default` | |
| + | | new (watchlist match) | critical | `urgent` | |
| + | | new (watchlist match) | high | `high` | |
| + | | new (watchlist match) | normal | `default` | |
| + | | new (no match) | - | **not sent** (UI only) | |
| + | | price ≥25% drop | any | `high` | |
| + | | price 10-25% drop | any | `default` | |
| + | | inventory ≥25% drop | any | `default` | |
| + | | shock drop (Twitter) | any | `urgent` | |
| + | |
| + | ### I.3 Dedupe rules (anti-spam) |
| + | - One ntfy push per `(event_id, drop_type)` per **10 minutes** (Redis key `notif:dedupe:{event_id}:{drop_type}` with TTL 600s). |
| + | - Max 5 notifications per minute total (token bucket). |
| + | - Max 50 per hour. |
| + | - If exceeded: drop quietly, log to `notifications_log` with `success=false, response='rate_limited_self'`. |
| + | - Quiet hours (configurable in Settings): default OFF (operator wants to wake up). When on, only `urgent` priority breaks through. |
| + | |
| + | ### I.4 ntfy server config (`infra/ntfy.server.yml`) |
| + | ```yaml |
| + | base_url: "http://ntfy" |
| + | listen: ":80" |
| + | cache_file: "/var/lib/ntfy/cache.db" |
| + | auth_file: "/var/lib/ntfy/user.db" |
| + | auth_default_access: "deny-all" |
| + | |
| + | # Behind Caddy already terminates TLS, so internal is HTTP |
| + | behind_proxy: true |
| + | |
| + | # Attachment limits (we don't use attachments for pushes) |
| + | attachment_total_size_limit: "1M" |
| + | attachment_file_size_limit: "512K" |
| + | |
| + | # Rate limit (per-IP; we don't actually want to limit our own internal publisher, |
| + | # so set high) |
| + | global_topic_limit: 1000 |
| + | visitor_request_limit_burst: 100 |
| + | visitor_request_limit_replenish: "1s" |
| + | |
| + | # Enable SMTP? No, not for v1. |
| + | ``` |
| + | |
| + | Create admin + publisher tokens at deploy time via `ntfy user add` and `ntfy token create` (one-shot, persisted in MinIO backup bucket for restore). |
| + | |
| + | --- |
| + | |
| + | ## §J. Prometheus Metrics Catalog |
| + | |
| + | Every metric prefixed `drophawk_`. All histograms use these standard buckets (ms): `[10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000]`. |
| + | |
| + | ### J.1 Counters |
| + | | Metric | Labels | When | |
| + | |---|---|---| |
| + | | `drophawk_source_poll_total` | `source`, `result`(ok/error/rate_limited) | end of every poll | |
| + | | `drophawk_drops_total` | `type`, `category`, `source` | every emit_drop | |
| + | | `drophawk_notifications_total` | `channel`, `priority`, `result`(ok/failed/skipped) | every notify attempt | |
| + | | `drophawk_sse_connections` | - | gauge (current count) | |
| + | | `drophawk_events_total` | - | gauge (current row count in events) | |
| + | |
| + | ### J.2 Histograms |
| + | | Metric | Labels | When | |
| + | |---|---|---| |
| + | | `drophawk_source_poll_duration_ms` | `source` | every poll | |
| + | | `drophawk_detection_latency_ms` | `type` | drop → notification | |
| + | | `drophawk_notify_latency_ms` | `channel` | notify send → ntfy ack | |
| + | | `drophawk_http_request_duration_ms` | `method`, `route`, `status` | every HTTP request | |
| + | | `drophawk_scraper_round_trip_ms` | `source` | every NATS RPC | |
| + | |
| + | ### J.3 Gauges |
| + | | Metric | Labels | When | |
| + | |---|---|---| |
| + | | `drophawk_source_up` | `source`, `status`(healthy/degraded/down) | on status change | |
| + | | `drophawk_watchlist_rules_active` | - | on rule change | |
| + | | `drophawk_db_connections_in_use` | - | every 5s | |
| + | | `drophawk_nats_unprocessed_messages` | `stream`, `consumer` | every 5s | |
| + | | `drophawk_redis_ops_per_sec` | - | every 5s | |
| + | |
| + | ### J.4 SLOs |
| + | - **Detection latency p99 ≤ 15s** (alert at p99 > 30s for 5m) |
| + | - **Source health: ≥ 90% of enabled sources `healthy`** (alert at <75%) |
| + | - **Notification success rate ≥ 99.5%** over 1h (alert at <98%) |
| + | - **SSE uptime 99.9%** (alert on 0 connected clients for 5m when backend is up) |
| + | |
| + | ### J.5 Alertmanager rules (`infra/alerts.yml`) |
| + | ```yaml |
| + | groups: |
| + | - name: drophawk |
| + | rules: |
| + | - alert: DropHawkHighDetectionLatency |
| + | expr: histogram_quantile(0.99, sum(rate(drophawk_detection_latency_ms_bucket[5m])) by (le)) > 30000 |
| + | for: 5m |
| + | annotations: |
| + | summary: "p99 detection latency > 30s" |
| + | |
| + | - alert: DropHawkSourcesDown |
| + | expr: count(drophawk_source_up{status="down"} == 1) > 0 |
| + | for: 10m |
| + | annotations: |
| + | summary: "{{ $value }} source(s) are DOWN" |
| + | |
| + | - alert: DropHawkNotifyFailures |
| + | expr: rate(drophawk_notifications_total{result="failed"}[5m]) / rate(drophawk_notifications_total[5m]) > 0.02 |
| + | for: 10m |
| + | annotations: |
| + | summary: "Notification failure rate > 2%" |
| + | |
| + | - alert: DropHawkPostgresDown |
| + | expr: pg_up == 0 |
| + | for: 1m |
| + | labels: { severity: critical } |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## §K. Error Taxonomy (Rust) |
| + | |
| + | ```rust |
| + | use thiserror::Error; |
| + | |
| + | #[derive(Debug, Error)] |
| + | pub enum AppError { |
| + | #[error("database error: {0}")] |
| + | Db(#[from] sqlx::Error), |
| + | |
| + | #[error("nats publish error: {0}")] |
| + | Bus(#[from] async_nats::PublishError), |
| + | |
| + | #[error("redis error: {0}")] |
| + | Cache(#[from] redis::RedisError), |
| + | |
| + | #[error("http client error: {0}")] |
| + | Http(#[from] reqwest::Error), |
| + | |
| + | #[error("json error: {0}")] |
| + | Json(#[from] serde_json::Error), |
| + | |
| + | #[error("validation failed: {0}")] |
| + | Validation(String), |
| + | |
| + | #[error("not found: {0}")] |
| + | NotFound(String), |
| + | |
| + | #[error("conflict: {0}")] |
| + | Conflict(String), |
| + | |
| + | #[error("rate limited")] |
| + | RateLimited, |
| + | |
| + | #[error("upstream unavailable: {0}")] |
| + | Upstream(String), |
| + | |
| + | #[error("internal error: {0}")] |
| + | Internal(#[from] anyhow::Error), |
| + | } |
| + | |
| + | impl AppError { |
| + | pub fn status_code(&self) -> u16 { |
| + | use AppError::*; |
| + | match self { |
| + | Validation(_) => 422, |
| + | NotFound(_) => 404, |
| + | Conflict(_) => 409, |
| + | RateLimited => 429, |
| + | Upstream(_) => 503, |
| + | _ => 500, |
| + | } |
| + | } |
| + | pub fn code(&self) -> &'static str { |
| + | use AppError::*; |
| + | match self { |
| + | Db(_) => "DB_ERROR", |
| + | Bus(_) => "BUS_ERROR", |
| + | Cache(_) => "CACHE_ERROR", |
| + | Http(_) => "HTTP_ERROR", |
| + | Json(_) => "JSON_ERROR", |
| + | Validation(_) => "VALIDATION_FAILED", |
| + | NotFound(_) => "NOT_FOUND", |
| + | Conflict(_) => "CONFLICT", |
| + | RateLimited => "RATE_LIMITED", |
| + | Upstream(_) => "UPSTREAM_UNAVAILABLE", |
| + | Internal(_) => "INTERNAL", |
| + | } |
| + | } |
| + | } |
| + | |
| + | // IntoResponse impl for Axum |
| + | impl IntoResponse for AppError { |
| + | fn into_response(self) -> Response { |
| + | let code = self.code(); |
| + | let status = StatusCode::from_u16(self.status_code()).unwrap_or(StatusCode::INTERNAL_SERVER_ERROR); |
| + | let body = Json(json!({ "error": { "code": code, "message": self.to_string() } })); |
| + | (status, body).into_response() |
| + | } |
| + | } |
| + | |
| + | pub type AppResult<T> = Result<T, AppError>; |
| + | ``` |
| + | |
| + | ### K.1 Source errors (separate, internal) |
| + | ```rust |
| + | #[derive(Debug, Error)] |
| + | pub enum SourceError { |
| + | #[error("network error: {0}")] |
| + | Network(String), |
| + | #[error("parse error: {0}")] |
| + | Parse(String), |
| + | #[error("rate limited; retry after {retry_after:?}")] |
| + | RateLimited { retry_after: Option<Duration> }, |
| + | #[error("blocked by source (403/429): {0}")] |
| + | Blocked(String), |
| + | #[error("source returned invalid auth")] |
| + | Auth, |
| + | #[error("upstream error {status}: {body}")] |
| + | Upstream { status: u16, body: String }, |
| + | } |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## §L. Backup & Disaster Recovery |
| + | |
| + | ### L.1 What to back up |
| + | - **Postgres** (full dump + WAL archive) - single source of truth. |
| + | - **MinIO bucket** (scraped HTML screenshots for debug, can be regenerated). |
| + | - **ntfy user.db** (auth tokens - annoying to recreate, do back up). |
| + | - **Meilisearch index** - can be rebuilt from Postgres; skip from backups. |
| + | - **Configs**: `.env`, `infra/Caddyfile`, `infra/ntfy.server.yml`, dashboards. |
| + | |
| + | ### L.2 Schedule |
| + | - **Postgres nightly** `pg_dump` at 03:00 homelab TZ → `/backups/postgres/drophawk-YYYYMMDD.sql.gz`. |
| + | - **WAL archiving** via `pgBackRest` or `wal-g` continuous to MinIO bucket `pg-wal`. |
| + | - **MinIO lifecycle**: nightly dumps retained 30 days, weekly dumps 90 days, monthly 1 year. |
| + | - **Config bundle**: every git push triggers GitHub Action that tarballs `infra/` and `.env.example` to MinIO. |
| + | |
| + | ### L.3 Restore runbook |
| + | 1. `docker compose down` |
| + | 2. Wipe `pg-data` volume. |
| + | 3. `docker compose up -d postgres` and wait for healthy. |
| + | 4. `gunzip -c drophawk-YYYYMMDD.sql.gz | docker compose exec -T postgres psql -U drophawk` |
| + | 5. Replay WAL since dump (if using continuous archive): `wal-g backup-fetch /var/lib/postgresql/data LATEST && wal-g wal-fetch …` |
| + | 6. `docker compose up -d` (everything). |
| + | 7. Verify `/api/ready` returns 200. |
| + | 8. Verify latest `drops.detected_at` matches expected. |
| + | |
| + | **RTO target: 30 minutes. RPO target: 15 minutes** (with WAL archiving) or 24 hours (nightly only). |
| + | |
| + | ### L.4 Backup verification |
| + | - Every Sunday 04:00, restore latest nightly dump into a temporary Postgres container, run smoke queries, alert if any fail. Cron job in `scripts/verify-backup.sh`. |
| + | |
| + | --- |
| + | |
| + | ## §M. Security Model |
| + | |
| + | ### M.1 Threat surface |
| + | - **Internal network only.** No public exposure. Operator accesses via Tailscale or LAN. |
| + | - If public exposure is ever needed, **Caddy must enforce basic auth + IP allowlist**. Not in v1 scope. |
| + | |
| + | ### M.2 Service-to-service auth |
| + | - All internal services on `drophawk-net` Docker network. No mTLS in v1 (trusted network). |
| + | - Postgres: single user `drophawk` with random password from `.env`. No app-level users. |
| + | - Redis: require `REDIS_PASSWORD`. No ACL subusers. |
| + | - NATS: require `NATS_USER` + `NATS_PASSWORD`. Enable JetStream. |
| + | - Meilisearch: require `MEILI_MASTER_KEY`. Frontend never talks to Meilisearch directly; always via backend. |
| + | - ntfy: ACL-protected. Publisher token has write-only on `drophawk-drops`. iOS subscribe uses read-only token. |
| + | |
| + | ### M.3 API auth (frontend → backend) |
| + | - v1: **no auth** (single user, LAN-only). Caddy IP allowlist optional. |
| + | - v7: optional bearer token via `DROPHAWK_API_TOKEN`. Frontend sends `Authorization: Bearer`. |
| + | |
| + | ### M.4 Secret management |
| + | - `.env` is the canonical secret store. **Never committed**. Mode 0600. |
| + | - `.env.example` documents every key with placeholder values. |
| + | - CI step: `gitleaks detect` runs on every PR. Pre-commit hook rejects if `.env` pattern is staged. |
| + | - Backups of `.env` stored in MinIO encrypted bucket, accessible only to operator. |
| + | |
| + | ### M.5 Input validation |
| + | - Every POST/PATCH body validated by Zod (frontend) AND `validator` crate (backend). Never trust client. |
| + | - Regex patterns in watchlist are compiled server-side; reject if compilation > 1ms (ReDoS guard). Limit pattern length to 256 chars. |
| + | - Query params: integers bounded (e.g. `per_page ≤ 100`), timestamps parsed strictly. |
| + | - All URLs returned to user are validated to be `https://` (no `javascript:`). |
| + | |
| + | ### M.6 Audit log |
| + | - Every mutation (POST/PATCH/DELETE on watchlist, PATCH on sources) writes to a `mutation_log` table: |
| + | ```sql |
| + | CREATE TABLE mutation_log ( |
| + | id BIGSERIAL PRIMARY KEY, |
| + | action TEXT NOT NULL, -- 'watchlist.create', 'source.toggle', etc. |
| + | target TEXT, |
| + | actor TEXT, -- 'operator' (single user) for now |
| + | payload JSONB, |
| + | at TIMESTAMPTZ NOT NULL DEFAULT NOW() |
| + | ); |
| + | ``` |
| + | |
| + | ### M.7 Anti-bot / ethical scraping (reaffirmed) |
| + | - Honest UA on API sources: `DropHawk/0.1 (+https://your-homelab/drophawk)`. |
| + | - Browser impersonation only on Cloudflare-protected public pages, only for read. |
| + | - **Never solve CAPTCHA, never bypass rate limits via IP rotation that targets a specific account, never submit forms on behalf of any user, never store 3rd party credentials.** |
| + | |
| + | --- |
| + | |
| + | ## §N. Testing Strategy |
| + | |
| + | ### N.1 Pyramid |
| + | - **Unit (70%)**: pure functions - hash canonicalization, status inference, price-drop classification, regex compilation. |
| + | - **Integration (25%)**: DB access (testcontainers-postgres), NATS round-trip, ntfy mock (wiremock). |
| + | - **E2E (5%)**: Playwright through the full stack via `docker compose`. |
| + | |
| + | ### N.2 Coverage gates |
| + | - Rust: `cargo tarpaulin` → **≥ 80% line coverage** on `backend/src/{detect,sources,store,notify}`. |
| + | - Python: `pytest --cov=scrapers --cov-fail-under=75`. |
| + | - TypeScript: Vitest → **≥ 75% line** on `lib/` and `hooks/`. |
| + | |
| + | ### N.3 Fixtures |
| + | - **Golden JSON**: `backend/tests/fixtures/ticketmaster/sample_event.json` (real Ticketmaster response, sanitized). Hash test vectors locked against this. |
| + | - **HTTP replay**: `wiremock` for Rust, `vcrpy` for Python. Cassettes checked in under `tests/cassettes/`. |
| + | - **DB snapshot**: tiny Postgres dump with seed data, loaded via testcontainers in `conftest.rs`. |
| + | - **SSE fixture**: a recorded stream of 50 drop events for frontend testing. |
| + | |
| + | ### N.4 Test commands (run all before merge) |
| + | ```bash |
| + | make check # runs all of below |
| + | cargo clippy -- -D warnings |
| + | cargo fmt --check |
| + | cargo test --all |
| + | cd scrapers && uv run pytest |
| + | cd frontend && pnpm typecheck && pnpm lint && pnpm test |
| + | cd frontend && pnpm test:e2e # only in CI, needs running stack |
| + | ``` |
| + | |
| + | ### N.5 Property tests (Rust, `proptest`) |
| + | - `content_hash` is deterministic: same input → same hash, across runs. |
| + | - `content_hash` differs when ANY participating field differs. |
| + | - Hash is stable across serializer versions (golden vectors). |
| + | |
| + | ### N.6 Load test |
| + | - `backend/benches/scheduler.rs`: simulate 50 sources × 1s interval × 1k events/poll → must sustain <60% CPU single core. |
| + | - `scripts/loadtest.sh`: 100 concurrent SSE clients, 1000 events/s broadcast → no SSE drops. |
| + | |
| + | --- |
| + | |
| + | ## §O. Performance Budgets |
| + | |
| + | ### O.1 Latency budgets |
| + | | Path | p50 | p99 | |
| + | |---|---|---| |
| + | | Poll → drop detected | 500ms | 2s | |
| + | | Drop detected → ntfy sent | 200ms | 1s | |
| + | | Drop detected → SSE fanout | 50ms | 250ms | |
| + | | HTTP API read | 30ms | 200ms | |
| + | | HTTP API write | 80ms | 400ms | |
| + | | Frontend TTFB (Next.js SSR) | 100ms | 400ms | |
| + | | Frontend TTI | 800ms | 2.5s | |
| + | | End-to-end (poll start → phone buzz) | 5s | 15s | |
| + | |
| + | ### O.2 Memory budgets (Docker container ceilings) |
| + | | Service | Limit | Notes | |
| + | |---|---|---| |
| + | | backend | 512MB | | |
| + | | scrapers | 1.5GB | Playwright hungry; cap concurrency to 4 tabs/worker | |
| + | | frontend (SSR) | 384MB | | |
| + | | postgres | 2GB | `shared_buffers=512MB`, `work_mem=16MB` | |
| + | | redis | 256MB | `maxmemory=200mb`, allkeys-lru | |
| + | | nats | 256MB | JetStream file storage, memory stream disabled | |
| + | | meilisearch | 1GB | | |
| + | | ntfy | 64MB | | |
| + | | minio | 256MB | | |
| + | | prometheus | 512MB | retention 30d | |
| + | | grafana | 256MB | | |
| + | | loki | 512MB | retention 14d | |
| + | |
| + | Total ceiling: ~7.6 GB. Operators with 16 GB homelab have ample headroom. |
| + | |
| + | ### O.3 SLOs (measured by Prometheus) |
| + | - **API availability**: 99.9% over 30 days rolling. |
| + | - **API p99 latency** ≤ 500ms on hot paths. |
| + | - **SSE reconnect rate** ≤ 0.5/min/client (bad if proxies drop constantly). |
| + | |
| + | ### O.4 Frontend bundle budget |
| + | - Initial JS for `/` route: **≤ 250 KB** gzipped. |
| + | - Initial CSS: **≤ 60 KB** gzipped. |
| + | - No single image > 200 KB without `next/image` optimization. |
| + | |
| + | --- |
| + | |
| + | ## §P. Idempotency Rules |
| + | |
| + | ### P.1 NATS JetStream deduplication |
| + | - Every message published by `emit_drop` carries `Nats-Msg-Id: drop-{drop_id}`. JetStream dedupes within the stream's duplicate window (set to **10 minutes**). |
| + | - Scraper round-trip messages carry `Nats-Msg-Id: scrape-{source_id}-{epoch_ms_floor_1000}` (1s buckets). Idempotent. |
| + | |
| + | ### P.2 Notification dedup (Redis) |
| + | - Key: `notif:dedupe:{event_id}:{drop_type}` (TTL 600s). SETNX. Skip if exists. |
| + | - Cross-type guard: `notif:dedupe:{event_id}:any` with TTL 60s - no more than one push per event per minute even across types. |
| + | |
| + | ### P.3 Drop dedup (DB) |
| + | - `drops` has no unique constraint (same event can legitimately emit two status drops minutes apart if status oscillates). |
| + | - But the **detection layer** only emits when `content_hash` actually changes. So oscillation is naturally bounded to source's actual polling cadence. |
| + | |
| + | ### P.4 Insert race (upsert) |
| + | - `events` has `UNIQUE (source_id, source_event_id)`. Use `INSERT … ON CONFLICT (source_id, source_event_id) DO UPDATE SET … WHERE events.content_hash != EXCLUDED.content_hash RETURNING id, content_hash`. This makes ingest atomic and race-safe. |
| + | |
| + | --- |
| + | |
| + | ## §Q. Cross-Source Entity Resolution |
| + | |
| + | The same physical event (e.g. Taylor Swift Aug 12 Miami) appears on Ticketmaster, SeatGeek, StubHub (resale), Vivid Seats. We want to link these so the UI shows aggregated info. |
| + | |
| + | ### Q.1 Algorithm (deterministic, runs in `detect::link_event`) |
| + | |
| + | For each new/updated `events` row, attempt to link to existing clusters: |
| + | |
| + | 1. **Exact performer ID match**: if `raw.tm_attraction_ids[]` and `raw.seatgeek_performer_ids[]` intersect (after a normalization map), confidence = 1.0, basis = `performer_id`. |
| + | 2. **Date + venue match**: `WHERE starts_at BETWEEN new.starts_at - 1h AND new.starts_at + 1h AND venue_name ILIKE new.venue_name AND city = new.city AND country = new.country`. Confidence = 0.85. |
| + | 3. **Title + date match**: tokenized title similarity (Jaccard ≥ 0.7 on lowercased tokens, ignoring stopwords) + same date ± 1h. Confidence = 0.65. |
| + | |
| + | If any match found, **insert into `cross_source_links` with the matched cluster_id** (create new cluster if no existing one). If multiple clusters match, merge them (lowest id wins). |
| + | |
| + | ### Q.2 When used |
| + | - `GET /api/events/:id` returns `cross_source_links[]` so the UI can show "Also on SeatGeek ($X), StubHub ($Y)". |
| + | - The buy_url shown in drops is always the canonical source's URL, but the UI surfaces alternatives. |
| + | |
| + | ### Q.3 Implementation notes |
| + | - Run linking **synchronously** during `ingest_candidate` (it's fast - 3 indexed queries). |
| + | - Re-run linking when venue names get normalized (write a `venue_normalization` table mapping messy names to canonical - populated manually over time). |
| + | |
| + | --- |
| + | |
| + | ## §R. Buy URL Canonicalization |
| + | |
| + | ### R.1 Rules |
| + | - Always `https://`. |
| + | - Strip tracking params added by our scrapers (`?utm_*`, `?ref=*`, `?clickId=*`, `?_branch_match_id=*`). |
| + | - Preserve source-required params (e.g. Ticketmaster's `event/id` path segment is essential). |
| + | - **Add** DropHawk's own ref param if affiliate program is set: `?drophawk=1`. (No affiliate abuse; honest disclosure in UA.) |
| + | - Sort query params alphabetically. (Stable URLs.) |
| + | - If URL has fragment, preserve. |
| + | |
| + | ### R.2 Reference implementation |
| + | ```rust |
| + | pub fn canonicalize_buy_url(raw: &str) -> Result<String, AppError> { |
| + | let mut url = url::Url::parse(raw).map_err(|e| AppError::Validation(e.to_string()))?; |
| + | if url.scheme() != "https" { |
| + | return Err(AppError::Validation("buy_url must be https".into())); |
| + | } |
| + | let drop_keys = ["utm_source","utm_medium","utm_campaign","utm_term","utm_content","ref","clickId","_branch_match_id"]; |
| + | let keys_to_remove: Vec<String> = url.query_pairs() |
| + | .filter(|(k, _)| drop_keys.contains(&k.as_ref())) |
| + | .map(|(k,_)| k.into_owned()) |
| + | .collect(); |
| + | for k in keys_to_remove { |
| + | url.query_pairs_mut().remove_pair(&k); |
| + | } |
| + | url.query_pairs_mut().append_pair("drophawk", "1"); |
| + | url.query_pairs_mut().clear().extend_pairs( |
| + | url.query_pairs().collect::<std::collections::BTreeMap<_,_>>() |
| + | ); // alphabetical |
| + | if url.query().map(|q| q.is_empty()).unwrap_or(true) { |
| + | url.set_query(None); |
| + | } |
| + | Ok(url.to_string()) |
| + | } |
| + | ``` |
| + | |
| + | ### R.3 Per-source overrides |
| + | - Ticketmaster: respect `event/<id>` URL format. Affiliate param `tm_link` allowed if operator has affiliate ID (env `TICKETMASTER_AFFILIATE_ID`). |
| + | - SeatGeek: same, `aid` param if `SEATGEEK_AFFILIATE_ID` set. |
| + | |
| + | --- |
| + | |
| + | ## §S. Mobile / PWA Requirements |
| + | |
| + | ### S.1 Installability |
| + | - `frontend/public/manifest.webmanifest` with name, short_name, theme_color (teal), background_color (bg-base), display `standalone`, scope `/`, start_url `/?source=pwa`. |
| + | - Icons: 192×192, 512×512, 512×512 maskable, all PNG. Generated from one SVG via `scripts/generate-pwa-icons.sh`. |
| + | - Apple touch icon: `apple-touch-icon.png` 180×180. |
| + | - `<meta name="apple-mobile-web-app-capable" content="yes">`. |
| + | - `<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">`. |
| + | |
| + | ### S.2 Service worker (`frontend/public/sw.js`) |
| + | - Use **Serwist** (modern Workbox alternative, Next 16 compatible). |
| + | - Cache strategy: |
| + | - HTML navigations: **NetworkFirst** with 5s timeout, fallback to cached `/`. |
| + | - Static assets (`/_next/static/*`): **CacheFirst** with stale-while-revalidate for fonts. |
| + | - API GETs: **NetworkFirst** (no caching of live data). |
| + | - SSE: bypass SW (browser handles natively). |
| + | - Update flow: SW detects new version → shows toast "Update available" → user clicks → SW takes over on next navigation. |
| + | |
| + | ### S.3 Touch interactions |
| + | - All tap targets ≥ 44×44 pt (WCAG 2.5.5). |
| + | - Pull-to-refresh on dashboard (use `react-pull-to-refresh` or custom Framer Motion). |
| + | - Long-press DropCard → context menu (Pin, Hide, Add to watchlist). |
| + | - Swipe-left on DropCard → dismiss. |
| + | |
| + | ### S.4 Push on PWA |
| + | - For v1, push is via **ntfy app** (already in scope). Web Push API integration is Phase 7+. |
| + | |
| + | --- |
| + | |
| + | ## §T. Accessibility - WCAG 2.2 AA (binding) |
| + | |
| + | ### T.1 Perceivable |
| + | - Color contrast: text ≥ 4.5:1, large text (≥18pt) ≥ 3:1. Tested against `--color-bg-base` and `--color-bg-elevated`. The OKLCH palette above is pre-verified; do not introduce new colors without re-test. |
| + | - Non-text contrast (UI components, borders): ≥ 3:1. |
| + | - All form inputs have associated `<label>` (Radix `Label`). |
| + | - Images have `alt`; decorative images have `alt=""`. |
| + | - Status pills: text label AND color. Never color alone. |
| + | |
| + | ### T.2 Operable |
| + | - Keyboard nav: tab order follows visual order; visible focus ring using `outline: 2px solid var(--color-accent-teal)` with `outline-offset: 2px`. Never `outline: none`. |
| + | - Skip-to-main link at top of every page. |
| + | - All interactive elements reachable in ≤ 6 tabs from page load. |
| + | - Cmd+K command palette has `role="dialog"`, `aria-modal`, focus trap, Escape to close. |
| + | - No keyboard trap. |
| + | |
| + | ### T.3 Understandable |
| + | - Form validation errors are announced via `aria-live="polite"`. |
| + | - Time formats include timezone suffix (e.g. `7:00 PM ET`). |
| + | - Relative time component has `title` with absolute timestamp. |
| + | |
| + | ### T.4 Robust |
| + | - Valid HTML5; tested with `axe-core` in Playwright suite. Zero critical or serious violations. |
| + | |
| + | ### T.5 Motion |
| + | - All animations honor `prefers-reduced-motion: reduce` (see globals.css). |
| + | |
| + | ### T.6 Audit |
| + | - Run `axe-playwright` against every route in e2e. Fail CI on new violations. |
| + | |
| + | --- |
| + | |
| + | ## §U. i18n |
| + | |
| + | ### U.1 v1 scope |
| + | - English only, but **structure for i18n from day one**. |
| + | - All UI strings via `next-intl` (`frontend/messages/en.json`). |
| + | - No hardcoded user-facing strings in components. |
| + | |
| + | ### U.2 Currency |
| + | - Each event carries `currency` (ISO 4217). Display via `Intl.NumberFormat` with user's preferred currency (Settings). |
| + | - Default user currency: `USD`. Operator can switch to `EUR`, `GBP`, etc. |
| + | - Conversion rates: fetched daily from `open.er-api.com` (free), cached in Redis. |
| + | |
| + | ### U.3 Dates / times |
| + | - All times stored UTC. Display in user's local timezone via `Intl.DateTimeFormat` with `timeZone` from `Intl.DateTimeFormat().resolvedOptions().timeZone`. |
| + | - Format pattern: `Aug 12 2026, 7:00 PM ET` (date, time, tz abbreviation). |
| + | |
| + | --- |
| + | |
| + | ## §V. Image Pipeline |
| + | |
| + | ### V.1 Source images |
| + | - Ticketmaster/SeatGeek provide `image_url`. Cache via Next.js `next/image` with remote pattern allow-list. |
| + | - For sources without images (FIFA), use a generated gradient placeholder keyed off `source_id` (deterministic hue). |
| + | |
| + | ### V.2 Allowed remote patterns (`next.config.mjs`) |
| + | ```js |
| + | images: { |
| + | remotePatterns: [ |
| + | { protocol: "https", hostname: "**.ticketmaster.com" }, |
| + | { protocol: "https", hostname: "**.seatgeek.com" }, |
| + | { protocol: "https", hostname: "cdn.fifa.com" }, |
| + | { protocol: "https", hostname: "**. axs.com" }, |
| + | ], |
| + | formats: ["image/avif", "image/webp"], |
| + | minimumCacheTTL: 86400, |
| + | } |
| + | ``` |
| + | |
| + | ### V.3 Generated placeholders |
| + | - Function `placeholderFor(seed: string): { from: string, to: string }`. |
| + | - Hash `seed` → pick hue from a curated 12-color palette. |
| + | - CSS gradient `linear-gradient(135deg, hsl1, hsl2)`. |
| + | - Cache the gradient in component state; no network. |
| + | |
| + | ### V.4 Lazy loading |
| + | - All `<Image>` below the fold use `loading="lazy"` (default in Next 16 Image). |
| + | - DropCard images are 64×64 (tiny); always load eagerly for top-of-feed. |
| + | |
| + | --- |
| + | |
| + | ## §W. Failure Mode Runbooks |
| + | |
| + | For each service: what fails, what the system does, what the operator does. |
| + | |
| + | ### W.1 Postgres down |
| + | - **Detection**: `/api/ready` 503; `pg_up == 0` alert. |
| + | - **System behavior**: backend stops accepting requests (returns 503). Pollers pause (no DB to write to). NATS messages accumulate in JetStream (24h retention). Scrapers keep working but Rust can't ingest. |
| + | - **Operator**: investigate (`docker compose logs postgres`), restore from backup if needed (§L.3), restart. On recovery, JetStream replays unprocessed messages. |
| + | |
| + | ### W.2 Redis down |
| + | - **Detection**: `/api/ready` 503. |
| + | - **System behavior**: rate-limit tokens can't be acquired - pollers pause. Notification dedup breaks - temporarily allow duplicate notifications (safer than missing one). Cache misses. |
| + | - **Operator**: `docker compose restart redis`. Data is non-critical (cache only). |
| + | |
| + | ### W.3 NATS down |
| + | - **Detection**: backend startup fails `nats.connect`. |
| + | - **System behavior**: pollers for scrape-based sources can't RPC → they wait + retry. API-based sources keep working (direct fetch). |
| + | - **Operator**: restart NATS. JetStream persists to disk; no data loss. |
| + | |
| + | ### W.4 Meilisearch down |
| + | - **Detection**: `/api/explore` returns 503. |
| + | - **System behavior**: search UI disabled; everything else works. Backend falls back to Postgres trigram search (`idx_events_title_trgm`). |
| + | - **Operator**: restart. Rebuild index from Postgres via `POST /api/admin/reindex` (Phase 7). |
| + | |
| + | ### W.5 ntfy down |
| + | - **Detection**: `notify::push` returns error; metric counter. |
| + | - **System behavior**: notifications fail silently to user. Drops still flow to SSE → UI still works. |
| + | - **Operator**: restart ntfy. Missed drops: UI has them; user can scroll back. |
| + | |
| + | ### W.6 Scraper worker down (Playwright crash) |
| + | - **Detection**: source's poll round-trip times out → `SourceError::Network`. |
| + | - **System behavior**: 3 timeouts → source `degraded`. 10 → `down` + alert. |
| + | - **Operator**: `docker compose restart scrapers`. Source resumes. |
| + | |
| + | ### W.7 Source blocks us (403/429) |
| + | - **Detection**: `SourceError::Blocked`. |
| + | - **System behavior**: circuit opens after 3, source → `degraded`. Alert at 10. |
| + | - **Operator**: investigate robots.txt change, enable proxy pool (Phase 6), or disable source temporarily. |
| + | |
| + | ### W.8 Caddy down |
| + | - **Detection**: nothing accessible from operator. |
| + | - **System behavior**: backend still runs, scrapers still run, but no UI access. |
| + | - **Operator**: `docker compose restart caddy`. Caddy auto-HTTPS state in volume. |
| + | |
| + | ### W.9 Disk full |
| + | - **Detection**: Postgres write fails; Loki rejects logs. |
| + | - **System behavior**: cascade failure. |
| + | - **Operator**: clean old DropHawk data (`SELECT drop_chunks('drops', older_than => '30 days')`), prune Docker images, expand disk. |
| + | |
| + | ### W.10 Backend OOM |
| + | - **Detection**: container restarts; `drophawk_backend_oom_total` metric. |
| + | - **System behavior**: brief outage. JetStream replays missed messages on startup. |
| + | - **Operator**: investigate memory leak; raise memory limit; file issue. |
| + | |
| + | --- |
| + | |
| + | ## §X. CORS Configuration |
| + | |
| + | `backend/src/api/mod.rs`: |
| + | ```rust |
| + | let cors = CorsLayer::new() |
| + | .allow_origin(["http://drophawk.lan", "http://localhost:3000"].map(|s| s.parse().unwrap())) |
| + | .allow_methods([Method::GET, Method::POST, Method::PATCH, Method::DELETE, Method::OPTIONS]) |
| + | .allow_headers([ |
| + | header::AUTHORIZATION, |
| + | header::CONTENT_TYPE, |
| + | header::ACCEPT, |
| + | ]) |
| + | .allow_credentials(false) |
| + | .max_age(Duration::from_secs(600)); |
| + | ``` |
| + | SSE handler bypasses CORS layer (handled separately to allow `text/event-stream`). |
| + | |
| + | --- |
| + | |
| + | ## §Y. Configuration Surface (env var reference) |
| + | |
| + | Complete list. `.env.example` must contain every key below with placeholder values. CI fails if `.env.example` is missing any key. |
| + | |
| + | ### Y.1 Backend |
| + | ``` |
| + | # Required |
| + | DATABASE_URL=postgres://drophawk:CHANGE_ME@postgres:5432/drophawk |
| + | REDIS_URL=redis://:CHANGE_ME@redis:6379/0 |
| + | NATS_URL=nats://drophawk:CHANGE_ME@nats:4222 |
| + | MEILI_URL=http://meilisearch:7700 |
| + | MEILI_MASTER_KEY=CHANGE_ME |
| + | NTFY_BASE_URL=http://ntfy:80 |
| + | NTFY_TOPIC=drophawk-drops |
| + | NTFY_TOKEN=tk_CHANGE_ME |
| + | LOG_LEVEL=info # trace|debug|info|warn|error |
| + | OTEL_EXPORTER_OTLP_ENDPOINT=http://loki:4317 |
| + | PUBLIC_BASE_URL=https://drophawk.lan |
| + | |
| + | # Source credentials (optional per source) |
| + | TICKETMASTER_API_KEYS=key1,key2,key3 |
| + | SEATGEEK_CLIENT_ID= |
| + | TICKETMASTER_AFFILIATE_ID= |
| + | SEATGEEK_AFFILIATE_ID= |
| + | |
| + | # Future |
| + | PROXY_POOL_URL= |
| + | TELEGRAM_BOT_TOKEN= |
| + | TWITTER_BEARER_TOKEN= |
| + | |
| + | # Operational |
| + | API_RATE_LIMIT_PER_MIN=100 |
| + | SSE_MAX_CLIENTS=200 |
| + | SCRAPER_RPC_TIMEOUT_S=30 |
| + | WATCHLIST_MAX_RULES=500 |
| + | POLL_DEFAULT_INTERVAL_S=300 |
| + | POLL_TIGHT_INTERVAL_S=10 |
| + | POLL_TIGHT_WINDOW_S=900 |
| + | ``` |
| + | |
| + | ### Y.2 Frontend (build-time) |
| + | ``` |
| + | NEXT_PUBLIC_API_BASE_URL=https://drophawk.lan/api |
| + | NEXT_PUBLIC_NTFY_PUBLIC_URL=https://drophawk.lan/ntfy |
| + | NEXT_PUBLIC_NTFY_PUBLIC_TOPIC=drophawk-drops |
| + | NEXT_PUBLIC_SENTRY_DSN= # optional |
| + | ``` |
| + | |
| + | ### Y.3 Python scrapers |
| + | ``` |
| + | DATABASE_URL= # informational only; not used directly |
| + | NATS_URL=nats://drophawk:CHANGE_ME@nats:4222 |
| + | REDIS_URL=redis://:CHANGE_ME@redis:6379/1 |
| + | SCRAPER_CONCURRENCY=4 |
| + | SCRAPER_LOG_LEVEL=INFO |
| + | PLAYWRIGHT_BROWSERS_PATH=/ms-playwright |
| + | FIFA_BASE_URL=https://tickets.fifa.com |
| + | AXS_BASE_URL=https://www.axs.com |
| + | STUBHUB_API_KEY= |
| + | VIVIDSEATS_PROXY= |
| + | TWITTER_ACCOUNTS= # comma list of @handles to watch |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## §Z. Final Implementation Directives |
| + | |
| + | These are the **non-negotiable directives** for any executing agent reading this contract: |
| + | |
| + | 1. **Implement Phase 1 first, end-to-end, no detours.** A thin working slice beats a wide unfinished one. The operator is disabled and depends on this working. |
| + | 2. **Run `make check` before declaring any task done.** Zero warnings, zero errors. |
| + | 3. **Commit per logical unit**, conventional commits, never amend shared branches. |
| + | 4. **If this contract is silent on a decision, ask the operator.** Do not improvise on security, data loss, or notification correctness. |
| + | 5. **Every file in §4 of SPEC.md exists in Phase 1 with a working implementation, not a stub.** Stub = `unimplemented!()` or `TODO` = merge blocked. |
| + | 6. **Test fixtures are golden**. Hash vectors in §D.4 are regression gates. |
| + | 7. **The OKLCH palette in §H.1 is the entire color system.** Do not introduce ad-hoc hex codes. |
| + | 8. **Notification correctness is sacred.** False positives erode trust fastest. The dedupe + filter pipeline (§I.3 + §5.5) must be tested exhaustively. |
| + | 9. **No third-party dependencies beyond those pinned in §A.** If a new one is truly required, bump the spec, justify, and pin a version. |
| + | 10. **When in doubt, choose reliability over feature richness.** The dashboard showing 5 working sources is better than 25 half-broken ones. |
| + | |
| + | --- |
| + | |
| + | **End of binding contracts. Return to SPEC.md §14 for the phased roadmap and §17 for per-phase verification.** |