c-relay-pg/plans/caching_page_redesign_plan.md

Caching Page Redesign: Split Backfill + Caching

Core Decision

Rename the current "Caching" page to "Backfill" (keep all existing UI/API exactly as-is). Create a new "Caching" page for designing the live subscription filter.

The nav becomes:

• Statistics
• Subscriptions
• Configuration
• Authorization
• IP BAN
• Relay Events
• Backfill ← renamed from "Caching"
• Caching ← new page
• DM
• Cleanup
• Database Query

What Stays the Same

The entire backfill system is untouched:

• admin/api/caching.php — unchanged, just renamed to backfill.php (or kept as-is and served under both names)
• admin/index.php — the current caching section HTML is moved to a "Backfill" section
• admin/assets/app.js — loadCaching() is renamed to loadBackfill() but logic is identical
• All daemon code (caching/src/backfill.c, etc.) — no changes

What Changes

1. Navigation: admin/index.php

<li><button class="nav-item" data-page="backfill">Backfill</button></li>
<li><button class="nav-item" data-page="caching">Caching</button></li>

2. Backfill Section (moved from current caching section)

The current caching section HTML (lines ~360-409) becomes the "Backfill" section with a new section ID backfillSection. Content is identical — same controls, same status displays, same followed pubkeys table.

3. New Caching Section

A new section for designing the live subscription filter. This is where we configure what the live subscriber sends to upstream relays.

┌─ CACHING (LIVE SUBSCRIPTION) ──────────────────────────┐
│                                                         │
│  Design the Nostr subscription filter:                  │
│                                                         │
│  Strategy:  ○ Whitelist Follows  ○ Cache Everything    │
│                                                         │
│  authors: [auto-populated from follow graph]     (1)   │
│  kinds:   [1, 7, 9734, ...]                           │
│  since:   [now - 3600s]  (lookback window)            │
│  limit:   [0]  (0 = no limit)                         │
│                                                         │
│  (1) authors is auto-populated in whitelist mode,      │
│      empty/absent in cache-everything mode             │
│                                                         │
│  Resubscribe interval: [300] seconds                   │
│                                                         │
│  [Save Configuration]                                   │
│                                                         │
│  Status: Live — receiving events                       │
│  Events received: 1,234                                │
└─────────────────────────────────────────────────────────┘

4. New API Endpoint: admin/api/caching.php

Option A: Create a new file admin/api/live_subscription.php

This is cleaner — separate concerns. The new endpoint handles:

• GET: return current live subscription config + status
• POST: update live subscription config fields

Option B: Keep admin/api/caching.php and add live sub fields

Simpler but muddies the existing file. Since we're renaming the old page to "Backfill", it makes more sense to have a separate file.

Recommendation: Option A — create admin/api/live_subscription.php.

5. New Config Keys

Add to PostgreSQL config table:

Key	Type	Default	Description
caching_live_strategy	text	whitelist	whitelist or cache_all
caching_live_kinds	text	(value of caching_kinds)	Kinds filter for live sub
caching_live_since_seconds	int	3600	Lookback: since = now - N
caching_live_limit	int	0	Max events (0 = no limit)
caching_live_resubscribe_seconds	int	300	Resubscribe interval

6. Admin JS: admin/assets/app.js

Changes:

• loadCaching() → renamed to loadBackfill() (same logic)
• New loadCaching() function for the new page
• New save functions for live subscription settings
• Add backfill to the page map and switch logic
• Keep caching pointing to the new section

7. Daemon Changes (Phase 2)

Update caching/src/live_subscriber.c to:

• Read caching_live_strategy from config
• If cache_all, omit authors filter
• Use configurable kinds, since, limit
• Skip admin sub in cache-all mode

Implementation Order

Phase 1: Admin Page Split (no daemon changes)

1. Rename nav item "Caching" → "Backfill"
2. Move current caching section HTML to backfill section
3. Create new caching section HTML with subscription design UI
4. Create admin/api/live_subscription.php
5. Update admin/assets/app.js:
   • Rename loadCaching() → loadBackfill()
   • Add new loadCaching() for live sub design
   • Add save functions
6. Add new config keys to database

Phase 2: Daemon Live Subscriber Changes

7. Update caching/src/config.h with new live config fields
8. Update caching/src/pg_config.c to read new keys
9. Modify caching/src/live_subscriber.c to support cache-all mode

Migration

• Existing caching_live_strategy defaults to whitelist (current behavior)
• Existing caching_live_kinds defaults to value of caching_kinds
• Zero behavior change on upgrade — backfill continues as before, live sub continues as before until user changes the strategy

Files Changed

File	Change
admin/index.php	Rename nav, move caching section to backfill, add new caching section
admin/api/caching.php	Unchanged (still serves backfill data)
admin/api/live_subscription.php	NEW — live subscription config API
admin/assets/app.js	Rename loadCaching→loadBackfill, add new loadCaching
caching/src/config.h	Add live strategy/kinds/since/limit fields
caching/src/pg_config.c	Read new config keys
caching/src/live_subscriber.c	Support cache-all mode