couchbase flags proposals

6bit.c

/**
 *
 */


/**
 * Couchbase Datatype Flags
 *
 * These flags help to disambiguate the format and compression of values.
 *
 *
 * There are two forms of disambiguation which the flags must be able to perform:
 *
 * 1) Client interoperability:
 *      This is useful for arbitrary data which the client wishes to store. The
 *      purpose of these flags would be to enable the clients to communicate
 *      with each other and establish a common protocol regarding compression
 *      and data formats.
 *
 * 2) Server Metadata:
 *      In future versions of the server, new features may be added regarding
 *      specialized (but inherently standardized) datatypes. These datatypes
 *      will all be subsets or variations of JSON, and the flags used therein
 *      will be used for efficiency.
 *
 *
 * TODO:
 * It would be nice if we could have a bit used for encoding (or at least
 * telling us whether it's ASCII or not)
 *
 * Legend:
 *
 * [ X ] A relevant bit in the description
 * [ - ] Ignored or reserved bit
 * [ 0|1 ] A bit in another set which must be on (or off)
 *
 */


/* Bit 0
 * First bit for indicating whether the value is 'user' data, or whether it
 * conforms to some pre-defined server type.
 * If the type is 'user', then the rest of the flags follow the UFDT formats,
 * if the type is 'std' then the rest of the flags follow the SFDT formats
 *
 * - - - - - - - X
 *
 */
#define COUCHBASE_FDT_MODE_USER  = 0x0
#define COUCHBASE_FDT_MODE_STD   = 0x1

/* Bits 1,2
 * User format
 * - - - - - X X 0
 */


typedef enum {
    /* blob of bytes */
    COUCHBASE_UFDT_FORMAT_BYTES   = 0x0,
    COUCHBASE_UFDT_FORMAT_JSON    = 0x1,
    COUCHBASE_UFDT_FORMAT_NUMERIC = 0x2,
    COUCHBASE_UFDT_FORMAT_PRIV    = 0x3
} couchbase_ufdt_format_t;

#define COUCHBASE_UFDT_FORMAT_MASK 0x6



/**
 * - - - X X - - 0
 * Bits 3,4
 */

typedef enum {
    COUCHBASE_UFDT_COMP_NONE = 0x0,
    COUCHBASE_UFDT_COMP_GZIP = 0x1,
    COUCHBASE_UFDT_COMP_BZIP = 0x2,
    COUCHBASE_UFDT_COMP_LZO  = 0x3,
} couchbase_ufdt_comp_t;

#define COUCHBASE_UFDT_COMP_MASK 0x18


/**
 * Server datatype flags
 * Bits 1,2
 * - - - - - X X 1
 */

typedef enum {
    COUCHBASE_SFDT_TYPE_DICT = 0x0,
    COUCHBASE_SFDT_TYPE_LIST = 0x1,
    COUCHBASE_SFDT_TYPE_SET  = 0x2
};

/**
 * Examples:
 *
 * LZO-compressed json
 * --- 11 01 0
 *
 * Gzip-compressed 'raw' data:
 * --- 01 00 0
 *
 * Couchbase Ordered Set
 *
 * --- 00 01 1
 */


/**
 * As an extension the flags section may be utilized to determine encoding.
 * Specifically, we will leave the upper 16 bits of the flags alone..
 *
 * According to http://www.hjp.at/zettel/m/memcached_flags.rxml, nothing uses
 * bits 4,5,6 - so we will use them for optional encoding properties..
 *
 * 'User' flags:
 *
 */

typedef enum {
    COUCHBASE_UFL_ENC_UTF8  = 0x0,
    COUCHBASE_UFL_ENC_UTF16 = 0x1,
    COUCHBASE_UFL_ENC_BOM   = 0x2,
    COUCHBASE_UFL_ENC_PRIV  = 0x3
};

#define COUCHBASE_UFL_ENC_MASK 0x30

/**
 * Example:
 * UTF16, bzip-compressed JSON:
 *
 * Datatype: --- 10 01 0
 * Flags: -------- -------- -------- -001----
 */

I like how wireshark displays flags in plaintext files

   Flags: 0x018 (PSH, ACK)
        000. .... .... = Reserved: Not set
        ...0 .... .... = Nonce: Not set
        .... 0... .... = Congestion Window Reduced (CWR): Not set
        .... .0.. .... = ECN-Echo: Not set
        .... ..0. .... = Urgent: Not set
        .... ...1 .... = Acknowledgment: Set
        .... .... 1... = Push: Set
        .... .... .0.. = Reset: Not set
        .... .... ..0. = Syn: Not set
        .... .... ...0 = Fin: Not set