Building a KV‑backed session store in Cloudflare Workers

Desired outcome

Create a Cloudflare Worker that reads and writes user session data to a Workers KV namespace, returning JSON that represents the current session or creates a new one when none exists.

Prerequisites

• A Cloudflare account with access to Workers and KV.
• Wrangler CLI installed (version compatible with Workers API).
• Node.js ≥18 for local development.
• The ID of an existing KV namespace (or permission to create one).

Procedure

1. Initialize a Worker project:

   # Run in your terminal
   wrangler init session-worker --type=javascript
   cd session-worker

2. Add the KV binding to wrangler.toml. Replace YOUR_KV_ID with the namespace ID.

   [[kv_namespaces]]
   binding = "SESSION_KV"
   id = "YOUR_KV_ID"
   

3. Implement the fetch handler in src/index.js (or index.ts if using TypeScript).

   addEventListener('fetch', event => {
     event.respondWith(handleRequest(event.request));
   });
   
   async function handleRequest(request) {
     const url = new URL(request.url);
     const cookieHeader = request.headers.get('Cookie') || '';
     const sessionIdMatch = cookieHeader.match(/session_id=([^;]+)/);
     let sessionId;
     let sessionData = {};
   
     if (sessionIdMatch) {
       sessionId = sessionIdMatch[1];
       const raw = await SESSION_KV.get(sessionId, { type: 'text' });
       if (raw !== null) {
         try {
           sessionData = JSON.parse(raw);
         } catch (_) {
           // corrupt data – treat as missing
         }
       }
     }
   
     // If no valid session, create a new one
     if (!sessionId) {
       sessionId = crypto.randomUUID();
       sessionData = { createdAt: new Date().toISOString(), visits: 0 };
       await SESSION_KV.put(sessionId, JSON.stringify(sessionData), { expirationTtl: 3600 });
     }
   
     // Example: increment a visit counter
     sessionData.visits = (sessionData.visits || 0) + 1;
     await SESSION_KV.put(sessionId, JSON.stringify(sessionData), { expirationTtl: 3600 });
   
     const responseBody = {
       sessionId,
       ...sessionData
     };
   
     return new Response(JSON.stringify(responseBody), {
       headers: {
         'Content-Type': 'application/json',
         'Set-Cookie': `session_id=${sessionId}; Path=/; HttpOnly; SameSite=Strict`
       }
     });
   }
   

4. Test locally with Wrangler dev:

   wrangler dev
   # In another terminal
   curl -i http://127.0.0.1:8787/
   

5. Deploy to Cloudflare:

   wrangler publish
   

Expected checks

• The first request returns JSON with a newly generated session_id and a Set-Cookie header.
• Subsequent requests that include the cookie return the same session_id with updated fields (e.g., incremented visits).
• KV namespace shows the session key with a TTL of approximately one hour (visible in the Cloudflare dashboard under Workers → KV → your namespace).
• If the KV namespace is temporarily unavailable, the worker will throw; you can catch the error and return a 503 response with a maintenance message.

Recovery options (rollback)

Because this procedure creates a Worker script and binds a KV namespace, you can roll back by:

1. Deleting the Worker: wrangler delete session-worker (or via the dashboard).
2. Removing the KV binding from wrangler.toml and republishing.
3. Optionally deleting the KV namespace if it was created solely for this worker (wrangler kv: namespace delete SESSION_KV).

Limitations and verification

KV offers eventual consistency; a write may not be immediately visible to subsequent reads for a few seconds. Design session logic to tolerate brief stale reads (e.g., by allowing a short grace period). The default KV namespace size limit is 1 GB; monitor usage in the dashboard and consider upgrading or sharding if you approach that limit.

To verify the TTL behavior, inspect a session key in the KV dashboard shortly after creation and note the Expiration field; it should reflect the expirationTtl value (seconds) you set.