KV 接口

LanBuffer 提供 RESTful 键值存储 API（默认端口 :7002），直接基于 SlateDB 实现，适合轻量级键值数据存取。

启用 KV 服务

在 lanbuffer.toml 中配置：

[servers.kv]
addresses = ["127.0.0.1:7002"]

API 端点

写入值

PUT /kv/v1/keys/{key}

请求体为原始字节（value）。

可选请求头：

请求头	说明
`X-Lanbuffer-Ttl-Ms`	过期时间（毫秒），到期后自动删除

# 写入简单值
curl -X PUT http://127.0.0.1:7002/kv/v1/keys/hello -d 'world'

# 写入带 TTL 的值（60 秒后过期）
curl -X PUT http://127.0.0.1:7002/kv/v1/keys/session:abc \
  -H "X-Lanbuffer-Ttl-Ms: 60000" \
  -d '{"user": "alice"}'

读取值

GET /kv/v1/keys/{key}

返回原始字节。不存在时返回 404 Not Found。

curl http://127.0.0.1:7002/kv/v1/keys/hello
# 输出: world

检查键是否存在

HEAD /kv/v1/keys/{key}

返回 200 OK 并在 content-length 头中包含值的大小。不存在时返回 404。

curl -I http://127.0.0.1:7002/kv/v1/keys/hello

删除键

DELETE /kv/v1/keys/{key}

curl -X DELETE http://127.0.0.1:7002/kv/v1/keys/hello

前缀扫描

GET /kv/v1/keys?prefix=&limit=&cursor=

查询参数：

参数	类型	默认值	说明
`prefix`	string	`""`	键前缀过滤
`limit`	number	1000	最大返回条目数（上限 1000）
`cursor`	string	空	分页游标，从该键之后开始扫描

响应：

{
  "items": [
    {"key": "user:1", "value": "alice", "encoding": null},
    {"key": "user:2", "value": "Ym9i", "encoding": "base64"}
  ],
  "next_cursor": "user:2"
}

值为合法 UTF-8 时以明文返回，encoding 为 null。
值为二进制数据时以 Base64 编码返回，encoding 为 "base64"。
next_cursor 非空表示还有更多数据，用作下次请求的 cursor 参数。

# 扫描所有 user: 前缀的键
curl "http://127.0.0.1:7002/kv/v1/keys?prefix=user:&limit=10"

# 翻页
curl "http://127.0.0.1:7002/kv/v1/keys?prefix=user:&limit=10&cursor=user:2"

批量写入

POST /kv/v1/batch

原子性批量写入，支持混合 put 和 delete 操作。

请求体 JSON：

{
  "ops": [
    {"op": "put", "key": "user:1", "value": "YWxpY2U="},
    {"op": "put", "key": "user:2", "value": "Ym9i"},
    {"op": "delete", "key": "user:3"}
  ]
}

批量操作中的 value 必须使用 Base64 编码。
所有操作在一个事务中原子执行。

curl -X POST http://127.0.0.1:7002/kv/v1/batch \
  -H "Content-Type: application/json" \
  -d '{
    "ops": [
      {"op": "put", "key": "config:theme", "value": "ZGFyaw=="},
      {"op": "put", "key": "config:lang", "value": "emgtQ04="},
      {"op": "delete", "key": "config:old"}
    ]
  }'

注意： 批量 put 操作中的 ttl_ms 字段当前会被忽略（SlateDB WriteBatch 不支持逐键 TTL）。如需 TTL，请使用单独的 PUT 请求。

只读模式

当服务以 --read-only 模式启动时，所有写入操作（PUT、DELETE、batch）将返回 405 Method Not Allowed。

内部实现

所有用户键在 SlateDB 中以 0xA0 前缀存储，与文件系统键空间隔离。
写入默认为非持久化模式（缓冲在 memtable 中），由后台任务定期刷盘。
批量写入通过 SlateDB 事务保证原子性。

使用场景

配置存储 — 存放应用配置、特性开关
会话管理 — 结合 TTL 实现会话过期
缓存层 — 作为应用级缓存使用
元数据存储 — 存放与文件或表关联的元数据