::kv Experimental

Syntax

https://name.rt.ht/::kv
https://name.rt.ht/docs/::kv
https://name.rt.ht/docs/::kv?scope=OG&N=50
https://name.rt.ht/::kv?json

The path is <route path>/::kv, with nothing after ::kv. For the route name/docs, use /docs/::kv. The viewer is read-only.

Parameters

scope

One of the scopes you can see. An unknown name returns 400 and a hidden scope returns 403, both as JSON with "error": "BAD_SCOPE".

key

A key to show. It needs scope, otherwise the answer is 400 with "error": "SCOPE_REQUIRED".

raw

With key, returns the value bytes as application/octet-stream.

json

Selects JSON mode. A request whose Accept header contains application/json selects it too.

N

The page size. The default is 25, also for 0 and for values that are not numbers. Other values are truncated to an integer and clamped to 1 through 1,000.

cursor

The cursor of the next page. It is honored only together with scope, because cursors belong to one list.

Scopes

The viewer shows the six scopes of env.KV.open(). The owner of the route sees all six. Every other signed-in visitor sees only the first three, always for their own email.

domain is the first segment of the route key: the bare label for name.rt.ht, and the full hostname for a custom domain. route is the route key. See Storing data in KV.

Response

JSON, HTML and raw responses carry Cache-Control: no-store. Errors about parameters, keys and KV are JSON even in HTML mode.

A list

An object with route, domain, user and N, plus scope when you pass one, and scopes. Each entry of scopes is named by its type and holds space, keys (each { name, expiration?, metadata? }), list_complete and cursor?. A name is relative to its scope.

A single key

An object with route, domain, user, scope, key, size, metadata and value. size is in bytes. encoding is "base64" when the value is not valid UTF-8, and value is then base64.

The viewer page

Each scope card shows its label and a {} JSON link, the space values, a key count (with + when the list is incomplete), key links with their expiry times and a "more…" link. The single-key view shows the key, size, encoding, metadata and value, with ⬇️ raw and {} JSON links.

Access

The viewer needs sign-in. It answers before the access gates, so edge:user is not applied. What a visitor can read depends on the scopes above, and the owner sees all of them.

Examples

Link to the viewer

<a href=::kv>KV</a>

On https://name.rt.ht/docs/, the relative link opens the viewer of the route name/docs.

Read one key

https://name.rt.ht/::kv?scope=UR&key=visits
https://name.rt.ht/::kv?scope=UR&key=visits&json

Sign in, then open the URLs to see the visits key that the per-user example in Adding sign-in stores in the UR scope.

Specifications

Not part of any specification. ::kv is an RTEdge.net feature that reads Workers KV.

Availability

See also

• Storing data in KV
• KVNamespace
• env
• *
• Edge worker runtime
• URL suffixes