bookish-spork

Simple Go application that provides HTTP API to in-memory cache

Public API

• /v1/set - set value to cache

Example:

curl -i -X POST "127.0.0.1:63100/v1/set" -H "Content-Type: application/json" \
                                         -d '{"key": "some-key", "value": "some-value", "ttl": 10}'
HTTP/1.1 200 OK
Date: Fri, 04 Sep 2020 16:33:37 GMT
Content-Length: 0

If ttl is equal or less to 0 it means that the key will never get expired.

• /v1/get/<key> - get value from cache

Example:

curl -s -X GET "127.0.0.1:63100/v1/get/some-key" | json_pp
{
   "value" : "some-value"
}

• /v1/keys - get list of all keys in cache

Example:

curl -s -X GET "127.0.0.1:63100/v1/keys" | json_pp
{
   "keys" : [
      "some-key",
      "some-key-1"
   ]
}

• /v1/remove/<key> - remove key from cache

Example:

curl -i -X DELETE "127.0.0.1:63100/v1/remove/some-key"
HTTP/1.1 204 No Content
Date: Fri, 04 Sep 2020 16:38:33 GMT

• /v1/rpush - add value to a list or create a new one

Example:

curl -i  -X POST "127.0.0.1:63100/v1/rpush" -H "Content-Type: application/json" \
                                            -d '{"key": "some-key", "value": "some-value", "ttl": 0}'
HTTP/1.1 200 OK
Date: Fri, 04 Sep 2020 16:42:13 GMT
Content-Length: 0

curl -i  -X POST "127.0.0.1:63100/v1/rpush" -H "Content-Type: application/json" \
                                            -d '{"key": "some-key", "value": "some-value-1"}'
HTTP/1.1 200 OK
Date: Fri, 04 Sep 2020 16:43:01 GMT
Content-Length: 0

curl -s -X GET "127.0.0.1:63100/v1/get/some-key" | json_pp
{
   "value" : [
      "some-value",
      "some-value-1"
   ]
}

• /v1/lindex/<key>/<list-index> - get value by the index in list

Example:

curl -s -X GET "127.0.0.1:63100/v1/lindex/some-key/0" | json_pp
{
   "value" : "some-value"
}

curl -s -X GET "127.0.0.1:63100/v1/lindex/some-key/1" | json_pp
{
   "value" : "some-value-1"
}

curl -s -X GET "127.0.0.1:63100/v1/lindex/some-key/2" | json_pp
{
   "value" : null
}

curl -s -X GET "127.0.0.1:63100/v1/lindex/some-key/-2" | json_pp
{
   "error" : "index can't be negative"
}

• /v1/hset - add key-value pairs to hash map or create a new one

Example:

curl -i  -X POST "127.0.0.1:63100/v1/hset" -H "Content-Type: application/json"
                                           -d '{"key": "some-hm", "value": {"k0": "v0", "k1": "v1"}, "ttl": 0}'
HTTP/1.1 200 OK
Date: Fri, 04 Sep 2020 16:46:32 GMT
Content-Length: 0

curl -s -X GET "127.0.0.1:63100/v1/get/some-hm" | json_pp
{
   "value" : {
      "k1" : "v1",
      "k0" : "v0"
   }
}

• /v1/hget/<key>/<hash-map-key> - get a value by hash map key

Example:

curl -s -X GET "127.0.0.1:63100/v1/hget/some-hm/k0" | json_pp
{
   "value" : "v0"
}

curl -s -X GET "127.0.0.1:63100/v1/hget/some-hm/k1" | json_pp
{
   "value" : "v1"
}

curl -s -X GET "127.0.0.1:63100/v1/hget/some-hm/k3" | json_pp
{
   "value" : null
}

You could also use HTTP API client in Go to access the API.

Service API

Service API provides standard pprof endpoints. By default, it listens at port 63101.

Example of fetching profile over HTTP:

go tool pprof http://127.0.0.1:63101/debug/pprof/profile

You could also visit http://127.0.0.1:63101/debug/pprof/ in your browser and do some profiling.

Build

Use the following command to build binary:

make build

Or you can build Docker image:

docker build -t bookish-spork .

Running

Example of config file: bookish-spork.yaml

Running locally:

./bookish-spork --config <path-to-yaml-config>

Running in Docker (requires bookish-spork image to be build, see the commands above):

docker run -p 63101:63101 -p 63100:63100 \
           -v (pwd)/bookish-spork.yaml:/etc/bookish-spork/bookish-spork.yaml \
           bookish-spork

Note, that running the command above you should have bookish-spork.yaml locally.

Testing

Use the following command to run acceptance tests (you will need docker-compose):

make acc-tests

Use the following command to run only unit-tests and linters:

make tests

Use the following command to run only unit-tests:

make unittest

Linters

Use the following command to run golangci-lint:

make golangci-lint

Use the following command to run golangci-lint with unit-tests:

make tests

TODO

• Auth
• Scaling support
• Load testing
• Add ability to dump cache to disk
• Code refactoring of http and qqcache packages
• Add missing functions to work with list and hash maps