couchbase-proxy

A Java proxy to expose basic Couchbase API via a simple REST API. The only need for this project is a problem in Coucbase node.js client library which fails if you feed it with too many documents to save. Depending on the machine, it can handle a maximum of 50-100 documents at a time. Feed it more and it just halts with 100% CPU. See JIRA bug JSCBC-14.

Feel free to fork and extend if necessary.

REST API

Currently only the following API methods are supported

• gets - Get one or more documents by keys. Returns the value (document) and CAS for each key.
• set - Save one document, no checks are done.
• cas - Save one document, first checking the CAS value.

The following REST API is exposed

• GET /bucket/key - Get a single document with key key from bucket bucket.
• GET /bucket?keys=key1,key2,key3 - Get multiple documents with keys key1, key2, key3 from bucket bucket.
• POST /bucket/key - Save a single document with key key in bucket bucket. The document is passed as the POST body. If the document exists, it is overwritten.
• POST /bucket/key?cas=1234567890 - Save a single document with key key in bucket bucket. The passed cas parameter contains a CAS value to be used when saving so concurrent modifications are detected.

The GET methods return array of documents in the following JSON format. If a single document is requested, a single-element array is returned. When an err element is present, the document was not retrieved and the doc, cas and key elements are not present. And vice-versa.

{
  "doc": document-as-string,
  "cas": cas-value-as-long,
  "key": document-key-as-string,
  "err": {
    "code": error-code-as-int,
    "message": error-message-as-string
  }
}

In case or errors all methods return the error in the following JSON format

{
  "err": {
    "code": error-code-as-int,
    "message": error-message-as-string
  }
}

The following errors indicate issues when communicating with this proxy

• 2 - Invalid resource. The endpoint is incorrect and not supported.
• 3 - No bucket provided or bucket is not supported. Missing the bucket element of the REST endpoint or it was provided but not configured to be proxied.
• 4 - No document key(s) provided - neither as part of the REST endpoint path nor via the keys parameter.
• 5 - No keys found in the keys parameter. The keys parameter is a comma-separated value.
• 6 - Unexpected internal error.
• 7 - Invalid CAS value.
• 8 - Unsupported content type. Only application/json content type is supported and must be explicitly set when send POST requests.
• 9 - Unsupoorted method type. Only GET and POST are supported.

The following errors indicate issues when communicating with Couchbase server

• 10 - Unable to save the document.
• 12 - CAS value mismatch. The document has been modified.
• 13 - No such document.
• 14 - Interrupted while executing command.

Build

It's built with Maven. Just execute mvn verify and you will have the JAR in the target folder. Start it as simply as java -jar target/couchbase-proxy-1.0.jar.

$ mvn verify
$ java -jar target/couchbase-proxy-1.0.jar

Configuration

The configuration is a simple JSON file in the current directory, named couchbase-proxy.json. An alternative filename can be passed as (the one and only) command line argument.

{
  "server": {
    "port": 8080
  },
  "couchbase": {
    "host": "localhost",
    "port": 8091,
    "buckets": [
      "facebook-pages",
      "facebook-users",
      "account-requests"
    ]
  }
}

The port element specifies a port the REST server will listen on. The couchbase element describes the connection to Couchbase server and the buckets to be supported for proxying. Only calls for the buckets described here will be accepted.