[explorer] implement local kv api #12075
Draft
+1,093
−19
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Pass a JSON binding map to the Local Explorer worker that maps binding names to actual namespace IDs, allowing correct ID resolution when binding name differs from namespace ID.
🦋 Changeset detectedLatest commit: 1dc92f9 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 |
create-cloudflare
@cloudflare/kv-asset-handler
miniflare
@cloudflare/pages-shared
@cloudflare/unenv-preset
@cloudflare/vite-plugin
@cloudflare/vitest-pool-workers
@cloudflare/workers-editor-shared
@cloudflare/workers-utils
wrangler
commit: |
emily-shen
force-pushed
the
emily/api
branch
3 times, most recently
from
39c3572 to
ad0bcea
Compare
Add REST API endpoints for KV storage operations: - GET /storage/kv/namespaces - List namespaces - GET /storage/kv/namespaces/:id/keys - List keys - GET /storage/kv/namespaces/:id/values/:key - Get value - PUT /storage/kv/namespaces/:id/values/:key - Write value - DELETE /storage/kv/namespaces/:id/values/:key - Delete key - POST /storage/kv/namespaces/:id/bulk/get - Bulk get values
vicb
reviewed
Jan 24, 2026
| const response = await fetch( | ||
| `http://${ip}:${port}/cdn-cgi/explorer/api/storage/kv/namespaces` | ||
| ); | ||
| const text = await response.text(); |
Contributor
There was a problem hiding this comment.
Should it be JSON (and should we check the content type ?)
vicb
reviewed
Jan 24, 2026
Comment on lines
+19
to
+28
| const KVNamespaceSchema = z.object({ | ||
| id: z.string(), | ||
| title: z.string(), | ||
| }); | ||
|
|
||
| const KVKeySchema = z.object({ | ||
| name: z.string(), | ||
| expiration: z.number().optional(), | ||
| metadata: z.unknown().optional(), | ||
| }); |
Contributor
There was a problem hiding this comment.
Do ns id, title, key name have max length?
vicb
reviewed
Jan 24, 2026
| const bindingName = bindingMap[namespaceId]; | ||
| if (!bindingName) return null; | ||
|
|
||
| return env[bindingName] as KVNamespace; |
Contributor
There was a problem hiding this comment.
Validate against the schema before casting?
vicb
reviewed
Jan 24, 2026
| direction: z | ||
| .enum(["asc", "desc"]) | ||
| .default("asc") | ||
| .describe("Direction to order namespaces"), |
Contributor
There was a problem hiding this comment.
Suggested change
| .describe("Direction to order namespaces"), | |
| .describe("Namespaces sort order"), |
vicb
reviewed
Jan 24, 2026
| // KV Helpers | ||
| // ============================================================================ | ||
|
|
||
| // Get a KV binding by namespace ID |
vicb
reviewed
Jan 24, 2026
| }, | ||
| }; | ||
|
|
||
| async handle(c: AppContext) { |
vicb
reviewed
Jan 24, 2026
Comment on lines
+105
to
+108
| const aVal = a[order]; | ||
| const bVal = b[order]; | ||
| const cmp = aVal.localeCompare(bVal); | ||
| return direction === "asc" ? cmp : -cmp; |
Contributor
There was a problem hiding this comment.
Suggested change
| const aVal = a[order]; | |
| const bVal = b[order]; | |
| const cmp = aVal.localeCompare(bVal); | |
| return direction === "asc" ? cmp : -cmp; | |
| return (direction === "asc" ? 1 : -1) * a[order].localeCompare(b[order]) |
vicb
reviewed
Jan 24, 2026
| })); | ||
|
|
||
| namespaces.sort( | ||
| (a: { id: string; title: string }, b: { id: string; title: string }) => { |
Contributor
There was a problem hiding this comment.
Could the type be retrieved from the schema instead of duplicated here?
vicb
reviewed
Jan 24, 2026
Comment on lines
+116
to
+117
| const endIndex = startIndex + per_page; | ||
| namespaces = namespaces.slice(startIndex, endIndex); |
Contributor
There was a problem hiding this comment.
nit: inline if not used elsewhere?
Suggested change
| const endIndex = startIndex + per_page; | |
| namespaces = namespaces.slice(startIndex, endIndex); | |
| namespaces = namespaces.slice(startIndex, startIndex + per_page); |
vicb
reviewed
Jan 24, 2026
| } | ||
|
|
||
| const listResult = await kv.list({ cursor, limit }); | ||
| const resultCursor = "cursor" in listResult ? listResult.cursor ?? "" : ""; |
Contributor
There was a problem hiding this comment.
nit: inline in the obj if onyl used once?
vicb
reviewed
Jan 24, 2026
| // Response Helpers | ||
| // ============================================================================ | ||
|
|
||
| export function wrapResponse<T>(result: T) { |
Contributor
There was a problem hiding this comment.
I would love to see more JSDoc across this PR.
We don't know what response this takes nor what it returns
vicb
reviewed
Jan 24, 2026
| title: "Local Explorer API", | ||
| version: "1.0.0", | ||
| description: | ||
| "A local subset of Cloudflare's REST API for exploring resources during local development.", |
Contributor
There was a problem hiding this comment.
A local subset of Cloudflare's REST API
Have we changed our mind on this ?
vicb
reviewed
Jan 24, 2026
| "get-port": "^7.1.0", | ||
| "glob-to-regexp": "0.4.1", | ||
| "heap-js": "^2.5.0", | ||
| "hono": "^4.11.5", |
Contributor
There was a problem hiding this comment.
Curious about why we use hono for vs its size?
Looks like the route matching we do is pretty basic and would not really require an external lib or maybe a tiny one?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
By commit:
Also notes on what i have implemented in the API:
bulk is not actually used in the dash, the dash seems to individually get each value, but that seems silly to do locally so i added bulk get as well.
I have not implemented key metadata (expiration_ttl etc), supports_url_encoding (we assume it is true, might be a legacy thing?), and prefix filtering when listing keys. I also haven't checked if the error codes are correct, DEVX-2426 will followup on errors.
A picture of a cute animal (not mandatory, but encouraged)