Crate cocaine

Roadmap:

• [x] Unicorn wrapper.
• [x] Send headers.
• [x] Notify about send events completion.
• [ ] Infinite buffer growing protection.
• [x] Implement local_addr and peer_addr for Service.
• [ ] Generic multiplexer over the socket type, allowing to work with both TCP and Unix sockets.
• [x] Receiving headers.
• [ ] HPACK encoder.
• [ ] HPACK decoder.

This framework provides a client-side API for the Cocaine Cloud platform.

There is a concept of services that represent universal cloud resource, which can be accessed using frameworks. These are: Locator, Storage, Unicorn, App and much more.

Examples

The following example demonstrates how to save a BLOB using Storage service.

use cocaine::{Core, Service};
use cocaine::service::Storage;

let mut core = Core::new().unwrap();
let storage = Storage::new(Service::new("storage", &core.handle()));

let future = storage.write("collection", "key", "le message".as_bytes(), &[]);

core.run(future).unwrap();

The framework is fully asynchronous, widely using tokio and futures for communicating with remote services. An example above represents a high-level API, but also does the data copy, which is unnecessary in some cases. However this can be completely avoided by using Dispatch trait in conjunction with Service object, because dispatch objects are called directly from the socket thread, where the data lays in completely zero-copy manner.

extern crate cocaine;
extern crate futures;

use std::mem;
use futures::sync::oneshot::{self, Sender};
use cocaine::{Core, Dispatch, Error, Response, Request, Service};
use cocaine::protocol::{Flatten, Primitive};

struct ReadDispatch {
    completion: Sender<()>,
}

impl Dispatch for ReadDispatch {
    fn process(self: Box<Self>, response: &Response) -> Option<Box<Dispatch>> {
        let data = response.deserialize::<Primitive<&str>>().flatten();

        println!("Data: {:?}", data);

        mem::drop(self.completion);
        None
    }
    fn discard(self: Box<Self>, err: &Error) {
        println!("Error: {}", err);
        mem::drop(self.completion);
    }
}

fn main() {
    let mut core = Core::new().unwrap();
    let service = Service::new("storage", &core.handle());
    let (tx, rx) = oneshot::channel();
    service.call(Request::new(0, &("collection", "key")).unwrap(), ReadDispatch { completion: tx });

    core.run(rx).unwrap();
}

Modules

There are both low-level API defined in the root module and more high-level API located in the service module.

Requirements

• Rust nightly, because it widely uses currently unstable impl Trait feature.

Reexports

pub use self::service::ServiceBuilder;

Modules

dispatch	Contains helper dispatches that ease working with common protocols, like Primitive or Streaming.
hpack	Header Compression for HTTP/2.
logging	Contains a logging service with helper macro to ease integration with the cloud logging system.
protocol	Contains protocol-specific helpers for deserialization and error handling.
service	This module contains various simplifications aimed to ease working with services: builders and façades.

Macros

cocaine_log

Logs a message using logger into the Logging Service.

Structs

Core	An event loop.
EventGraph	Describes a protocol graph for an event.
FixedResolver	A no-op resolver, that always returns preliminarily specified endpoints.
GraphNode	Describes a protocol graph node.
Request	A generic Cocaine request.
ResolveInfo	Response that is returned from either a resolver or Locator::resolve method.
Resolver	A Resolver that uses the Locator for name resolution.
Response	Generic response type.
Sender	An upstream for sending additional chunks into a channel.
Service	A low-level entry point to the Cocaine Cloud.

Enums

Error

An Error that can occur while working with Service.

Traits

Dispatch	Receiver part of every multiplexed non-mute request performed with a service.
Resolve	Cloud name resolution for services.