Slap.KV.HTTP.Router (slap_kv v0.6.1)

Copy Markdown View Source

Slap.KV over HTTP, as a Plug. Under :prefix (default /v1/kv, relative to a Plug.forward/4 mount):

  • GET /v1/kv/{partition}/{key} - the value (200, with the version as the ETag), or 404. HEAD is the same without the body.
  • PUT /v1/kv/{partition}/{key} - writes the request body. 204 with the new version as the ETag.
  • DELETE /v1/kv/{partition}/{key} - 204.
  • POST /v1/kv/{partition} - an atomic JSON batch; see the README for operation shapes. Returns {"version": n} and an ETag for mutations, or {"version": null} without an ETag for check-only success.
  • GET /v1/kv/{partition}?prefix=&gte=&lt=&limit=&cursor= - a page of the partition's rows in key order (see Slap.KV.scan/2), as JSON: {"rows": [{"key": k, "value": v}], "cursor": c}, with keys, values and the cursor in unpadded base64url, and cursor null after the last page.

The partition and key are path segments and the scan's bounds query parameters, all percent-encoded (a key may contain / as %2F, and a + in a query parameter must be sent as %2B).

PUT and DELETE take If-Match: "version", and PUT takes If-None-Match: * (the row must not exist); a failed condition is 412, with the current version as the ETag when there is a row.

A 503 response with body overloaded: request was not applied is a definite rejection and includes Retry-After: 1. Other 503 responses leave the write's outcome unknown. Size errors return 413 without Retry-After.

It does not authenticate: put that in front of it.

Options:

  • :prefix - default "/v1/kv".
  • :max_value - the largest value, in bytes (default 8 MiB; 413 above it).
  • :max_batch_body - raw JSON batch body limit (default 16 MiB), independent of decoded owner limits.
  • :cluster - KV cluster serving these requests (default Slap.KV.Cluster).

Each response sends a [:slap, :kv, :http, :request] telemetry event.