Cocained API Reference

1. C++
2. Python
   • cocaine.context package
   • cocaine.decorators package

C++

Binary - it's a compiled binary app loader for the Cocaine cloud which is working with the compiled shared libraries written, for example, on C or C++.

The app is described by the app manifest with the parameters of the app.

For example, the manifest for a binary loader might look this:

{
    "type": "binary",
    "engine": {
        "heartbeat-timeout": 60,
        "pool-limit": 10,
        "queue-limit": 2000,
        "grow-threshold": 1,
        "slave": "/tmp/cocaine/bin/cocaine-slave"
    },
    "args": {
        "name": "libtest.so",
        "config": {
            "nodes": {
                "localhost": 1025
            },
            "groups": [2],
            "log-mask": 8,
            "log": "/dev/stdout"
        }
    }
}

Binary loader is selected if the app type (block type in the manifest) is binary.

There are two mandatory arguments (block args) for the binary loader:

• args:name — the name of the file of the shared library which have to export three user functions.

void *initialize(const char *config, const size_t size);
void cleanup(void *handle);
int process(void *handle, struct binary_io *io);

This file should contain a relative path in the downloaded archive. In the example above, the tar-file root directory should have the libtest.so file.

• args:config — block passed to initialize() as a pointer to an array of characters (and their size). In the example above, it will be a string containing the following information:

{
    "nodes" : {
        "localhost": 1025
    },
    "groups" : [2],
    "log-mask" : 8,
    "log" : "/dev/stdout"
}

This data is not interpreted by binary loader, it’s for your sole use.

void *initialize(const char *config, const size_t size);

Initializes the internal structures of your app and returns a unique pointer that is passed to other functions as the first parameter.

The function is called when your app is being destroyed.

void cleanup(void *handle);

• handle - a pointer which is returned by the initialize() function.

Function is called when a new request is recieved.

int process(void *handle, struct binary_io *io);

• handle — a pointer which is returned by the initialize() function;
• io - structure that describes received block of data on the network;
• io.chunk.data - a pointer to the recieved data;
• io.chunk.size - size of data.

If it necessary to return some data over the network in the response, you can call the function:

binary_write(struct binary_io *io, const void *data, size_t size)

• data - a pointer to the data;
• size - the size of the data;
• io - pointer passed to the user in the process() function.

Python

Packages:

• cocaine.context
• cocaine.decorators

cocaine.context package

Log class

Class which can be used to log into the main server log.

Constructor:

Log()

Methods:

• debug, info, warning, error

These methods write a message to the main log of the server with the appropriate priority (which is described in the method name).

An example:

from cocaine.context import Log
log = Log()
log.info("Hello, World!")

• write, writelines, flush

Internal methods that are needed to support the WSGI specification.

Function manifest()

manifest()

Returns: a dictionary, which was stored in the app manifest with the “args” key, i.e. your own app configuration.

cocaine.decorators package

The package contains a set of decorators that make it much easier to write the code that runs on the Cocained server.

• @zeromq

Decorator expects that the message sent to the decorated method was serialized using the MessagePack library. Decorator deserializes the message and passes it as the first argument to your function. If the return value is string, then it will be sent as is. If the return value is not a string - it will be serialized with the MessagePack library and sent back to the client.

An example:

from cocaine.decorators import zeromq

@zeromq
def function(request):
    return int(request["uuid"]) * 5

• @simple (simple http decorator)

Decorator expects that the message is a MessagePack-serialized dictionary with two required keys (the first key is «meta» and the second is «request»). Decorator deserializes the message and passes the described keys as keyword-arguments.

The return value is sent as the body of a serialzed http-response with a response code 200 and a header «Content-Type: text/plain».

An example:

from cocaine.decorators import simple

@simple
def function(meta, request):
    return "User UID Cookies is %s" % meta["cookies"]["uid"]

• @http

Decorator expects that the message is a dictionary with two required keys (the first key - «meta», the second - «request»), serialized using the MessagePack library. Decorator deserializes the message and passes the described keys as keyword-arguments.

The decorator expects the return value to be a tuple of three elements:

• http-response code;
• list of headers in the form of tuples in the format (header_name, header_value);
• response body.

An example:

from cocaine.decorators import http

import json

@http
def function(meta, request):
    return 404, [("Content-Type", "application/json")], json.dumps({"error": "not found"})

• @wsgi

Adapter for web-applications written using the WSGI framework.