Route-scoped KV at the edge — what shipped, what we deferred, and why

The ask landed in almost every v1.0 beta review: feature flags, rate limiters, session tokens. Edge functions worked great as long as they were stateless; anything with memory had to round-trip to the origin.

v1.0.2 (June 2026) shipped a 256 KB preview tier. v1.2 (March 2027) is the GA shape. This post documents what landed, what we deferred, and why each call was made — for customers planning against the surface and for the future-self who'll re-evaluate when the next round of friction shows up.

The shape that landed

import { kv } from "yourspace:edge";

export default async function handler(req, ctx) {
  const sessionToken = req.headers.get("authorization");
  const session = sessionToken
    ? await kv.get(`sessions/${sessionToken}`)
    : null;

  if (req.url.pathname.startsWith("/admin") && !session) {
    return ctx.redirect("/login");
  }

  return ctx.next();
}

• 1 MB per key, 5 million keys per site. Free tier carries 100,000 keys; Indie carries 1M; Team carries 5M. Above that, Enterprise.
• Regional reads, write-through to the home region. Eventually consistent within a few hundred milliseconds across every region.
• Scoped to the site by default. No accidental cross-site reads; no cross-tenant writes.
• Route-scoped optionally. A function can declare narrower scoping in the route block (kv: read-only for example) so a function that should only read flags cannot also write them.
• Visible in the dashboard. yourspace kv ls lists keys; the dashboard's KV browser opens a key's value (capped at 1 MB with a streaming download for the rest if needed).

What we deferred

Three things asked for, three things deferred, three reasons.

Cross-site KV — deferred

The shape would be useful for a federated identity provider site that needed to be readable from member sites in the federation. Deferred because the access-control posture for cross-site reads is non-trivial — the abuse vector (a malicious member of a federation reading the federation's secrets) needs more design than v1.2 had room for.

The workaround: an edge function on Site A makes an authenticated HTTP request to Site B's API surface, which reads its own KV. Slower, but scoped to whatever Site B's API explicitly exposes.

Strong consistency — deferred

The read-after-write contract is "eventually consistent across regions, strongly consistent within a region." A few customers asked for "strongly consistent everywhere" — useful for distributed-counter use cases.

Deferred because Raft-for-KV is its own substantive workstream. The cross-region-consensus work that landed in v2.0 covers deploy-log ordering, not arbitrary KV. We ship cross-region consensus for KV when (a) enough customers ask for it AND (b) the use case can't be served by the home-region read model.

Atomic multi-key operations — deferred

kv.transaction(key1, key2, ...) would let you read-modify-write multiple keys atomically. Two customers asked.

Deferred because the implementation cost is high (transaction log + replay across regions) and the use case (typically: "increment counter A and write to log B atomically") usually has a single-key alternative (write a structured object that carries both the counter and the log entry; eventually-consistent counter behaviour is acceptable for analytics-shaped use cases).

If a third customer asks AND the use case is genuinely multi-key-atomic-or-broken, the workstream graduates from backlog.

Cost shape

The dashboard's billing pane breaks KV by:

• Reads — billed per million; included up to a tier ceiling.
• Writes — billed per million; same.
• Storage — billed per GB-hour; the Free tier ceiling is 50 MB total, Indie is 5 GB, Team is 50 GB.
• Egress — only billed if a KV value is shipped to a region outside its home; in-region reads are free.

A customer with 1 MB values reading them once per request hits the Free-tier ceiling on storage at roughly 50 keys; the cost shape encourages smaller values, which is also what makes KV fast.

The privacy contract holds

Same contract as the rest of the platform: the keys you write are yours; we don't introspect them, surface them in analytics, or retain them past your retention setting. The audit log of who read or wrote which key — that's available to you, scoped to your site, and never copied across the privacy boundary.

Try it

yourspace kv set flags/homepage-v2 on
yourspace kv get flags/homepage-v2
yourspace kv ls

Full docs at /docs/edge-functions#kv. The migration story for sites coming off the v1.0.2 256 KB preview tier is there too — same key namespace, same API, just a larger ceiling.