Skip to content

[explorer] add implementation for local KV API (take 2)#12152

Merged
emily-shen merged 9 commits intomainfrom
emily/api
Jan 28, 2026
Merged

[explorer] add implementation for local KV API (take 2)#12152
emily-shen merged 9 commits intomainfrom
emily/api

Conversation

@emily-shen
Copy link
Copy Markdown
Contributor

@emily-shen emily-shen commented Jan 26, 2026

This PR implements the KV api by:

  1. pulling down the cloudflare openapi spec, filtering for the KV subset we need (using filter-openapi.ts, with config in openapi-filter-config-ts).
  2. generating types and zod schemas using hey-api (in local-explorer/generated)
  3. Using hono to route and validate incoming requests

By commit:

rename getLocalExplorerFromEnv() to getLocalExplorerEnabledFromEnv() - a stray fixup from the last PR

Add resource ID to binding name map - since we route by resource id, but the id is not available at runtime, pass in an id to binding name map as a JSON binding

Add script to filter openapi spec down - takes the existing cloudflare openapi spec which is a casual 400k lines and filters it down to just the endpoints we want, and also filters out specific components we have not yet implemented.

This is done via our own parsing script rather than a library because all openapi filtering tools i can find assume that you can annotate the original openapi spec (e.g. with x-ignore). i don't think it would be practical for us to checkout and modify the full openapi spec (again, 400k lines), so instead we have this filtering script. Claude wrote this filtering script, and i've sanity checked it, but tbh i think the best way to review this is to look at the output in openapi.local.json and verify that it is what you expect. The filtering script is configured in openapi-filter-config.ts which makes it easier to extend in the future.
Once we have an openapi spec, we generate zod schemas/types using hey-api. These are in the local-explorer/generated folder.

add implementation for KV API - we use hono to do the routing here, using its middleware to validate the requests using the generated zod schemas.

I've changed the approach since #12075 because I think it will be more maintainable to start from the existing OpenAPI spec (as much as i like the concept of writing the schema in typescript, it doesn't really make sense). Also, the existing openapi spec will not undergo breaking changes without a lot of warning, so given we periodically update this spec, we should always have a compatible subset of the remote APIs. I think it is fine if we have missing APIs, because adding APIs later is a non-breaking change.


  • Tests
    • Tests included/updated
    • Automated tests not possible - manual testing has been completed as follows:
    • Additional testing not necessary because:
  • Public documentation
    • Cloudflare docs PR(s):
    • Documentation not necessary because: experimental wip thing

A picture of a cute animal (not mandatory, but encouraged)


Open with Devin

@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Jan 26, 2026

🦋 Changeset detected

Latest commit: 0ef809f

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@emily-shen emily-shen force-pushed the emily/api branch 2 times, most recently from 19cef98 to 33108bb Compare January 26, 2026 17:31
@github-project-automation github-project-automation bot moved this to Untriaged in workers-sdk Jan 26, 2026
@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new bot commented Jan 26, 2026

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@12152

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@12152

miniflare

npm i https://pkg.pr.new/miniflare@12152

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@12152

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@12152

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@12152

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@12152

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@12152

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@12152

wrangler

npm i https://pkg.pr.new/wrangler@12152

commit: 0ef809f

@emily-shen emily-shen force-pushed the emily/api branch 2 times, most recently from c2d7634 to ee5f9e7 Compare January 26, 2026 17:53
Copy link
Copy Markdown
Contributor

@vicb vicb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did a quick pass and added a few comments.

I still have the same question. What would it like without Hono? If adding 50l could avoid adding 500kB of dependencies maybe it's worth it? (not sure about the 50l nor the 500kB but I think it's worth investigating)

Edit: it looks like hono is only ~20kB and using import { Hono } from 'hono/tiny' could even reduce that. So probably not worth the effort of finding something else.

@emily-shen emily-shen force-pushed the emily/api branch 2 times, most recently from 64ca50e to a4b5c1d Compare January 27, 2026 15:36
@emily-shen emily-shen marked this pull request as ready for review January 27, 2026 15:36
@emily-shen emily-shen requested a review from a team as a code owner January 27, 2026 15:36
Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 5 additional flags.

Open in Devin Review

Copy link
Copy Markdown
Contributor

@petebacondarwin petebacondarwin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good!

@github-project-automation github-project-automation bot moved this from Untriaged to Approved in workers-sdk Jan 27, 2026
Uses a JSON binding in the Local Explorer worker that maps binding names to namespace IDs
@emily-shen emily-shen enabled auto-merge January 28, 2026 15:06
@emily-shen emily-shen added this pull request to the merge queue Jan 28, 2026
Merged via the queue into main with commit 8a210af Jan 28, 2026
40 of 41 checks passed
@emily-shen emily-shen deleted the emily/api branch January 28, 2026 15:58
@github-project-automation github-project-automation bot moved this from Approved to Done in workers-sdk Jan 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

6 participants