Build a Praxa edge backend with Cloudflare Workers

​

Prerequisites

• a trusted server runtime and application authentication boundary;
• a disposable personal workspace Praxa key with only the tutorial’s required scopes;
• synthetic input plus a persisted application request ID for replay tests;
• a fake upstream for unit tests and a non-production environment for canaries;
• an acceptance assertion that proves the Worker keeps the key secret, admits one task, and safely projects readback.

​

1. Declare and add the secret

{
  "name": "praxa-task-edge",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-01"
}

npx wrangler secret put PRAXA_API_KEY

​

2. Implement the Worker

import { authenticateApplicationRequest } from "./auth";

type Env = { PRAXA_API_KEY: string };

async function deterministicKey(principalId: string, requestId: string) {
  const bytes = new TextEncoder().encode(principalId + "\0" + requestId);
  const digest = await crypto.subtle.digest("SHA-256", bytes);
  const hex = [...new Uint8Array(digest)]
    .map((byte) => byte.toString(16).padStart(2, "0"))
    .join("");
  return "worker:" + hex;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname !== "/api/tasks" || request.method !== "POST") {
      return new Response("Not found", { status: 404 });
    }

    const principal = await authenticateApplicationRequest(request, env);
    if (!principal) return new Response("Unauthorized", { status: 401 });

    const body = await request.json<{ task?: unknown; requestId?: unknown }>();
    if (
      typeof body.task !== "string" ||
      body.task.length < 1 ||
      body.task.length > 16_000 ||
      typeof body.requestId !== "string" ||
      body.requestId.length < 16 ||
      body.requestId.length > 128
    ) {
      return new Response("Invalid request", { status: 400 });
    }

    const key = await deterministicKey(principal.id, body.requestId);
    const upstream = await fetch("https://api.praxa.io/v1/execute", {
      method: "POST",
      headers: {
        authorization: "Bearer " + env.PRAXA_API_KEY,
        "content-type": "application/json",
        "idempotency-key": key,
      },
      body: JSON.stringify({
        apiVersion: "v1",
        requestId: key,
        mode: "task",
        task: { input: body.task },
        idempotencyKey: key,
      }),
    });

    return new Response(upstream.body, {
      status: upstream.status,
      headers: {
        "content-type": upstream.headers.get("content-type") ?? "application/json",
        "cache-control": "no-store",
      },
    });
  },
};

​

3. Test locally

1. Authentication runs before parsing or forwarding consequential work.
2. Unknown methods and routes fail closed.
3. Oversized input never reaches Praxa.
4. Exact retries preserve the upstream idempotency key.
5. The key never appears in the response, logs, or thrown errors.
6. Every response carrying a run or problem is no-store.

​

4. Verify after deployment

​

Troubleshooting

​

Best practices

• Store the key as a Worker secret, never a vars value.
• Validate authentication and body size before upstream work.
• Reuse one stable idempotency key per logical request.
• Use explicit AbortSignal deadlines for upstream calls.
• Rate-limit by the authenticated application principal.
• Test locally with a fake upstream, then run a disposable deployed canary.

​

Optimize for production

• Reuse one configured HTTP or SDK client per process and bound concurrent upstream work.
• Prefer durable admission plus asynchronous readback over holding application requests open.
• Cache only non-sensitive, tenant-scoped reads within their documented freshness window.
• Measure p50/p95 latency, admission-to-terminal time, retries, conflicts, and connection reuse before tuning.

​

Cleanup and next steps

1. Revoke the disposable Praxa key and require a later request to fail.
2. Remove synthetic application records and any temporary environment files.
3. Cancel or archive unresolved test runs according to the application policy.
4. Retain only redacted request, run, and verification identifiers needed for the test record.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?