Version 2 by Ron Korving
on Feb 14, 2012 20:50.

compared with
Current by Ron Korving
on Feb 15, 2012 23:28.

(show comment)
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (2)

View Page History
h1. Design goals

h2. API

While libcouchbase exposes the binary Memcached protocol and API, the client SDKs (and therefore also the Node.js SDK) should reflect the well-known Memcached protocol, which resembles the ASCII API.

h2. Error handling

This is common practice in many Node.js libraries, including a lot of APIs internal to Node.js itself.

h1. Architecture proposal

h2. Primary components

h3. libcouchbase (C binding)

The lowest level API, written in C, exposes libcouchbase API virtually 1-to-1.
The only difference is type handling. Buffer lengths don't have to be given to the API, as this is part of the buffer object.
Callbacks are exposed through the EventEmitter. If this proves difficult, we'll just expose the C-logic (set_storage_callback, etc).
No special error handling logic.

h3. api (JavaScript)

The api module can wrap around the binding, providing friendly access to the binding. Its responsibilities:

* turn error codes into Error or CouchbaseError objects.
* synchronous (exceptions) and asynchronous (callback argument) error emission.
* type conversion for special data types.
* callback wrapping, based on a cookie (see: CookieJar) it creates, follows and destroys.
* registering and unregistering event listeners on the libcouchbase binding.

_uses: libcouchbase, CookieJar, errors_

h3. couchbase (JavaScript)

This is what we really want to expose to the user. This module is in charge of:

* creating instance objects (see: CouchbaseInstance).
* emitting errors that are not related to any instances.
* any global configuration that may exist.

_uses: api, CouchbaseInstance, errors_

h3. CouchbaseInstance class (JavaScript)

A friendly API that exposes a single instance and hides any complexities in the underlying APIs. Its responsibilities:

* hiding API that is unrelated to the user.
* value serialization.
* flags management.
* emitting instance related errors.
* self destruction.

_uses: couchbase, api, errors_

h2. Secondary components

h3. CookieJar (JavaScript)

A module that provides cookie generation, access and destruction.

h3. errors (JavaScript)

The errors module contains the CouchbaseError error class that can automatically transform error codes (strerror api) into error strings. Whenever possible, this class is prefered over the generic Error class.

_uses: api_