Redis Keys¶
Inventory of every Redis key pattern the backend reads or writes. Keys are grouped by domain. Patterns use {var} for runtime-substituted values.
This list is reconstructed by auditing backend/internal/platform/cache/cache.go (the Redis abstraction) and every caller across the domain packages under backend/internal/services/. If you add a new key, add it here too, since drift makes incident response painful.
Asynq queues
The background-task queues used by hibiken/asynq (asynq:* keys, including queue lists, scheduled sets, processing zsets, and unique-task locks) are managed internally by the library. They are not enumerated below — treat them as opaque. The library's own dashboard tools (asynq stats) are the right inspection path.
Authentication & sessions¶
| Key Pattern | Type | TTL | Purpose | Set By | Read By |
|---|---|---|---|---|---|
refresh_token:{sha256_hex} |
STRING | refresh token expiry | Maps a refresh token to its owning user_id, keyed by the hex SHA-256 of the token so the keyspace never carries a usable credential. Written on issue, deleted on logout and every revocation path. |
services/auth/session_service.go |
services/auth/session_service.go |
register_device:{fingerprint} |
STRING | 30 days | Count of registrations from a device fingerprint. Throttles bulk-account abuse. | services/auth/auth_service.go |
services/auth/auth_service.go |
webauthn:reg:{user_id} |
STRING (JSON) | 5 min | WebAuthn registration session data (challenge + options). | services/auth/auth_handler.go |
services/auth/auth_handler.go |
webauthn:login:{user_id} |
STRING (JSON) | 5 min | WebAuthn login session data (challenge + options). | services/auth/auth_handler.go |
services/auth/auth_handler.go |
step_up:{challenge_id} |
STRING (JSON) | 5 min | A begun step-up: caller, target account, purpose and the passkey session. Deleted when finished. | services/auth/link_service.go |
services/auth/link_service.go |
step_up:{challenge_id}:taken |
STRING | 5 min | SETNX claim so a challenge is finished at most once. | services/auth/link_service.go |
services/auth/link_service.go |
step_up_spent:{jti} |
STRING | step-up token's remaining life | SETNX marker that a step-up token was spent; a second use is refused. | services/auth/link_service.go |
services/auth/link_service.go |
apple_public_keys |
STRING (JSON) | 24 h | Cached Apple JWKS used to verify Sign-in-with-Apple identity tokens. | services/auth/auth_service.go |
services/auth/auth_service.go |
user:privacy:{user_id} |
STRING ("0"/"1") |
24 h | Cached is_location_shared flag, avoids a DB hit on every location update. Invalidated when user toggles sharing. |
services/friend/friend_service.go |
services/friend/friend_service.go, services/auth/auth_service.go (invalidate) |
usercontext:{user_id} |
STRING (JSON) | 5 min | Cached UserContext for search personalization: category affinities, saved/dismissed places, interaction edges. Invalidate drops it after a save/dismiss/affinity change; else the short TTL bounds staleness. |
services/personalization/service.go |
services/personalization/service.go |
affinity:reconciled:{user_id} |
STRING ("1") |
7 days | Lazy category-affinity reconcile watermark. Key present means the profile was recomputed within the window (skip); absent (expired or never) means a reconcile is due. Set after each reconcile, including the dormant-skip case. | services/maps/service.go |
services/maps/service.go |
affinity:cap:{user_id}:{action}:{item} |
STRING ("1") |
24 hours | Per-item daily cap on affinity signals: present means this action on this item already moved the user's score today (skip). | services/maps/service.go |
services/maps/service.go |
feed:seen:{user_id} |
STRING (JSON [momentId,…]) |
14 days | Home-feed seen-set: moment ids the viewer has scrolled past, so the moments pager leads with unseen cards. Bounded to 500 ids (oldest trimmed). Written by POST /discovery/feed/seen, read when assembling the feed. |
services/discovery/feed.go |
services/discovery/feed.go |
feed:snap:{user_id} |
STRING (JSON [{id,tier,seen},…]) |
15 min | Frozen ranked order for feed pagination: written on the first /discovery/feed request, read by ?cursor= requests so later pages window into a stable order instead of re-ranking against an advancing seen-set. |
services/discovery/feed.go |
services/discovery/feed.go |
browse:pool:{kind}:{geohash6}:{radius_m}:{lang}:{limit}:{variant} |
STRING (JSON candidates with their ranking signals) | 3 min | Shared per-area place recall behind /discovery/browse/places: kind is places or highlights; variant is - or a short digest of source, kinds and categories. Holds only the non-personal recall; the viewer overlay is applied per request and never stored here. |
services/discovery/browse_cache.go |
services/discovery/browse_cache.go |
trending:pool:{geohash6}:{radius_m}:{window_h} |
STRING (JSON [{u,l,t}]) |
2 min | Anonymous per-user, per-day activity for the area's top places, shared by every viewer in the cell. The viewer's own activity is excluded and friends weighted per request, never stored here. | services/discovery/trending.go |
services/discovery/trending.go |
Rate limiting & abuse¶
Most rate-limit keys are written by the Lua INCR + EXPIRE script in platform/cache/cache.go::RateLimit, keyed as {prefix}:{identifier} where identifier is the client IP (for the middleware presets) or a user id (for enrich:*). item:rl:* is the exception: a plain GetCache/SetCache counter rather than the atomic Lua limiter.
| Key Pattern | Type | TTL | Purpose | Set By | Read By |
|---|---|---|---|---|---|
register_ip:{ip} |
INT | 1 h | Registration attempts per IP (default limit: 5/h). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
login_ip:{ip} |
INT | 15 min | Login attempts per IP (default limit: 10/15 min). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
api_ip:{ip} |
INT | 1 min | Baseline API requests per IP on /api/v1/* (limit: 600/min). |
middleware/rate_limiter.go |
middleware/rate_limiter.go |
reset_password_ip:{ip} |
INT | 1 h | Password-reset token attempts per IP (limit: 5/h, prevents brute force). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
item:rl:{user_id}:{minute} |
INT | 2 min | Per-user capture-item throttle (limit: 60/min). Windowed by unix-minute suffix; a plain INCR-style counter, not the Lua limiter. |
services/plan/item_service.go |
services/plan/item_service.go |
enrich:parse:{user_id} |
INT | 24 h | Per-user/day budget for billable link-enrichment passes (CAPTURE_DAILY_PARSE_LIMIT, default 50). Dev/admin accounts bypass. |
services/plan/item_service.go |
services/plan/item_service.go |
enrich:upgrade:google |
INT | 24 h | Global daily budget for upgrading Serper-minted google_places rows via the billed Places details API (limit 200/day). |
services/location/location_service.go |
services/location/location_service.go |
enrich:photo-backfill |
INT | 24 h | Global daily cap on rows the enrichment sweep re-queues to rehost a missing place photo (limit 100/day). | services/location/location_enricher.go |
services/location/location_enricher.go |
otp_ip:{ip} |
INT | 15 min | OTP send and verify per IP (limit: 10/15 min). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
login_challenge:{sha256(token)} |
STRING | 10 min | The account id a proven password is waiting to finish with an emailed code; deleted when the code verifies. | services/auth/login_code.go |
services/auth/login_code.go |
otp_send_acct:{email_hash} |
INT | 1 h | OTP sends per address, hashed (limit: 5/h). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
data_export_user:{user_id} |
INT | 24 h | Personal-data exports per account, wrong-credential attempts included (limit: 5/day). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
step_up_user:{user_id} |
INT | 15 min | Step-up begin, finish and switches into linked accounts per account (limit: 20/15 min, fails closed). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
invite_ip:{ip} |
INT | 1 h | Account invite preview, code send and acceptance per client IP (limit: 10/h, fails closed). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
suspension_review_ip:{ip} |
INT | 1 h | Suspended-member review requests per client IP (limit: 10/h, fails closed). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
suspension_review:{sha256(token)} |
STR | 15 min | The single-purpose review token a refused suspended sign-in issues: userID\|actionID. Only the hash of the token is stored, and …:spent marks its one use. |
report/suspension_review.go |
report/suspension_review.go |
report_user:{user_id} |
INT | 1 h | Report filings and review requests per account (limit: 20/h, fails open). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
support_user:{user_id} |
INT | 1 h | Support cases and replies per account (limit: 30/h, fails open). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
screenshot_upload_user:{user_id} |
INT | 1 h | Support-screenshot upload starters per account (limit: 10/h, fails open). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
support_contact_ip:{ip} |
INT | 1 h | Public contact form per IP (limit: 5/h, fails closed). | middleware/rate_limiter.go |
middleware/rate_limiter.go |
abuse:violations:{key} |
INT | 10 min | Attack-pattern violations per client key (ip:{ip}); the threshold triggers a block. |
middleware/ip_blocker.go |
middleware/ip_blocker.go |
abuse:block:{key} |
STRING (JSON) | block length (15m, 1h, 24h) | Active block with reason, strike, since, until. | middleware/ip_blocker.go |
middleware/ip_blocker.go |
abuse:strikes:{key} |
INT | 7 d | Past blocks; picks the next block length. | middleware/ip_blocker.go |
middleware/ip_blocker.go |
harvest:lock:{h3cell}:fill |
STRING (token) | 45 s | Per-cell harvest lock: user fills, prefetches and the worker handoff of a cell take it, so a crowd opening the picker in one cold area pays for one harvest; released only by its owner's token. | services/location/harvest/engine.go |
services/location/harvest/lock.go |
harvest:fresh:{h3cell}:{tilekey} |
STRING | up to 10 min | Read-through verdict that a ledger tile is fresh; the ledger stays the truth. | services/location/harvest/engine.go |
services/location/harvest/engine.go |
gov:{gov}:spent:{yyyymmdd}:global, :trigger:{t}, :user:{fill\|text\|auto}:{id} |
INT | 48 h | Governor credit counters per UTC day, under one {gov} Cluster hash tag. Re-seeded, user counters included, from location_provider_spend after a flush (guard gov:{gov}:seeded:{yyyymmdd}). |
services/location/harvest/governor.go |
services/location/harvest/governor.go |
harvest:outbox:{id} |
STRING (JSON) | 72 h | A paid harvest answer stored before its write and deleted once committed; cron:harvest_outbox_sweep replays leftovers. |
services/location/harvest/outbox.go |
services/location/harvest/outbox.go |
burst:smcell:{cell}:{yyyymmddhh} |
INT | 1 h | Paid search-more lookups started in one area this hour (40). | services/location/location_search_more.go |
services/location/location_search_more.go |
harvest_user:{id}, harvest_device:{hash}, harvest_ip:{ip} |
INT | 1 h | Hourly paid-request ceilings (90 / 120 / 1500) checked just before a paid reservation. | middleware/rate_limiter.go |
middleware/rate_limiter.go |
gov:breaker:open, gov:breaker:probe_needed, gov:breaker:probe, gov:outcomes |
STRING / LIST | 15 min / until closed / 30 s / 60 s | Provider circuit breaker: open window, half-open marker, single probe lease, last 20 call outcomes. | services/location/harvest/governor.go |
services/location/harvest/governor.go |
gov:slots |
ZSET | 30 s leases | Cluster-wide lease set bounding concurrent provider calls (burst_slot_limit). |
services/location/harvest/governor.go |
services/location/harvest/governor.go |
burst:photos:{yyyymmdd} |
INT | 24 h | Global per-day ceiling on harvested-place thumbnail downloads (BURST_PHOTO_DAILY_CEILING, default 50000; 0 disables). |
services/location/location_burst.go |
services/location/location_burst.go |
Presence & active location¶
| Key Pattern | Type | TTL | Purpose | Set By | Read By |
|---|---|---|---|---|---|
presence:{user_id} |
STRING ("1") |
3 min | Heartbeat marker, user is online if key exists. Refreshed by client ping. | services/presence/presence_service.go |
services/chat/service.go, services/friend/friend_service.go (via MGet) |
active_location:{user_id} |
STRING (JSON) | configurable | User's currently-active shared location (the live pin). Deleted when user toggles off. | services/presence/presence_service.go |
services/presence/presence_service.go, services/friend/friend_service.go (via MGet) |
user:location:{user_id} |
STRING (JSON: {lat, lng, updated_at, arrived_at}) |
24 h | Latest location + stay-duration tracking. Backbone of nearby-friends discovery. Deleted when the user turns is_location_shared off or stops an active-location session; readers re-check is_location_shared anyway, since the TTL can outlive the toggle. |
services/friend/friend_service.go |
services/friend/friend_service.go, services/discovery/service.go, sim workers |
Chat & messaging¶
| Key Pattern | Type | TTL | Purpose | Set By | Read By |
|---|---|---|---|---|---|
chat:messages:{chat_id} |
LIST | 24 h | Cached recent messages for a chat (trimmed to 100). Read-through on hit, DB fallback on miss. | services/chat/service.go |
services/chat/service.go |
chat:online:{event_id}:{user_id} |
STRING | 1 h | Marker that {user_id} is currently active in event {event_id}. Deleted on offline. |
services/chat/service.go |
services/chat/service.go |
chat:client_msg:{chat_id}:{user_id}:{client_msg_id} |
STRING | 30 s claim, then 24 h | Send dedup: pending while the first send runs, then the sent message JSON returned to a resend. |
services/chat/service.go |
services/chat/service.go |
chat:event:{event_id} |
Pub/Sub channel | n/a | Cross-pod chat fanout channel. Envelope {opid, xuid?, p}: opid is the publishing pod's UUID (subscriber drops own echoes), xuid skips a UserID on receive, p is the raw WS payload. |
SessionHub.publishRemote (internal/platform/ws/session_hub.go) |
SessionHub.runSubscriber (PSUBSCRIBE chat:event:* on every pod) |
Friends¶
| Key Pattern | Type | TTL | Purpose | Set By | Read By |
|---|---|---|---|---|---|
user:friends:{user_id} |
STRING (JSON) | friendListCacheTTL (10 min) |
Cached accepted-friend list for a user. Invalidated on accept/remove. | services/friend/friend_service.go |
services/friend/friend_service.go |
Live activity (anonymous)¶
Anonymous aggregate powering the public marketing globe (GET /api/v1/stats/live). {w} is a 10-minute window (unix / 600); {bucket} is a coarse 1-degree cell ("lat_lng", values from math.Round). User IDs are fed into HyperLogLog only (irreversible distinct-count), never stored retrievably, so no ID or precise coordinate is kept. Read path merges the current + previous windows and drops any bucket with fewer than 5 distinct users (k-anonymity).
| Key Pattern | Type | TTL | Purpose | Set By | Read By |
|---|---|---|---|---|---|
stats:live:g:{w} |
HLL | 1500 s (25 min) | Global distinct active users in window w. |
services/friend/friend_service.go |
services/friend/friend_service.go |
stats:live:b:{w}:{bucket} |
HLL | 1500 s (25 min) | Distinct active users in a 1-degree bucket for window w. |
services/friend/friend_service.go |
services/friend/friend_service.go |
stats:live:set:{w} |
SET | 1500 s (25 min) | Enumeration of active buckets in window w (which HLLs to read). |
services/friend/friend_service.go |
services/friend/friend_service.go |
stats:live:v1 |
STRING (JSON) | 45 s | Read-through cache of the assembled aggregate served to the globe. | services/friend/friend_service.go |
services/friend/friend_service.go |
stats:live:tmp:g, stats:live:tmp:b |
HLL (temp) | deleted after use | PFMERGE scratch keys for cross-window distinct counts. |
services/friend/friend_service.go |
services/friend/friend_service.go |
Geo discovery¶
| Key Pattern | Type | TTL | Purpose | Set By | Read By |
|---|---|---|---|---|---|
events:geo |
GEO (ZSET) | none | Geospatial index of all event locations. Backs GetNearbyEventIDs via GEORADIUS. |
platform/cache/cache.go::AddEventLocation(s) |
platform/cache/cache.go::GetNearbyEventIDs |
Spatial data
Location coordinates live in Postgres (PostGIS geometry + denormalized lat/lng columns), not Redis. Redis only holds the raw lat/lng geo set above; viewport clustering happens in SQL inside services/discovery/service.go.
Utility caches¶
| Key Pattern | Type | TTL | Purpose | Set By | Read By |
|---|---|---|---|---|---|
link-preview:{sha256(url)} |
STRING (JSON) | 1 h | OpenGraph metadata cache for outbound URL previews. Keyed by SHA-256 hex of the URL. | services/media/link_preview_handler.go |
services/media/link_preview_handler.go |
enrich:place:{location_id} |
STRING (JSON) | 14 d | A place's curated enrichment (discovered links, CID/FID, thumbnail) reused by later captures of the same place without a Serper spend. | services/plan/item_service.go |
services/plan/item_service.go |
enrich:item:lock:{item_id} |
STRING ("1") |
5 min | Per-item work lock (SETNX) so a double-fired link:enrich task can't double-spend the billable pass. Released on completion. |
services/plan/item_service.go |
services/plan/item_service.go |
semantic:extract:{hash} / semantic:select:{hash} |
STRING (JSON) | 14 d | Memoized positive LLM answers, keyed by the first 16 bytes of the SHA-256 of the rendered prompt (hex); identical re-captures skip the model calls. | platform/llm/semantic_resolver.go |
platform/llm/semantic_resolver.go |
loc:area:{normalized_name} |
STRING (JSON, - = negative) |
1 h | Gazetteer area lookup by NFKC-folded name, so repeated area-scoped searches skip the DB; - caches a miss. |
services/location/location_area.go |
services/location/location_area.go |
fx:rates:frankfurter:{BASE}:{YYYY-MM-DD} |
STRING (JSON) | 24 h, or 5 min after a provider failure | Every Frankfurter quote for one base currency and date, fetched in one call. An entry with no quotes is a negative cache (24 h when the provider rejects the base). | platform/currency/fx/frankfurter.go |
platform/currency/fx/frankfurter.go |
embed:qvec:{normalized_query} |
STRING (vector) | 1 h | Memoized query embedding shared by semantic location and event search, so repeat queries skip the embeddings call. | platform/embeddings/query_cache.go |
platform/embeddings/query_cache.go |
Async (Asynq)¶
Background work — both event-driven tasks and cron-driven tasks — runs through Asynq. All of Asynq's Redis keys (asynq:*, including queue lists, scheduled sets, processing zsets, archived/dead-letter, and asynq.Unique locks) are managed internally by the library and treated as opaque per the note at the top of this doc. See backend/infrastructure/async.md for the queue and scheduler model.
Cleanup keys¶
Used by the test-data seeder (cmd/test/data/main.go) to wipe state between simulation runs:
presence:*
user:location:*
active_location:*
user:friends:*
user:privacy:*
If you add a new user-scoped Redis key, add its prefix to that cleanup list too — otherwise stale data leaks between test runs.
Adding a new key¶
- Define the key shape in the service that owns it. Prefer
domain:purpose:{id}(lowercase, colon-separated). - Document it in the table above with type, TTL, purpose, writers, readers.
- If it's user-scoped and ephemeral, add the prefix to the simulation cleanup list.
- If it's a rate-limit key, route it through
middleware/rate_limiter.goso the Lua atomic INCR script is used.