willb / firkin   0.3.0

Apache License 2.0 GitHub

storage, aging, and access for small structured data

Scala versions: 2.10

firkin

storage, aging, and access for small structured data

dependencies

Use the following resolver:

resolvers += "Will's bintray" at "https://dl.bintray.com/willb/maven/"

To embed the Firkin server in your project:

libraryDependencies += "com.freevariable" %% "firkin" % "0.3.0"

To use the Firkin client in your project:

libraryDependencies += "com.freevariable" %% "firkin-client" % "0.3.0"

usage

Fire up a Firkin server with

com.freevariable.firkin.Firkin.start()(colossus.IOSystem())

or run sbt server/console from a clone of the Firkin repository.

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 cache
  • GET /cache: this will return a list of all the hashes currently in the cache
  • GET /cache/$HASH: this will return the object in the cache with hash $HASH or 404
  • POST /tag with a payload of JSON data containing a tag field and a hash 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 given hash 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

answers to frequently anticipated questions

  1. A firkin is 4.091 L but we can't have fractional ports.
  2. 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.

Statistics

5 Dependencies

No Dependent