storage, aging, and access for small structured data
Fire up a Firkin server with
com.freevariable.firkin.Firkin.start()(colossus.IOSystem())
or sbt server/console
.
You'll then have a server running on port 4091. You can store and access data via the following HTTP routes:
POST /cache
with a payload of JSON data: this will store the object you provided and redirect you to its location in the cacheGET /cache
: this will return a list of all the hashes currently in the cacheGET /cache/$HASH
: this will return the object in the cache with hash$HASH
or 404POST /tag
with a payload of JSON data containing atag
field and ahash
field: this will create a tag mapping from the value of the tag field to the document with the given hash, redirecting you to a URI for this tag. The document with the givenhash
must exist.GET /tag/$TAG
: this will resolve the tag given by$TAG
and redirect you to the document it points to (returning 404 if there is no such tag)
Submitting empty POST data or submitting invalid JSON as POST data will result in various 4xx errors.
To interact with Firkin using curl
, try the following:
% curl -i -d '{"foo":"bar"}' http://localhost:4091/cache
HTTP/1.1 302 Found
Location: http://localhost:4091/cache/a5e744d0164540d33b1d7ea616c28f2fa97e754a
Content-Length: 0
% curl http://localhost:4091/cache/a5e744d0164540d33b1d7ea616c28f2fa97e754a
{"foo":"bar"}
% curl http://localhost:4091/cache/
{"cachedKeys":["a5e744d0164540d33b1d7ea616c28f2fa97e754a"]}
% curl -i -d '{"tag":"foobar", "hash":"a5e744d0164540d33b1d7ea616c28f2fa97e754a"}' http://localhost:4091/tag
HTTP/1.1 302 Found
Location: http://localhost:4091/tag/foobar
Content-Length: 0
% curl -L -i http://localhost:4091/tag/foobar 2015-05-19 10:42:01 willb ttys000
HTTP/1.1 302 Found
Location: http://localhost:4091/cache/a5e744d0164540d33b1d7ea616c28f2fa97e754a
Content-Length: 0
HTTP/1.1 200 OK
Content-Length: 13
{"foo":"bar"}
To interact with Firkin using its Scala client library, try the following:
scala> val client = new com.freevariable.firkin.Client("localhost", 4091)
client: com.freevariable.firkin.Client = com.freevariable.firkin.Client@3f342608
scala> client.put("""{"foo": "bar"}""")
res0: String = http://localhost:4091/cache/a5e744d0164540d33b1d7ea616c28f2fa97e754a
scala> client.getOrElse("a5e744d0164540d33b1d7ea616c28f2fa97e754a", "sorry!")
res1: String = {"foo":"bar"}
scala> client.putTag("foobar", "a5e744d0164540d33b1d7ea616c28f2fa97e754a")
scala> client.getTag("foobar")
res2: Option[String] = Some({"foo":"bar"})
scala> client.publish("foobar-2", """{"foo": "bar"}""")
res0: String = http://localhost:4091/tag/foobar-2
- A firkin is 4.091 L but we can't have fractional ports.
- In order: it's useful to have a sink for relatively small structured data that you generate with one thing and want to consume with another. Also: NIH.