Public KV
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
data
docker
include
priv
rel
src
.gitignore
Dockerfile
Makefile
README.md
erlang.mk
pubkv.d
relx
relx.config

README.md

Public KV

FAQ

Please see FAQ

Command line API

KV=https://kv.jamhed.tk
UUID=`curl -s $KV/uuid`
curl -XPUT -d some-data $KV/key/$UUID/some-key
# returns ok
curl $KV/key/$UUID/some-key
# returns some-data

In browser API

Suppose you want to store something from script running in browser, and then retrieve the value from somewhere else. This is a primitive key-value store exactly for that.

Usage example (from browser):

function store(id, obj) {
    $.ajax({
        url: 'https://kv.jamhed.tk/key/bceea91e-d3a0-45fc-9a8a-5d8fdb6047f2/' + id,
        type: 'PUT',
        data: JSON.stringify(obj),
        contentType: "application/json",
        processData: false,
    });
}

store('what-ever-key', { data: "value" });

Setup

# erlang must be installed (see docker image for mandatory erlang components)
make

Run

_rel/pubkv_release/bin/pubkv_release start

Setup and run with Docker

You can either manually create a docker image from supplied docker-file, or to use an image from docker hub repository:

mkdir Mnesia
docker run -td -v $(pwd)/Mnesia:/src/pubkv/_rel/pubkv_release/Mnesia -p 10080:10080 jamhed/pubkv

Live Demo

asciicast

API

Generate UUID

KV=https://kv.jamhed.tk
UUID=`curl -s $KV/uuid`

Put

curl -X PUT -H "Content-Type: application/json"  -d '{"key": "json data"}' $KV/key/$UUID/some-data
curl -X PUT -H "Content-Type: application/json"  -d '{"key": "other data"}' $KV/key/$UUID/some-other-data

Returns: HTTP 200, ok. Keys will be created with default TTL=24*3600 seconds (one day).

Put with TTL

curl -X PUT -d data $KV/key/$UUID/some-key?ttl=60

TTL = Time To Live in seconds. Key will be deleted after TTL will expire.

Persistent keys

curl -X PUT -d data $KV/key/$UUID/some-key?ttl=keep

Hidden keys

curl -X PUT -d data $KV/skey/$UUID/hidden-key
curl $KV/skey/$UUID/hidden-key
curl -X DELETE $KV/skey/$UUID/hidden-key

Hidden keys (skey) are stored as sha256 hashes, and are not visible in keys list response to curl $KV/skey/$UUID.

List keys

curl $KV/key/$UUID

Returns: HTTP 200, ["some-data", "some-other-data"] or []

Get

curl $KV/key/$UUID/some-data

Returns: HTTP 200, {"key": "json data"}

curl $KV/key/$UUID/some-missing-key

Returns: HTTP 404, not found

Delete

curl -X DELETE $KV/key/$UUID/some-data
curl -X DELETE $KV/key/$UUID

Returns: HTTP 200, ok

Readonly Aliases

Create an UUID alias only for reading (write and delete take no effect)

ALIAS=`curl -s $KV/alias/$UUID`
curl $KV/key/$ALIAS/some-data

SHA256 keys

curl -X PUT -d whateverdata $KV/sha/whateverkey
curl -X GET $KV/sha/whateverkey
curl -X DELETE $KV/sha/whateverkey

Replication

You can run several copies of KV store, all of them synchronized. Here is an example with docker image:

docker run -td --name pubkv-slave-1 jamhed/pubkv slave
SLAVE_NODE=`docker exec pubkv-slave-1 info`
docker run -ti --name pubkv-master jamhed/pubkv master "'$SLAVE_NODE'"

After this two instances will be completely synchronized. If one goes down another will continue to work. You can have more than one slave node: master "'$SLAVE_NODE_1','$SLAVE_NODE_2'", and so on.

Event API

One can subscribe to UUID events delete and update, by using Server Side Events (SSE, EventSource)

curl $KV/watch/$UUID
# update some/key
# delete some/key

CORS Support

Each OPTIONS request returns response with headers set:

Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: VALUE_OF(Access-Control-Request-Method)
Access-Control-Allow-Headers: VALUE_OF(Access-Control-Request-Headers)

Therefore allowing use from everywhere.

Closing words

Public beta available at: https://kv.jamhed.tk

Source code: https://github.com/jamhed/pubkv

Docker image: https://hub.docker.com/r/jamhed/pubkv/