Prompt Caching at the Edge: Using CloudFront Functions and Lambda to Speed Up Claude Calls

# Install the AWS SDK for JavaScript (v3) if you need it locally
npm install @aws-sdk/client-cloudfront

// kv-setup.ts – run once with node
import {
  CreateKeyGroupCommand,
  CreateCachePolicyCommand,
  CreateOriginRequestPolicyCommand,
  CreateDistributionCommand,
  CloudFrontClient,
} from "@aws-sdk/client-cloudfront";

const client = new CloudFrontClient({ region: "us-east-1" });

async function createDistribution() {
  // The KV store is defined via a Cache Policy that enables “Cache‑Based Origin Request”.
  // In the console this appears as “Cache key and origin request settings”.
  const cachePolicy = await client.send(
    new CreateCachePolicyCommand({
      CachePolicyConfig: {
        Name: "ClaudePromptCachePolicy",
        // We want the request body (the prompt) to be part of the cache key.
        ParametersInCacheKeyAndForwardedToOrigin: {
          EnableAcceptEncodingBrotli: false,
          EnableAcceptEncodingGzip: false,
          // The request body is not automatically part of the key,
          // so we forward it to the origin (Lambda) where we will hash it.
          // The KV store itself is accessed via the Function, not the cache policy.
        },
        DefaultTTL: 0, // we control TTL manually in the KV store
        MaxTTL: 0,
        MinTTL: 0,
        // Important: Edge Functions can only read from KV if the cache behavior
        // points to a "function association" with “viewer request”.
        // The association is set later in the console or via the API.
        // No extra code needed here.
      },
    })
  );

  // Omitted: create the origin (Lambda ARN) and the distribution.
  // The key point for the beginner is that the distribution must have:
  //   - a Viewer Request Function (our edge function)
  //   - an Origin (our Lambda) for /chat
  //   - the default behavior points to the Lambda.
}
createDistribution().catch(console.error);

// lambda-handler.ts
import { CloudFrontClient, PutKeyValueStoreCommand } from "@aws-sdk/client-cloudfront";

// Claude endpoint – replace with your actual URL and API key.
const CLAUDE_ENDPOINT = "https://api.anthropic.com/v1/complete";
const CLAUDE_API_KEY = process.env.CLAUDE_API_KEY!;

// TTL in seconds for the edge KV entry.
const KV_TTL = 300; // 5 minutes

export const handler = async (event: any) => {
  // -------------------------------------------------
  // 1️⃣ Extract the prompt from the incoming request.
  // -------------------------------------------------
  const body = JSON.parse(event.body);
  const prompt = body.prompt?.trim();
  if (!prompt) {
    return {
      statusCode: 400,
      body: JSON.stringify({ error: "Missing 'prompt' field" }),
    };
  }

  // -------------------------------------------------
  // 2️⃣ Call Claude. (fetch is available in Node 20)
  // -------------------------------------------------
  const claudeResponse = await fetch(CLAUDE_ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": CLAUDE_API_KEY,
    },
    body: JSON.stringify({
      prompt,
      max_tokens: 256,
      temperature: 0.7,
    }),
  });

  if (!claudeResponse.ok) {
    const err = await claudeResponse.text();
    return {
      statusCode: claudeResponse.status,
      body: JSON.stringify({ error: err }),
    };
  }

  const claudeData = await claudeResponse.json();
  const answer = claudeData.completion;

  // -------------------------------------------------
  // 3️⃣ Store prompt → answer in the Edge KV store.
  // -------------------------------------------------
  // The KV store lives on CloudFront, not Lambda, but the SDK
  // lets us write to it from anywhere with the right permissions.
  const cf = new CloudFrontClient({});
  await cf.send(
    new PutKeyValueStoreCommand({
      // “ClaudePromptCache” is the name you gave the KV store
      // when you created the distribution.
      KeyValueStoreName: "ClaudePromptCache",
      Items: [
        {
          Key: prompt, // exact prompt string as the key
          Value: answer,
          // TTL tells the edge when the entry expires.
          // Edge will automatically drop it after 5 minutes.
          // The attribute name is `TTL`, expressed in seconds.
          TTL: KV_TTL,
        },
      ],
    })
  );

  // -------------------------------------------------
  // 4️⃣ Return the answer to the caller.
  // -------------------------------------------------
  return {
    statusCode: 200,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ answer }),
  };
};

import crypto from "crypto";

function hashPrompt(prompt: string): string {
  // Create a hex‑encoded SHA‑256 hash of the prompt.
  // This produces a fixed‑length, URL‑safe string.
  return crypto.createHash("sha256").update(prompt).digest("hex");
}

// invalidate-cache.ts
import {
  CloudFrontClient,
  DeleteKeyValueStoreCommand,
} from "@aws-sdk/client-cloudfront";

const client = new CloudFrontClient({});

export async function clearCache() {
  await client.send(
    new DeleteKeyValueStoreCommand({
      KeyValueStoreName: "ClaudePromptCache",
    })
  );
  console.log("Edge KV store cleared");
}

// cf-function.js
/**
 * CloudFront Function – viewer request.
 * Looks for a cached answer to the incoming prompt.
 * If found, returns it immediately; otherwise lets the request
 * continue to the Lambda origin.
 */

function handler(event) {
  var request = event.request;
  var uri = request.uri; // e.g., "/chat"
  // We only care about POST /chat
  if (uri !== "/chat" || request.method !== "POST") {
    return request; // let everything else pass through
  }

  // -------------------------------------------------
  // 1️⃣ Extract the request body (the prompt JSON).
  // -------------------------------------------------
  // CloudFront Functions can only read the body if the
  // request is sent with the "application/json" content type.
  var body = request.body && request.body.text;
  if (!body) {
    // No body – forward to Lambda for proper error handling.
    return request;
  }

  var prompt;
  try {
    var parsed = JSON.parse(body);
    prompt = parsed.prompt?.trim();
    if (!prompt) throw "missing";
  } catch (e) {
    // Malformed JSON – forward to Lambda.
    return request;
  }

  // -------------------------------------------------
  // 2️⃣ Look up the prompt in the Edge KV store.
  // -------------------------------------------------
  // The KV store is called "ClaudePromptCache". The key is the
  // raw prompt string (or a hash if you used one in Lambda).
  var kvStore = "ClaudePromptCache";
  var cached = KV.get(kvStore, prompt);
  // KV.get returns null if the key does not exist or has expired.

  if (cached) {
    // -------------------------------------------------
    // 3️⃣ Build a synthetic response with the cached answer.
    // -------------------------------------------------
    var response = {
      statusCode: 200,
      statusDescription: "OK",
      headers: {
        "content-type": { value: "application/json" },
        "cache-control": { value: "max-age=0, private" },
      },
      body: JSON.stringify({ answer: cached }),
    };
    // Returning a response short‑circuits the rest of the
    // CloudFront pipeline – Lambda never runs.
    return response;
  }

  // -------------------------------------------------
  // 4️⃣ No cache hit → let the request travel to Lambda.
  // -------------------------------------------------
  return request;
}

npm install @aws-sdk/client-cloudfront

// deploy-function.ts
import {
  CloudFrontClient,
  CreateFunctionCommand,
  PublishFunctionCommand,
} from "@aws-sdk/client-cloudfront";
import * as fs from "fs";

const client = new CloudFrontClient({ region: "us-east-1" });

async function deploy() {
  const code = fs.readFileSync("cf-function.js", "utf8");
  const create = await client.send(
    new CreateFunctionCommand({
      Name: "ClaudePromptCacheFunction",
      FunctionConfig: {
        Comment: "Look up Claude prompt cache at the edge",
        Runtime: "cloudfront-js-1.0", // the only supported runtime
      },
      FunctionCode: Buffer.from(code),
    })
  );
  console.log("Created:", create.FunctionSummary?.ARN);

  // Publishing makes the function live.
  const publish = await client.send(
    new PublishFunctionCommand({
      Name: "ClaudePromptCacheFunction",
      IfMatch: create.ETag, // ensures we publish the right version
    })
  );
  console.log("Published version:", publish.FunctionSummary?.FunctionMetadata?.FunctionARN);
}
deploy().catch(console.error);