Reactive-Resume/plans/005-dedup-public-view-statistics.md

# Plan 005: Deduplicate public-resume view-count writes

> **Executor instructions**: Follow step by step. Run every verification and
> confirm before moving on. Honor "STOP conditions". When done, update the
> status row in `plans/README.md`.
>
> **Drift check (run first)**:
> `git diff --stat 73daf22b2..HEAD -- packages/api/src/features/resume/service.ts packages/api/src/features/resume/access-policy.ts`
> If either changed since this plan, compare "Current state" excerpts against
> live code; on mismatch, STOP.

## Status

- **Priority**: P2
- **Effort**: M
- **Risk**: MED
- **Depends on**: 001 recommended (its Step 5 test characterizes
  `statistics.increment`, giving you a safety net that this plan changes the
  *caller*, not the write body).
- **Category**: perf
- **Planned at**: commit `73daf22b2`, 2026-07-08

## Why this matters

Every public-resume view triggers a database write. `getBySlug`
(`packages/api/src/features/resume/service.ts:475`) calls
`statistics.increment(...)` whenever `shouldCountForStatistics` is true, and
`increment` (lines 199–237) runs a transaction with **two** `INSERT ... ON
CONFLICT DO UPDATE` statements (`resumeStatistics` + `resumeStatisticsDaily`).
This fires on every non-owner load — bots, crawlers, and refreshes included.
TanStack Query's 60s `staleTime` only suppresses within-session refetches; it
does nothing for distinct sessions or server-side crawlers. A popular public
resume therefore drives continuous write traffic to two tables for what is
functionally the same view counted many times.

This plan adds a short-window per-viewer dedup so a burst of views from the
same client within a window counts once, cutting write volume without changing
what the counters mean to users (roughly "unique-ish views per window").

## Current state

- `packages/api/src/features/resume/service.ts:475` — `getBySlug` receives
  `input.requestHeaders: Headers`, resolves the resume, and at lines 505–507:

  ```ts
  if (shouldCountForStatistics(resume, viewer)) {
    await resumeService.statistics.increment({ id: resume.id, views: true });
  }
  ```

- `packages/api/src/features/resume/access-policy.ts:76` —
  `shouldCountForStatistics(resume, viewer)` decides *whether* a view counts
  (e.g. skip the owner). This plan adds an orthogonal *"have we already counted
  this viewer recently?"* gate; it does **not** change `shouldCountForStatistics`.

- `increment` (`service.ts:199-237`) — the two-table transactional write. **Do
  not change its body**; this plan changes only whether it is called.

- **Reusable client-identity helper**: `packages/utils/src/rate-limit.ts`
  exports `TRUSTED_IP_HEADERS` (the ordered list of proxy IP headers the app
  trusts). The rate-limit middleware already derives a client key from these
  headers the same way. Reuse `TRUSTED_IP_HEADERS` to read the viewer IP from
  `input.requestHeaders`; fall back to a `user-agent`-based key when no trusted
  IP header is present (mirror the middleware's fallback so behavior is
  consistent).

- **Environment**: `REDIS_URL` exists in `packages/env/src/server.ts` and
  `turbo.json` globalEnv, but the app runs as a single Node process by default
  and the existing rate limiter uses an **in-memory** store
  (`@orpc/experimental-ratelimit/memory`). Match that: an in-memory TTL cache
  is the right default here.

## Commands you will need

| Purpose   | Command                                                             | Expected  |
|-----------|--------------------------------------------------------------------|-----------|
| Typecheck | `pnpm --filter @reactive-resume/api typecheck`                     | exit 0    |
| Test      | `pnpm --filter @reactive-resume/api test -- resume`                | all pass  |
| All api   | `pnpm --filter @reactive-resume/api test`                          | all pass  |

(Do NOT run `pnpm check`.)

## Scope

**In scope**:
- A new small helper module, e.g.
  `packages/api/src/features/resume/view-dedup.ts` (create) — an in-memory
  TTL set keyed by `${resumeId}:${clientKey}` with a `shouldCountView(...)`
  function that returns `true` at most once per key per window.
- `packages/api/src/features/resume/view-dedup.test.ts` (create)
- `packages/api/src/features/resume/service.ts` — gate the `increment` call
  (lines 505–507) on the new helper.
- `plans/README.md` (status row)

**Out of scope**:
- `increment`'s write body and the DB schema — unchanged.
- `shouldCountForStatistics` in `access-policy.ts` — unchanged.
- Any Redis / distributed-cache implementation — an in-memory window is the
  agreed default; a distributed store is a documented future upgrade, not this
  plan.
- Download counting (`downloads: true`) — this plan is about view writes only;
  do not alter download increments.

## Git workflow

- Branch: `advisor/005-stats-view-dedup`
- Commit: `perf(api): dedup public-resume view increments within a short window`
- Do NOT push or open a PR unless instructed.

## Steps

### Step 1: Write the dedup helper

Create `view-dedup.ts` exporting a pure-ish, testable function. Suggested
shape (keep it small — this is not a cache library):

```ts
// ponytail: in-memory per-process dedup window. Single-instance is the default
// deploy; for multi-instance, swap the Map for a Redis SETNX+EXPIRE keyed the
// same way (REDIS_URL already exists in env). Upgrade only if you scale out.
const WINDOW_MS = 60 * 60 * 1000; // 1 hour
const seen = new Map<string, number>(); // key -> expiry timestamp

export function shouldCountView(key: string, now: number): boolean {
  const expiry = seen.get(key);
  if (expiry !== undefined && expiry > now) return false;
  seen.set(key, now + WINDOW_MS);
  return true;
}

export function clientKeyFromHeaders(headers: Headers): string { /* uses TRUSTED_IP_HEADERS, UA fallback */ }
```

Take `now` as a parameter (don't call `Date.now()` inside the predicate) so the
test can drive the clock deterministically. Add a lightweight size guard: if
`seen.size` exceeds a cap (e.g. 50_000), prune entries whose expiry has passed
before inserting, so the Map can't grow unbounded. Reuse `TRUSTED_IP_HEADERS`
from `@reactive-resume/utils/rate-limit` inside `clientKeyFromHeaders`.

**Verify**: `pnpm --filter @reactive-resume/api typecheck` → exit 0.

### Step 2: Test the helper

Create `view-dedup.test.ts`:
- `shouldCountView(key, t)` returns `true` the first time, `false` for the same
  key within the window, and `true` again once `now` is past the window.
- Two different keys are independent.
- `clientKeyFromHeaders` derives distinct keys for distinct trusted-IP headers
  and a stable key for the UA fallback when no IP header is present.

**Verify**: `pnpm --filter @reactive-resume/api test -- view-dedup` → all pass.

### Step 3: Gate the increment call

In `service.ts` `getBySlug`, wrap the existing count so it fires only when both
the policy allows it AND the viewer hasn't been counted this window:

```ts
if (shouldCountForStatistics(resume, viewer)) {
  const key = `${resume.id}:${clientKeyFromHeaders(input.requestHeaders)}`;
  if (shouldCountView(key, Date.now())) {
    await resumeService.statistics.increment({ id: resume.id, views: true });
  }
}
```

Do not change anything else in `getBySlug`.

**Verify**: `pnpm --filter @reactive-resume/api typecheck` → exit 0.

### Step 4: Confirm no regression in existing resume tests

**Verify**: `pnpm --filter @reactive-resume/api test -- resume` → all pass. In
particular, if Plan 001's `statistics.increment` characterization test exists,
it should still pass (this plan didn't touch `increment`'s body). If a
`getBySlug` test asserts increment-on-view, it may now need the test to pass a
fresh header/clock so the first view still counts — update it to reflect the
dedup (first view counts, immediate repeat does not).

## Test plan

- `view-dedup.test.ts`: window behavior + key derivation (Step 2 cases).
- If an existing `getBySlug` test asserts view counting, extend it: first call
  with a given client key increments; an immediate second call with the same
  key does not; a call with a different key does.
- Verification: `pnpm --filter @reactive-resume/api test` → all pass.

## Done criteria

Machine-checkable. ALL must hold:

- [ ] `packages/api/src/features/resume/view-dedup.ts` and its `.test.ts` exist
- [ ] `pnpm --filter @reactive-resume/api test -- view-dedup` passes with ≥ 4 cases
- [ ] `grep -n "shouldCountView" packages/api/src/features/resume/service.ts` shows the gate around the increment call
- [ ] `pnpm --filter @reactive-resume/api typecheck` exits 0
- [ ] `pnpm --filter @reactive-resume/api test` exits 0
- [ ] `git status --porcelain` lists only in-scope files + `plans/README.md`
- [ ] `plans/README.md` status row for 005 updated

## STOP conditions

Stop and report if:

- `getBySlug` no longer calls `statistics.increment` at lines ~505–507, or its
  signature no longer exposes `requestHeaders` — the code drifted.
- You cannot derive a client key from `input.requestHeaders` because headers
  aren't actually populated at this layer in practice (check a real request
  path / existing rate-limit middleware usage) — report it; a dedup keyed on an
  empty header is worthless.
- You find that view counting must remain exact (product decision that every
  raw hit counts) — the dedup changes counter semantics slightly; if unsure,
  stop and confirm before shipping.

## Maintenance notes

- **Semantics change**: counters become "unique-ish views per 1h window per
  client" rather than "raw hits". Document this near the helper. If the product
  wants raw hit counts back, this gate is the single place to remove.
- **Multi-instance ceiling**: the in-memory Map is per-process. If the app is
  ever horizontally scaled, each instance dedups independently (still a large
  reduction, but not global). The ponytail comment names Redis as the upgrade
  path; do it only if scale-out happens.
- Reviewer should confirm `Date.now()` is only called at the call site (Step 3),
  not inside the predicate, so the helper stays testable.