ebb 0.2.1 → 0.3.0

data/README

@@ -1,20 +1,11 @@
+(this is only for HEAD - old docs are found in the git repo)
+
 # A Web Server Called *Ebb*
 
 Ebb aims to be a small and fast web server specifically for hosting 
-dynamic web applications. It is not meant to be a full featured web server
-like Lighttpd, Apache, or Nginx. Rather it should be used in multiplicity
-behind a load balancer and a front-end server. It is not meant to serve static files in production.
-
-At one level Ebb is a minimalist C library that ties together the 
-[Mongrel state machine](http://mongrel.rubyforge.org/browser/tags/rel_1-0-1/ext/http11/http11_parser.rl) 
-and [libev](http://software.schmorp.de/pkg/libev.html) event loop. One can use
-this library to drive a web application written in C. (Perhaps for embedded 
-devices?) However, most people will be interested in the binding of this
-library to the Ruby programming language. The binding provides a
-[Rack](http://rack.rubyforge.org/) server interface that allows it to host
-Rails, Merb, or other frameworks.
+dynamic Ruby language web applications. 
 
-A Python-WSGI binding is under development.
+It is a binding to [libebb](http://tinyclouds.org/libebb)
 
 ## Install
 
@@ -22,37 +13,17 @@ The Ruby binding is available as a Ruby Gem. It can be install by executing
 
     gem install ebb
 
-Ebb depends on having glib2 headers and libraries installed. For example, in
-Macintosh if one is using Darwin ports then the following should do the trick
-  
-    port install glib2
-  
-Downloads are available at
-the [RubyForge project page](http://rubyforge.org/frs/?group_id=5640).
+If you want SSL support you must install GnuTLS.
+Ebb has no other dependencies.
 
 ## Running
 
-Using the executable `ebb_rails` one can start Ebb with a Rails project. Use
-`ebb_rails -h` to see all of the options but to start one can try
-
-    cd my_rails_project/
-    ebb_rails start
-
-When using `ebb_rails` from monit, the monitrc entry might look like this:
-
-    check process myApp4000
-      with pidfile /home/webuser/myApp/current/tmp/ebb.4000.pid
-      start program = "/usr/bin/ruby /usr/bin/ebb_rails start -d -e production -p 4000 -P /home/webuser/myApp/current/tmp/ebb.4000.pid -c /home/webuser/myApp/current" as uid webuser and gid webuser
-      stop program = "/usr/bin/ruby /usr/bin/ebb_rails stop -P /home/webuser/myApp/current/tmp/ebb.4000.pid" as uid webuser and gid webuser
-      if totalmem > 120.0 MB for 2 cycles then restart
-      if loadavg(5min) greater than 10 for 8 cycles then restart
-      group myApp
-
-To use Ebb with a different framework you will have to do a small amount of
-hacking at the moment! :)
+Use Ebb.start_server()
 
 ## Speed
 
+(these stats are out of date)
+
 Because Ebb handles most of the processing in C, it is able to do work
 often times more efficiently than other Ruby language web servers.
 
@@ -75,14 +46,9 @@ can be retrieved by executing
 
     git clone git://github.com/ry/ebb.git
 
-Here are some features that I would like to add:
-* HTTP 1.1 Expect/Continue (RFC 2616, sections 8.2.3 and 10.1.1)
-* A parser for multipart/form-data (only for optimization - this functionality is currently handled at the framework level)
-* Python binding
-
 ## (The MIT) License
 
-Copyright © 2008 [Ry Dahl](http://tinyclouds.org) (ry at tiny clouds dot org)
+Copyright (c) 2008 [Ryah Dahl](http://tinyclouds.org) (ry at tiny clouds dot org)
 
 <div id="license">
 Permission is hereby granted, free of charge, to any person obtaining

data/Rakefile

@@ -0,0 +1,123 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+require 'rake/clean'
+
+class String
+  def /(other)
+    File.join(self, other)
+  end
+end
+
+require 'lib/ebb/version'
+
+libev_dist = "http://dist.schmorp.de/libev/Attic"
+libev_release = "libev-3.43.tar.gz"
+libev_url = File.join(libev_dist, libev_release)
+
+LIBEBBFILES = ['ebb.c', 'ebb.h',
+               'ebb_request_parser.rl', 'ebb_request_parser.c', 'ebb_request_parser.h', 
+               'rbtree.c', 'rbtree.h']
+SRCEBBFILES = LIBEBBFILES.map { |f| "ext" / f }
+
+DISTFILES = FileList.new('libev/*.{c,h}', 'lib/**/*.rb', 'ext/*.{rb,rl,c,h}', 'README', 'Rakefile') + SRCEBBFILES
+CLEAN.add ["**/*.{o,bundle,so,obj,pdb,lib,def,exp}", "benchmark/*.dump", 'site/index.html']
+CLOBBER.add ['ext/Makefile', 'ext/mkmf.log'] + SRCEBBFILES
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList.new("test/*.rb")
+  t.verbose = true
+end
+
+LIBEBBFILES.each do |f|
+  file(".libebb"/f => ".libebb") 
+  file("ext"/f => ".libebb"/f) do |t|
+    sh "cp .libebb/#{f} ext/#{f}"
+  end
+end
+
+task(:default => [:compile])
+
+task(:compile => ['ext/Makefile','libev'] + SRCEBBFILES) do
+  sh "cd ext && make"
+end
+
+file "libev" do
+  puts "downloading libev"
+  sh "wget #{libev_url}" do |ok, res|
+    if ! ok
+      puts "Couldn't download libev. Please put #{libev_url} in here and try again"
+      exit 1
+    end
+  end
+  sh "tar -zxf #{libev_release}"
+  sh "mv #{libev_release.sub('.tar.gz', '')} libev"
+end
+
+file ".libebb" do
+  sh "git clone git://github.com/ry/libebb.git .libebb"
+end
+
+file('ext/Makefile' => 'ext/extconf.rb') do
+  sh "cd ext && ruby extconf.rb"
+end
+
+file(".libebb/ebb_request_parser.c" => '.libebb/ebb_request_parser.rl') do
+  sh 'ragel -s -G2 .libebb/ebb_request_parser.rl'
+end
+
+task(:test => DISTFILES)
+Rake::TestTask.new do |t|
+  t.test_files = 'test/basic_test.rb'
+  t.verbose = true
+end
+
+task(:site_upload => :site) do
+  sh 'scp -r site/* rydahl@rubyforge.org:/var/www/gforge-projects/ebb/'
+end
+task(:site => 'site/index.html')
+file('site/index.html' => %w{README site/style.css}) do
+  require 'rubygems'
+  require 'bluecloth'
+  doc = BlueCloth.new(File.read('README'))
+  template = <<-HEREDOC
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <title>Ebb</title>
+    <link rel="alternate" href="http://max.kanat.us/tag-syndicate/?user=four&tag=ebb" title="RSS Feed" type="application/rss+xml" />
+    <link type="text/css" rel="stylesheet" href="style.css" media="screen"/>
+  </head>
+  <body>  
+    <div id="content">CONTENT</div>
+  </body>
+</html>
+HEREDOC
+  
+  File.open('site/index.html', "w+") do |f|
+    f.write template.sub('CONTENT', doc.to_html)
+  end
+end
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.summary = "A Web Server"
+  s.description = ''
+  s.name = 'ebb'
+  s.author = 'ry dahl'
+  s.email = 'ry at tiny clouds dot org'
+  s.homepage = 'http://ebb.rubyforge.org'
+  s.version = Ebb::VERSION
+  s.rubyforge_project = 'ebb'
+  
+  s.required_ruby_version = '>= 1.8.4'
+  
+  s.require_path = 'lib'
+  s.extensions = 'ext/extconf.rb'
+  
+  s.files = DISTFILES
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+end

data/ext/ebb.c

@@ -0,0 +1,794 @@
+/* libebb web server library
+ * Copyright 2008 ryah dahl, ry at tiny clouds punkt org
+ *
+ * This software may be distributed under the "MIT" license included in the
+ * README
+ */
+
+#include <assert.h>
+#include <string.h>
+#include <fcntl.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <netinet/tcp.h> /* TCP_NODELAY */
+#include <netinet/in.h>  /* inet_ntoa */
+#include <arpa/inet.h>   /* inet_ntoa */
+#include <unistd.h>
+#include <stdio.h>      /* perror */
+#include <errno.h>      /* perror */
+#include <stdlib.h> /* for the default methods */
+#include <ev.h>
+
+#include "ebb.h"
+#include "ebb_request_parser.h"
+#ifdef HAVE_GNUTLS
+# include <gnutls/gnutls.h>
+# include "rbtree.h" /* for session_cache */
+#endif
+
+#ifndef TRUE
+# define TRUE 1
+#endif
+#ifndef FALSE
+# define FALSE 0
+#endif 
+#ifndef MIN
+# define MIN(a,b) (a < b ? a : b)
+#endif
+
+#define error(FORMAT, ...) fprintf(stderr, "error: " FORMAT "\n", ##__VA_ARGS__)
+
+#define CONNECTION_HAS_SOMETHING_TO_WRITE (connection->to_write != NULL)
+
+static void 
+set_nonblock (int fd)
+{
+  int flags = fcntl(fd, F_GETFL, 0);
+  int r = fcntl(fd, F_SETFL, flags | O_NONBLOCK);
+  assert(0 <= r && "Setting socket non-block failed!");
+}
+
+static ssize_t 
+nosigpipe_push(void *data, const void *buf, size_t len)
+{
+  int fd = (int)data;
+  int flags = 0;
+#ifdef MSG_NOSIGNAL
+  flags = MSG_NOSIGNAL;
+#endif
+  return send(fd, buf, len, flags);
+}
+
+static void 
+close_connection(ebb_connection *connection)
+{
+#ifdef HAVE_GNUTLS
+  if(connection->server->secure)
+    ev_io_stop(connection->server->loop, &connection->handshake_watcher);
+#endif
+  ev_io_stop(connection->server->loop, &connection->read_watcher);
+  ev_io_stop(connection->server->loop, &connection->write_watcher);
+  ev_timer_stop(connection->server->loop, &connection->timeout_watcher);
+
+  if(0 > close(connection->fd))
+    error("problem closing connection fd");
+
+  connection->open = FALSE;
+
+  if(connection->on_close)
+    connection->on_close(connection);
+  /* No access to the connection past this point! 
+   * The user is allowed to free in the callback
+   */
+}
+
+#ifdef HAVE_GNUTLS
+#define GNUTLS_NEED_WRITE (gnutls_record_get_direction(connection->session) == 1)
+#define GNUTLS_NEED_READ (gnutls_record_get_direction(connection->session) == 0)
+
+#define EBB_MAX_SESSION_KEY 32
+#define EBB_MAX_SESSION_VALUE 512
+
+struct session_cache {
+  struct rbtree_node_t node;
+
+  gnutls_datum_t key;
+  gnutls_datum_t value;
+
+  char key_storage[EBB_MAX_SESSION_KEY];
+  char value_storage[EBB_MAX_SESSION_VALUE];
+};
+
+static int 
+session_cache_compare (void *left, void *right) 
+{
+  gnutls_datum_t *left_key = left;
+  gnutls_datum_t *right_key = right;
+  if(left_key->size < right_key->size)
+    return -1;
+  else if(left_key->size > right_key->size)
+    return 1;
+  else
+    return memcmp( left_key->data
+                 , right_key->data
+                 , MIN(left_key->size, right_key->size)
+                 );
+}
+
+static int
+session_cache_store(void *data, gnutls_datum_t key, gnutls_datum_t value)
+{
+  rbtree tree = data;
+
+  if( tree == NULL
+   || key.size > EBB_MAX_SESSION_KEY
+   || value.size > EBB_MAX_SESSION_VALUE
+    ) return -1;
+
+  struct session_cache *cache = gnutls_malloc(sizeof(struct session_cache));
+
+  memcpy (cache->key_storage, key.data, key.size);
+  cache->key.size = key.size;
+  cache->key.data = (void*)cache->key_storage;
+
+  memcpy (cache->value_storage, value.data, value.size);
+  cache->value.size = value.size;
+  cache->value.data = (void*)cache->value_storage;
+
+  cache->node.key = &cache->key;
+  cache->node.value = &cache;
+
+  rbtree_insert(tree, (rbtree_node)cache);
+
+  //printf("session_cache_store\n");
+
+  return 0;
+}
+
+static gnutls_datum_t
+session_cache_retrieve (void *data, gnutls_datum_t key)
+{
+  rbtree tree = data;
+  gnutls_datum_t res = { NULL, 0 };
+  struct session_cache *cache = rbtree_lookup(tree, &key);
+
+  if(cache == NULL)
+    return res;
+
+  res.size = cache->value.size;
+  res.data = gnutls_malloc (res.size);
+  if(res.data == NULL)
+    return res;
+
+  memcpy(res.data, cache->value.data, res.size);
+
+  //printf("session_cache_retrieve\n");
+
+  return res;
+}
+
+static int
+session_cache_remove (void *data, gnutls_datum_t key)
+{
+  rbtree tree = data;
+
+  if(tree == NULL)
+    return -1;
+
+  struct session_cache *cache = (struct session_cache *)rbtree_delete(tree, &key);
+  if(cache == NULL)
+    return -1;
+
+  gnutls_free(cache);
+
+  //printf("session_cache_remove\n");
+
+  return 0;
+}
+
+static void 
+on_handshake(struct ev_loop *loop ,ev_io *watcher, int revents)
+{
+  ebb_connection *connection = watcher->data;
+
+  //printf("on_handshake\n");
+
+  assert(ev_is_active(&connection->timeout_watcher));
+  assert(!ev_is_active(&connection->read_watcher));
+  assert(!ev_is_active(&connection->write_watcher));
+
+  if(EV_ERROR & revents) {
+    error("on_handshake() got error event, closing connection.n");
+    goto error;
+  }
+
+  int r = gnutls_handshake(connection->session);
+  if(r < 0) {
+    if(gnutls_error_is_fatal(r)) goto error;
+    if(r == GNUTLS_E_INTERRUPTED || r == GNUTLS_E_AGAIN)
+      ev_io_set( watcher
+               , connection->fd
+               , EV_ERROR | (GNUTLS_NEED_WRITE ? EV_WRITE : EV_READ)
+               );
+    return;
+  }
+
+  ebb_connection_reset_timeout(connection);
+  ev_io_stop(loop, watcher);
+
+  ev_io_start(loop, &connection->read_watcher);
+  if(CONNECTION_HAS_SOMETHING_TO_WRITE)
+    ev_io_start(loop, &connection->write_watcher);
+
+  return;
+error:
+  close_connection(connection);
+}
+
+#endif /* HAVE_GNUTLS */
+
+
+/* Internal callback 
+ * called by connection->timeout_watcher
+ */
+static void 
+on_timeout(struct ev_loop *loop, ev_timer *watcher, int revents)
+{
+  ebb_connection *connection = watcher->data;
+
+  assert(watcher == &connection->timeout_watcher);
+
+  //printf("on_timeout\n");
+
+  /* if on_timeout returns true, we don't time out */
+  if(connection->on_timeout) {
+    int r = connection->on_timeout(connection);
+
+    if(r == EBB_AGAIN) {
+      ebb_connection_reset_timeout(connection);
+      return;
+    }
+  }
+
+  ebb_connection_schedule_close(connection);
+}
+
+/* Internal callback 
+ * called by connection->read_watcher
+ */
+static void 
+on_readable(struct ev_loop *loop, ev_io *watcher, int revents)
+{
+  ebb_connection *connection = watcher->data;
+  char base[TCP_MAXWIN];
+  char *recv_buffer = base;
+  size_t recv_buffer_size = TCP_MAXWIN;
+  ssize_t recved;
+
+  //printf("on_readable\n");
+
+  // TODO -- why is this broken?
+  //assert(ev_is_active(&connection->timeout_watcher));
+  assert(watcher == &connection->read_watcher);
+
+  if(EV_ERROR & revents) {
+    error("on_readable() got error event, closing connection.");
+    goto error;
+  }
+
+  ebb_buf *buf = NULL;
+  if(connection->new_buf) {
+    buf = connection->new_buf(connection);
+    if(buf == NULL) return; 
+    recv_buffer = buf->base;
+    recv_buffer_size = buf->len;
+  }
+
+#ifdef HAVE_GNUTLS
+  assert(!ev_is_active(&connection->handshake_watcher));
+
+  if(connection->server->secure) {
+    recved = gnutls_record_recv( connection->session
+                               , recv_buffer
+                               , recv_buffer_size
+                               );
+    if(recved <= 0) {
+      if(gnutls_error_is_fatal(recved)) goto error;
+      if( (recved == GNUTLS_E_INTERRUPTED || recved == GNUTLS_E_AGAIN)
+       && GNUTLS_NEED_WRITE
+        ) ev_io_start(loop, &connection->write_watcher);
+      return; 
+    } 
+  } else {
+#endif /* HAVE_GNUTLS */
+
+    recved = recv(connection->fd, recv_buffer, recv_buffer_size, 0);
+    if(recved < 0) goto error;
+    if(recved == 0) return;
+
+#ifdef HAVE_GNUTLS
+  }
+#endif /* HAVE_GNUTLS */
+
+  ebb_connection_reset_timeout(connection);
+
+  ebb_request_parser_execute(&connection->parser, recv_buffer, recved);
+
+  /* parse error? just drop the client. screw the 400 response */
+  if(ebb_request_parser_has_error(&connection->parser)) goto error;
+
+  if(buf && buf->on_release)
+    buf->on_release(buf);
+
+  return;
+error:
+  ebb_connection_schedule_close(connection);
+}
+
+/* Internal callback 
+ * called by connection->write_watcher
+ */
+static void 
+on_writable(struct ev_loop *loop, ev_io *watcher, int revents)
+{
+  ebb_connection *connection = watcher->data;
+  ssize_t sent;
+  
+  //printf("on_writable\n");
+
+  assert(CONNECTION_HAS_SOMETHING_TO_WRITE);
+  assert(connection->written <= connection->to_write_len);
+  // TODO -- why is this broken?
+  //assert(ev_is_active(&connection->timeout_watcher));
+  assert(watcher == &connection->write_watcher);
+
+#ifdef HAVE_GNUTLS
+  assert(!ev_is_active(&connection->handshake_watcher));
+
+  if(connection->server->secure) {
+    sent = gnutls_record_send( connection->session
+                             , connection->to_write + connection->written
+                             , connection->to_write_len - connection->written
+                             ); 
+    if(sent <= 0) {
+      if(gnutls_error_is_fatal(sent)) goto error;
+      if( (sent == GNUTLS_E_INTERRUPTED || sent == GNUTLS_E_AGAIN)
+       && GNUTLS_NEED_READ
+        ) ev_io_stop(loop, watcher);
+      return; 
+    }
+  } else {
+#endif /* HAVE_GNUTLS */
+
+    sent = nosigpipe_push( (void*)connection->fd
+                         , connection->to_write + connection->written
+                         , connection->to_write_len - connection->written
+                         );
+    if(sent < 0) goto error;
+    if(sent == 0) return;
+
+#ifdef HAVE_GNUTLS
+  }
+#endif /* HAVE_GNUTLS */
+
+  ebb_connection_reset_timeout(connection);
+
+  connection->written += sent;
+
+  if(connection->written == connection->to_write_len) {
+    ev_io_stop(loop, watcher);
+    connection->to_write = NULL;
+
+    if(connection->after_write_cb)
+      connection->after_write_cb(connection);
+  }
+  return;
+error:
+  error("close connection on write.");
+  ebb_connection_schedule_close(connection);
+}
+
+#ifdef HAVE_GNUTLS
+
+static void 
+on_goodbye_tls(struct ev_loop *loop, ev_io *watcher, int revents)
+{
+  ebb_connection *connection = watcher->data;
+  assert(watcher == &connection->goodbye_tls_watcher);
+
+  if(EV_ERROR & revents) {
+    error("on_goodbye() got error event, closing connection.");
+    goto die;
+  }
+
+  int r = gnutls_bye(connection->session, GNUTLS_SHUT_RDWR);
+  if(r < 0) {
+    if(gnutls_error_is_fatal(r)) goto die;
+    if(r == GNUTLS_E_INTERRUPTED || r == GNUTLS_E_AGAIN)
+      ev_io_set( watcher
+               , connection->fd
+               , EV_ERROR | (GNUTLS_NEED_WRITE ? EV_WRITE : EV_READ)
+               );
+    return;
+  }
+
+die:
+  ev_io_stop(loop, watcher);
+  if(connection->session) 
+    gnutls_deinit(connection->session);
+  close_connection(connection);
+}
+#endif /* HAVE_GNUTLS*/
+
+static void 
+on_goodbye(struct ev_loop *loop, ev_timer *watcher, int revents)
+{
+  ebb_connection *connection = watcher->data;
+  assert(watcher == &connection->goodbye_watcher);
+
+  close_connection(connection);
+}
+
+
+static ebb_request* 
+new_request_wrapper(void *data)
+{
+  ebb_connection *connection = data;
+  if(connection->new_request)
+    return connection->new_request(connection);
+  return NULL;
+}
+
+/* Internal callback 
+ * Called by server->connection_watcher.
+ */
+static void 
+on_connection(struct ev_loop *loop, ev_io *watcher, int revents)
+{
+  ebb_server *server = watcher->data;
+
+  //printf("on connection!\n");
+
+  assert(server->listening);
+  assert(server->loop == loop);
+  assert(&server->connection_watcher == watcher);
+  
+  if(EV_ERROR & revents) {
+    error("on_connection() got error event, closing server.");
+    ebb_server_unlisten(server);
+    return;
+  }
+
+  
+  struct sockaddr_in addr; // connector's address information
+  socklen_t addr_len = sizeof(addr); 
+  int fd = accept( server->fd
+                 , (struct sockaddr*) & addr
+                 , & addr_len
+                 );
+  if(fd < 0) {
+    perror("accept()");
+    return;
+  }
+
+  ebb_connection *connection = NULL;
+  if(server->new_connection)
+    connection = server->new_connection(server, &addr);
+  if(connection == NULL) {
+    close(fd);
+    return;
+  } 
+  
+  set_nonblock(fd);
+  connection->fd = fd;
+  connection->open = TRUE;
+  connection->server = server;
+  memcpy(&connection->sockaddr, &addr, addr_len);
+  if(server->port[0] != '\0')
+    connection->ip = inet_ntoa(connection->sockaddr.sin_addr);  
+
+#ifdef SO_NOSIGPIPE
+  int arg = 1;
+  setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &arg, sizeof(int));
+#endif
+
+#ifdef HAVE_GNUTLS
+  if(server->secure) {
+    gnutls_init(&connection->session, GNUTLS_SERVER);
+    gnutls_transport_set_lowat(connection->session, 0); 
+    gnutls_set_default_priority(connection->session);
+    gnutls_credentials_set(connection->session, GNUTLS_CRD_CERTIFICATE, connection->server->credentials);
+
+    gnutls_transport_set_ptr(connection->session, (gnutls_transport_ptr) fd); 
+    gnutls_transport_set_push_function(connection->session, nosigpipe_push);
+
+    gnutls_db_set_ptr (connection->session, &server->session_cache);
+    gnutls_db_set_store_function (connection->session, session_cache_store);
+    gnutls_db_set_retrieve_function (connection->session, session_cache_retrieve);
+    gnutls_db_set_remove_function (connection->session, session_cache_remove);
+  }
+
+  ev_io_set(&connection->handshake_watcher, connection->fd, EV_READ | EV_WRITE | EV_ERROR);
+#endif /* HAVE_GNUTLS */
+
+  /* Note: not starting the write watcher until there is data to be written */
+  ev_io_set(&connection->write_watcher, connection->fd, EV_WRITE);
+  ev_io_set(&connection->read_watcher, connection->fd, EV_READ | EV_ERROR);
+  /* XXX: seperate error watcher? */
+
+  ev_timer_start(loop, &connection->timeout_watcher);
+
+#ifdef HAVE_GNUTLS
+  if(server->secure) {
+    ev_io_start(loop, &connection->handshake_watcher);
+    return;
+  }
+#endif
+
+  ev_io_start(loop, &connection->read_watcher);
+}
+
+/**
+ * Begin the server listening on a file descriptor.  This DOES NOT start the
+ * event loop.  Start the event loop after making this call.
+ */
+int 
+ebb_server_listen_on_fd(ebb_server *server, const int fd)
+{
+  assert(server->listening == FALSE);
+
+  if (listen(fd, EBB_MAX_CONNECTIONS) < 0) {
+    perror("listen()");
+    return -1;
+  }
+  
+  set_nonblock(fd); /* XXX superfluous? */
+  
+  server->fd = fd;
+  server->listening = TRUE;
+  
+  ev_io_set (&server->connection_watcher, server->fd, EV_READ | EV_ERROR);
+  ev_io_start (server->loop, &server->connection_watcher);
+  
+  return server->fd;
+}
+
+
+/**
+ * Begin the server listening on a file descriptor This DOES NOT start the
+ * event loop. Start the event loop after making this call.
+ */
+int 
+ebb_server_listen_on_port(ebb_server *server, const int port)
+{
+  int fd = -1;
+  struct linger ling = {0, 0};
+  struct sockaddr_in addr;
+  int flags = 1;
+  
+  if ((fd = socket(AF_INET, SOCK_STREAM, 0)) == -1) {
+    perror("socket()");
+    goto error;
+  }
+  
+  flags = 1;
+  setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, (void *)&flags, sizeof(flags));
+  setsockopt(fd, SOL_SOCKET, SO_KEEPALIVE, (void *)&flags, sizeof(flags));
+  setsockopt(fd, SOL_SOCKET, SO_LINGER, (void *)&ling, sizeof(ling));
+
+  /* XXX: Sending single byte chunks in a response body? Perhaps there is a
+   * need to enable the Nagel algorithm dynamically. For now disabling.
+   */
+  setsockopt(fd, IPPROTO_TCP, TCP_NODELAY, (void *)&flags, sizeof(flags));
+  
+  /* the memset call clears nonstandard fields in some impementations that
+   * otherwise mess things up.
+   */
+  memset(&addr, 0, sizeof(addr));
+  
+  addr.sin_family = AF_INET;
+  addr.sin_port = htons(port);
+  addr.sin_addr.s_addr = htonl(INADDR_ANY);
+  
+  if (bind(fd, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
+    perror("bind()");
+    goto error;
+  }
+  
+  int ret = ebb_server_listen_on_fd(server, fd);
+  if (ret >= 0) {
+    sprintf(server->port, "%d", port);
+  }
+  return ret;
+error:
+  if(fd > 0) close(fd);
+  return -1;
+}
+
+/**
+ * Stops the server. Will not accept new connections.  Does not drop
+ * existing connections.
+ */
+void 
+ebb_server_unlisten(ebb_server *server)
+{
+  if(server->listening) {
+    ev_io_stop(server->loop, &server->connection_watcher);
+    close(server->fd);
+    server->port[0] = '\0';
+    server->listening = FALSE;
+  }
+}
+
+/**
+ * Initialize an ebb_server structure.  After calling ebb_server_init set
+ * the callback server->new_connection and, optionally, callback data
+ * server->data.  The new connection MUST be initialized with
+ * ebb_connection_init before returning it to the server.
+ *
+ * @param server the server to initialize
+ * @param loop a libev loop
+ */
+void 
+ebb_server_init(ebb_server *server, struct ev_loop *loop)
+{
+  server->loop = loop;
+  server->listening = FALSE;
+  server->port[0] = '\0';
+  server->fd = -1;
+  server->connection_watcher.data = server;
+  ev_init (&server->connection_watcher, on_connection);
+  server->secure = FALSE;
+
+#ifdef HAVE_GNUTLS
+  rbtree_init(&server->session_cache, session_cache_compare);
+  server->credentials = NULL;
+#endif
+
+  server->new_connection = NULL;
+  server->data = NULL;
+}
+
+
+#ifdef HAVE_GNUTLS
+/* similar to server_init. 
+ *
+ * the user of secure server might want to set additional callbacks from
+ * GNUTLS. In particular 
+ * gnutls_global_set_mem_functions() 
+ * gnutls_global_set_log_function()
+ * Also see the note above ebb_connection_init() about setting gnutls cache
+ * access functions
+ *
+ * cert_file: the filename of a PEM certificate file
+ *
+ * key_file: the filename of a private key. Currently only PKCS-1 encoded
+ * RSA and DSA private keys are accepted. 
+ */
+int 
+ebb_server_set_secure (ebb_server *server, const char *cert_file, const char *key_file)
+{
+  server->secure = TRUE;
+  gnutls_global_init();
+  gnutls_certificate_allocate_credentials(&server->credentials);
+  /* todo gnutls_certificate_free_credentials */
+  int r = gnutls_certificate_set_x509_key_file( server->credentials
+                                              , cert_file
+                                              , key_file
+                                              , GNUTLS_X509_FMT_PEM
+                                              );
+  if(r < 0) {
+    error("loading certificates");
+    return -1;
+  }
+  return 1;
+}
+#endif /* HAVE_GNUTLS */
+
+/**
+ * Initialize an ebb_connection structure. After calling this function you
+ * must setup callbacks for the different actions the server can take. See
+ * server.h for which callbacks are availible. 
+ * 
+ * This should be called immediately after allocating space for a new
+ * ebb_connection structure. Most likely, this will only be called within
+ * the ebb_server->new_connection callback which you supply. 
+ *
+ * If using SSL do consider setting
+ *   gnutls_db_set_retrieve_function (connection->session, _);
+ *   gnutls_db_set_remove_function (connection->session, _);
+ *   gnutls_db_set_store_function (connection->session, _);
+ *   gnutls_db_set_ptr (connection->session, _);
+ * To provide a better means of storing SSL session caches. libebb provides
+ * only a simple default implementation. 
+ *
+ * @param connection the connection to initialize
+ * @param timeout    the timeout in seconds
+ */
+void 
+ebb_connection_init(ebb_connection *connection)
+{
+  connection->fd = -1;
+  connection->server = NULL;
+  connection->ip = NULL;
+  connection->open = FALSE;
+
+  ebb_request_parser_init( &connection->parser );
+  connection->parser.data = connection;
+  connection->parser.new_request = new_request_wrapper;
+  
+  ev_init (&connection->write_watcher, on_writable);
+  connection->write_watcher.data = connection;
+  connection->to_write = NULL;
+
+  ev_init(&connection->read_watcher, on_readable);
+  connection->read_watcher.data = connection;
+
+#ifdef HAVE_GNUTLS
+  connection->handshake_watcher.data = connection;
+  ev_init(&connection->handshake_watcher, on_handshake);
+
+  ev_init(&connection->goodbye_tls_watcher, on_goodbye_tls);
+  connection->goodbye_tls_watcher.data = connection;
+
+  connection->session = NULL;
+#endif /* HAVE_GNUTLS */
+
+  ev_timer_init(&connection->goodbye_watcher, on_goodbye, 0., 0.);
+  connection->goodbye_watcher.data = connection;  
+
+  ev_timer_init(&connection->timeout_watcher, on_timeout, EBB_DEFAULT_TIMEOUT, 0.);
+  connection->timeout_watcher.data = connection;  
+
+  connection->new_buf = NULL;
+  connection->new_request = NULL;
+  connection->on_timeout = NULL;
+  connection->on_close = NULL;
+  connection->data = NULL;
+}
+
+void 
+ebb_connection_schedule_close (ebb_connection *connection)
+{
+#ifdef HAVE_GNUTLS
+  if(connection->server->secure) {
+    ev_io_set(&connection->goodbye_tls_watcher, connection->fd, EV_ERROR | EV_READ | EV_WRITE);
+    ev_io_start(connection->server->loop, &connection->goodbye_tls_watcher);
+    return;
+  }
+#endif
+  ev_timer_start(connection->server->loop, &connection->goodbye_watcher);
+}
+
+/* 
+ * Resets the timeout to stay alive for another connection->timeout seconds
+ */
+void 
+ebb_connection_reset_timeout(ebb_connection *connection)
+{
+  ev_timer_again(connection->server->loop, &connection->timeout_watcher);
+}
+
+/**
+ * Writes a string to the socket. This is actually sets a watcher
+ * which may take multiple iterations to write the entire string.
+ *
+ * The buf->on_release() callback will be made when the operation is complete.
+ *
+ * This can only be called once at a time. If you call it again
+ * while the connection is writing another buffer the ebb_connection_write
+ * will return FALSE and ignore the request.
+ */
+int 
+ebb_connection_write (ebb_connection *connection, const char *buf, size_t len, ebb_after_write_cb cb)
+{
+  if(ev_is_active(&connection->write_watcher))
+    return FALSE;
+  assert(!CONNECTION_HAS_SOMETHING_TO_WRITE);
+  connection->to_write = buf;
+  connection->to_write_len = len;
+  connection->written = 0;
+  connection->after_write_cb = cb;
+  ev_io_start(connection->server->loop, &connection->write_watcher);
+  return TRUE;
+}