Skip to content
cfdemo.link

Data & Messaging: Storage and Protocol Specs

Storage Architecture

Section titled “Storage Architecture”

CF Messenger chooses each storage primitive for what it does best—no single database for everything.

Storage by Use Case

Section titled “Storage by Use Case”
  • SESSION_KV: 20-minute TTL tokens, presence heartbeats, and bot rotation metrics. Globally replicated for rapid socket revalidation.
  • Durable Objects (ChatRoom, PresenceRoom): Handle broadcast logic, schema enforcement (Zod), and rate limiting with in-memory buffers.
  • Hibernation Mirror: When a Durable Object hibernates, the latest buffer is mirrored to KV for rapid bootstrapping.

Data Model

Section titled “Data Model”
EntityStorageKey Attributes
UserSeeded listID, persona, avatar, archetype hints
SessionSESSION_KVSessionID, UserID, expiry, nonce, location hint (uk)
MessageDO memoryID, RoomID, Sender, Type, Timestamp, Content
PresenceSESSION_KV + DOStatus flag, last heartbeat, routing hint

WebSocket Protocol

Section titled “WebSocket Protocol”

Every payload is JSON-formatted and validated via Zod.

Primary Message Types

Section titled “Primary Message Types”
  • chat: Text ≤ 2048 characters.
  • nudge: Screen shake/alert limited to 3 per 10s.
  • wink: Flash-style animated notifications keyed by winkId.
  • typing: TTL-bound typing indicator (3 seconds).
  • presence: Online/busy/away updates pushed to the PresenceRoom.

Handlers & Constraints

Section titled “Handlers & Constraints”
  • NudgeHandler: Rate-limited per user (3 per 10s).
  • TypingHandler: Emits a forced typing:false after TTL to clear stale UI indicators.
  • WinkHandler: Combines timestamps and winkId hashes to synchronise playback across clients.

Standard Edge API Spec (v1.0)

Section titled “Standard Edge API Spec (v1.0)”

This section defines the unified API structure for applications on the *.cfdemo.link zone.

Request/Response Envelope

Section titled “Request/Response Envelope”

All endpoints MUST use a consistent JSON structure to facilitate automated parsing:

type ApiResponse<T> = {
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
  meta: { timestamp: number; requestId: string };
};

Endpoint Hierarchy

Section titled “Endpoint Hierarchy”
Endpoint RootMethodUse CasePrimary Storage
/api/auth/loginPOSTTurnstile-gated session creationKV
/api/auth/meGETSession validation/Profile fetchKV/D1
/api/data/:collectionGET/POSTRelational CRUD (Orders, Users)D1
/api/ws/room/:idGET (Upgrade)Real-time synchronisationDurable Object
/api/ws/presenceGET (Upgrade)Global presence trackingDurable Object

Sources & References

Section titled “Sources & References”