Dowe

SERVER / KV

KV is Dowe's Rust-owned in-memory key-value runtime. It is local by default, can persist binary values under .dowe/kv, and can connect to an authenticated remote KV service.

Database documentation

MENTAL MODEL

Declare a KV handle, then bind each operation

kv creates a server-only handle. Every operation uses query to make a result binding available to the next server statement. The legacy let handle = kv form is rejected.

handler cacheAppointment req
  kv cache name:"clinic"
  query saved kv:cache.set key:"appointment:1" value:{ patientName:"Ana" }
  query value kv:cache.get key:"appointment:1" required:true
  return response json:{ ok:saved.ok data:value }

HANDLE

kv cache name

Opens an isolated named KV database for server behavior.

RESULT

query value

Names the data returned by get, set, delete, keys, or clear.

BOUNDARY

Server only

Views receive a response value, never the KV handle or its remote credentials.

OPERATIONS

Read, write, list, and clear

Keys are static validated strings. Values are controlled JSON data handled by the Rust runtime. required:true turns a missing get into a controlled 404.

kv cache name:"clinic"
query value kv:cache.get key:"appointment:1"
query saved kv:cache.set key:"appointment:1" value:{ status:"scheduled" }
query deleted kv:cache.delete key:"appointment:1"
query keys kv:cache.keys prefix:"appointment:"
query cleared kv:cache.clear

get

Returns JSON data or null; add required:true when absence must be an error.

set

Stores a JSON value and returns ok plus the written key.

delete

Removes a key and returns whether a value was deleted.

keys

Lists visible keys, optionally constrained by a static prefix.

clear

Clears visible keys and returns the number of cleared values.

PERSISTENCE

Memory first, binary fallback

Persistence is opt-in. With persist:true, get checks memory first and then reloads a missing key from .dowe/kv. Without it, the handle stays in memory only.

handler readCachedAppointment req
  kv cache name:"clinic" persist:true
  query value kv:cache.get key:"appointment:1" required:true
  return response json:{ ok:true data:value }

REMOTE SERVICE

Authenticate the declared handle

A remote handle requires host, user, and exactly one token or password. Declare environment names in .env.example, supply values through .env or the process environment, and keep these references server-only.

handler cacheAppointment req
  kv cache name:"clinic" host:env.KV_HOST user:"clinic-api" token:env.KV_TOKEN
  query saved kv:cache.set key:"appointment:1" value:{ patientName:"Ana" }
  return response json:saved

No Redis protocol

KV is a Dowe runtime capability, not an implementation of the Redis wire protocol.

No Node.js

Local handlers compile to shared Rust behavior without node_modules or an external runtime.

Safe authority

Database names, keys, users, and credentials are validated before runtime paths or remote requests are created.