Reverbrain wiki

Site Tools


thevoid:api

Table of Contents

The Void API

How to start

First implement server class which have to be successor of ioremap::thevoid::server:

class example_server : public server<example_server>
{
public:
	virtual bool initialize(const rapidjson::Value &config)
	{
		/* Handle config argument here */
 
		on<on_get>("/get");
		on<on_upload>("/upload");
	}

It has the only pure-virtual member initialize so you have to override it and handle all configuration options.

Second implement ioremap::thevoid::request_stream successors, it is created for every incoming request for specified handle. So on_get and on_upload objects in example are created for every “/get” and “/upload” request.

ioremap::thevoid::request_stream has pure virtual functions which are called on headers are finally received and on every data chunk received.

ioremap::thevoid::simple_request_stream is high-level successor of request_stream which has only one pure virtual function which is called once the request is fully received so it's recommended option.

	struct on_upload : public simple_request_stream<example_server>, std::enable_shared_from_this<on_upload>
	{
		void on_request(const swarm::network_request &req, const boost::asio::const_buffer &buffer)
		{
			const char *data = boost::asio::buffer_cast<const char *>(buffer);
			const size_t data_size = boost::asio::buffer_size(buffer);
 
			example_server &server = *get_server();
			elliptics::session session = server.get_session();
			session.write_data(...).connect(std::bind(..., shared_from_this(), ...);
		}
 
		void on_write_finished(const elliptics::sync_write_result &, const elliptics::error_info &error)
		{
			if (error)
				send_reply(swarm::network_reply::service_unavailable);
			else
				send_reply(swarm::network_reply::ok);
		}
	};

It's safe to call send_reply from another thread.

There are several methods to send data back to client:

  • send_headers - send HTTP headers to client.
  • send_data - send HTTP data to client. It usually must go right after headers.
  • close - close connection to client. Error should be set if connection is corrupted, i.e. if lost connection to Cocaine/Elliptics backend before all data are received.
  • send_reply is a shortcut for calling send_headers, send_data and close. In most cases it's a best option.

Lifetime

thevoid::reply_stream holds shared pointer to the thevoid::request_stream. This pointer is reseted as reply_stream::close method is called or any error occurs. If request_stream makes any asynchronous requests it's recommended to make it enable_shared_from_this successor, so it will be possible either be notified about the stream's death or provide it longer life.

reply_stream lives until connection to the client or request_stream are alive, so it's always safe to call any of it's methods, if error occurs (write error or any other) request_stream::on_close will be called and pointer will be reseted.

thevoid/api.txt · Last modified: 2013/11/21 17:21 by elessar