warden-protocol 0.1.3

data/lib/warden/protocol/pb/link.proto

@@ -0,0 +1,40 @@
+// Link to a job.
+//
+// A request blocks until the job completes.
+// A job is removed after it has completed and has been linked to.
+//
+// > **TODO** Talk about nomenclature (what is a job).
+//
+// ### Request
+//
+// * `handle`: Container handle.
+// * `job_id`: Job ID.
+//
+// ### Response
+//
+// * `exit_status`: Exit status of the job.
+// * `stdout`: Standard out produced by the job.
+// * `stderr`: Standard error produced by the job.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+// * When `job_id` does not refer to a job.
+//
+// ### Definition
+//
+
+package warden;
+
+message LinkRequest {
+  required string handle = 1;
+
+  required uint32 job_id = 2;
+}
+
+message LinkResponse {
+  optional uint32 exit_status = 1;
+  optional string stdout = 2;
+  optional string stderr = 3;
+  optional InfoResponse info = 4;
+}

data/lib/warden/protocol/pb/list.proto

@@ -0,0 +1,25 @@
+// Lists all containers.
+//
+// ### Request
+//
+// Empty.
+//
+// ### Response
+//
+// * `handles`: List of container handles.
+//
+// ### Errors
+//
+// None.
+//
+// ### Definition
+//
+
+package warden;
+
+message ListRequest {
+}
+
+message ListResponse {
+  repeated string handles = 1;
+}

data/lib/warden/protocol/pb/message.proto

@@ -0,0 +1,36 @@
+// nodoc
+
+package warden;
+
+message Message {
+  enum Type {
+    Error = 1;
+
+    Create  = 11;
+    Stop    = 12;
+    Destroy = 13;
+    Info    = 14;
+
+    Spawn  = 21;
+    Link   = 22;
+    Run    = 23;
+    Stream = 24;
+
+    NetIn  = 31;
+    NetOut = 32;
+
+    CopyIn  = 41;
+    CopyOut = 42;
+
+    LimitMemory    = 51;
+    LimitDisk      = 52;
+    LimitBandwidth = 53;
+
+    Ping = 91;
+    List = 92;
+    Echo = 93;
+  }
+
+  required Type type = 1;
+  required bytes payload = 2;
+}

data/lib/warden/protocol/pb/net_in.proto

@@ -0,0 +1,39 @@
+// Set up a port mapping on the host to forward traffic to a specific port to a container.
+//
+// > **TODO** Link to page explaining how networking works.
+//
+// ### Request
+//
+// * `handle`: Container handle.
+// * `host_port`: External port to be mapped.
+//    If not specified, a port will be acquired from the server's port pool.
+//    If specified, the user is expected to manage port availability.
+// * `container_port`: Port on the container's interface that traffic should be forwarded to.
+//    If not specified, the port will be the same as `host_port`, whether it is specified or not.
+//
+// ### Response
+//
+// * `host_port`: External port that was mapped.
+// * `container_port`: Port on the container's interface that traffic will be forwarded to.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+// * When no port can be acquired from the server's port pool.
+//
+// ### Definition
+//
+
+package warden;
+
+message NetInRequest {
+  required string handle = 1;
+
+  optional uint32 host_port      = 3;
+  optional uint32 container_port = 2;
+}
+
+message NetInResponse {
+  required uint32 host_port      = 1;
+  required uint32 container_port = 2;
+}

data/lib/warden/protocol/pb/net_out.proto

@@ -0,0 +1,35 @@
+// Whitelist network traffic.
+//
+// If the configuration directive `deny_networks` is not used,
+// all networks are already whitelisted and this command is effectively a no-op.
+//
+// > **TODO** Link to page explaining how networking works.
+//
+// ### Request
+//
+// * `handle`: Container handle.
+// * `network`: Network to whitelist (in the form `1.2.3.4/8`).
+// * `port`: Port to whitelist.
+//
+// ### Response
+//
+// Empty.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+//
+// ### Definition
+//
+
+package warden;
+
+message NetOutRequest {
+  required string handle = 1;
+
+  optional string network = 2;
+  optional uint32 port    = 3;
+}
+
+message NetOutResponse {
+}

data/lib/warden/protocol/pb/ping.proto

@@ -0,0 +1,24 @@
+// Pings.
+//
+// ### Request
+//
+// Empty.
+//
+// ### Response
+//
+// Empty.
+//
+// ### Errors
+//
+// None.
+//
+// ### Definition
+//
+
+package warden;
+
+message PingRequest {
+}
+
+message PingResponse {
+}

data/lib/warden/protocol/pb/resource_limits.proto

@@ -0,0 +1,30 @@
+// This structure is neither a request nor a response.
+//
+// It is a structure that is shared between `Spawn` and `Run` requests.
+//
+// Please refer to the manual page of [`getrlimit(2)`][getrlimit] for a description of the individual fields.
+//
+// [getrlimit]: http://www.kernel.org/doc/man-pages/online/pages/man2/getrlimit.2.html
+//
+// ### Definition
+//
+
+package warden;
+
+message ResourceLimits {
+  optional uint64 as         =  1;
+  optional uint64 core       =  2;
+  optional uint64 cpu        =  3;
+  optional uint64 data       =  4;
+  optional uint64 fsize      =  5;
+  optional uint64 locks      =  6;
+  optional uint64 memlock    =  7;
+  optional uint64 msgqueue   =  8;
+  optional uint64 nice       =  9;
+  optional uint64 nofile     = 10;
+  optional uint64 nproc      = 11;
+  optional uint64 rss        = 12;
+  optional uint64 rtprio     = 13;
+  optional uint64 sigpending = 14;
+  optional uint64 stack      = 15;
+}

data/lib/warden/protocol/pb/run.proto

@@ -0,0 +1,29 @@
+// Run a job inside a container.
+//
+// This request is equivalent to spawning a job and immediately linking to it.
+//
+// See `Spawn` and `Link` for a description of the request and response.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+//
+// ### Definition
+//
+
+package warden;
+
+message RunRequest {
+  required string handle = 1;
+
+  required string script = 2;
+  optional bool privileged = 3 [default = false];
+  optional ResourceLimits rlimits = 4;
+}
+
+message RunResponse {
+  optional uint32 exit_status = 1;
+  optional string stdout = 2;
+  optional string stderr = 3;
+  optional InfoResponse info = 4;
+}

data/lib/warden/protocol/pb/spawn.proto

@@ -0,0 +1,37 @@
+// Spawn a job inside a container.
+//
+// > **TODO** Talk about nomenclature (what is a job).
+//
+// ### Request
+//
+// The specified script is interpreted by `/bin/bash` inside the container.
+//
+// * `handle`: Container handle.
+// * `script`: Script to execute.
+// * `privileged`: Whether to run the script as root or not.
+// * `rlimits`: Resource limits (see `ResourceLimits`).
+//
+// ### Response
+//
+// * `job_id`: Job ID.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+//
+// ### Definition
+//
+
+package warden;
+
+message SpawnRequest {
+  required string handle = 1;
+
+  required string script = 2;
+  optional bool privileged = 3 [default = false];
+  optional ResourceLimits rlimits = 4;
+}
+
+message SpawnResponse {
+  required uint32 job_id = 1;
+}

data/lib/warden/protocol/pb/stop.proto

@@ -0,0 +1,40 @@
+// Stops a container.
+//
+// Once a container is stopped, warden does not allow spawning new processes inside the container.
+// It is possible to copy files in to and out of a stopped container.
+// It is only when a container is destroyed that its filesystem is cleaned up.
+//
+// ### Request
+//
+// Warden stops a container by sending the processes running inside it the `SIGTERM` signal.
+// It then waits for the processes to terminate before returning a response.
+// If one or more processes do not terminate within 10 seconds,
+// the warden server sends these processes the `SIGKILL` signal,
+// killing them ungracefully.
+//
+// * `handle`: Container handle.
+// * `background`: Return a response immediately instead of waiting for the container to be stopped.
+// * `kill`: Send SIGKILL instead of SIGTERM.
+//
+// ### Response
+//
+// Empty.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+//
+// ### Definition
+//
+
+package warden;
+
+message StopRequest {
+  required string handle = 1;
+
+  optional bool background = 10 [default = false];
+  optional bool kill       = 20 [default = false];
+}
+
+message StopResponse {
+}

data/lib/warden/protocol/pb/stream.proto

@@ -0,0 +1,41 @@
+// Stream a job.
+//
+// A stream request is followed by one or more stream responses.
+//
+// A job is removed after it has completed and the terminating stream response was sent.
+//
+// > **TODO** Talk about nomenclature (what is a job).
+//
+// ### Request
+//
+// * `handle`: Container handle.
+// * `job_id`: Job ID.
+//
+// ### Response
+//
+// * `name`: Name of stream (either `stdout` or `stderr`).
+// * `data`: A chunk of data from the stream specified in `name`.
+// * `exit_status`: Exit status of the job. If set, this is the terminating response for the request.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+// * When `job_id` does not refer to a job.
+//
+// ### Definition
+//
+
+package warden;
+
+message StreamRequest {
+  required string handle = 1;
+
+  required uint32 job_id = 2;
+}
+
+message StreamResponse {
+  optional string name = 1;
+  optional string data = 2;
+  optional uint32 exit_status = 3;
+  optional InfoResponse info = 4;
+}

data/lib/warden/protocol/version.rb

@@ -0,0 +1,7 @@
+# coding: UTF-8
+
+module Warden
+  module Protocol
+    VERSION = "0.1.3"
+  end
+end

data/spec/base_spec.rb

@@ -0,0 +1,150 @@
+# coding: UTF-8
+
+require "spec_helper"
+require "warden/protocol"
+
+describe Warden::Protocol::BaseRequest do
+  it "should respond to #wrap" do
+    request = Warden::Protocol::SpawnRequest.new(:handle => "blah",
+                                                 :script => "script")
+    wrapped = request.wrap
+    wrapped.should be_an_instance_of(Warden::Protocol::Message)
+    wrapped.type.should == Warden::Protocol::SpawnRequest.type
+    decoded = Warden::Protocol::SpawnRequest.decode(wrapped.payload)
+    decoded.handle.should == request.handle
+    decoded.script.should == request.script
+  end
+
+  it "should wrap beefcake errors" do
+    expect {
+      Warden::Protocol::SpawnRequest.new.wrap
+    }.to raise_error(Warden::Protocol::ProtocolError) { |e|
+      e.cause.class.name.should =~ /^Beefcake/
+    }
+  end
+end
+
+describe Warden::Protocol::BaseResponse do
+  it "should respond to #wrap" do
+    response = Warden::Protocol::SpawnResponse.new(:job_id => 1)
+    wrapped = response.wrap
+    wrapped.should be_an_instance_of(Warden::Protocol::Message)
+    wrapped.type.should == Warden::Protocol::SpawnResponse.type
+    decoded = Warden::Protocol::SpawnResponse.decode(wrapped.payload)
+    decoded.job_id.should == response.job_id
+  end
+
+  it "should wrap beefcake errors" do
+    expect {
+      Warden::Protocol::SpawnResponse.new.wrap
+    }.to raise_error(Warden::Protocol::ProtocolError) { |e|
+      e.cause.class.name.should =~ /^Beefcake/
+    }
+  end
+end
+
+describe "wrapped request" do
+  it "should respond to #request" do
+    w = Warden::Protocol::Message.new
+    w.type = Warden::Protocol::Message::Type::Spawn
+    w.payload = Warden::Protocol::SpawnRequest.new(:handle => "blah",
+                                                   :script => "script").encode
+    w.should be_valid
+
+    w.request.should be_a(Warden::Protocol::SpawnRequest)
+  end
+
+  it "should wrap beefcake errors" do
+    w = Warden::Protocol::Message.new
+    w.type = Warden::Protocol::Message::Type::Spawn
+    w.payload = "bad payload"
+    w.should be_valid
+
+    expect { w.request }.to raise_error(Warden::Protocol::ProtocolError)
+  end
+end
+
+describe "wrapped response" do
+  it "should respond to #response" do
+    w = Warden::Protocol::Message.new
+    w.type = Warden::Protocol::Message::Type::Spawn
+    w.payload = Warden::Protocol::SpawnResponse.new(:handle => "blah",
+                                                    :job_id => 2).encode
+    w.should be_valid
+
+    w.response.should be_a(Warden::Protocol::SpawnResponse)
+  end
+
+  it "should wrap beefcake errors" do
+    w = Warden::Protocol::Message.new
+    w.type = Warden::Protocol::Message::Type::Spawn
+    w.payload = "bad payload"
+
+    w.should be_valid
+
+    expect { w.response }.to raise_error(Warden::Protocol::ProtocolError)
+  end
+end
+
+describe Warden::Protocol do
+  before :all do
+    module Test
+      A = 1
+      B = 2
+    end
+  end
+
+  describe "#protocol_type_to_str" do
+    it "should return string representation of constants in a module" do
+      described_class.protocol_type_to_str(Test).should == "A, B"
+    end
+
+    it "should return string representation of symbol" do
+      described_class.protocol_type_to_str(:test).should == "test"
+    end
+
+    it "should return nil for invalid parameter" do
+      described_class.protocol_type_to_str(123).should be_nil
+    end
+  end
+
+  describe "#to_ruby_type" do
+    it "should use the type converter if is defined" do
+      Warden::Protocol::TypeConverter.should_receive("[]").once.
+        with(:uint32).and_return(lambda { |arg| Integer(arg) } )
+
+      described_class.to_ruby_type("123", :uint32).should == 123
+    end
+
+    it "should return value of constant defined in the module" do
+      Warden::Protocol::TypeConverter.should_receive("[]").once.
+        with(Test).and_return(nil)
+
+      described_class.to_ruby_type("A", Test).should == 1
+    end
+
+    it "should raise an error if a constant is not defined in a module" do
+      Warden::Protocol::TypeConverter.should_receive("[]").once.
+        with(Test).and_return(nil)
+
+      expect {
+        described_class.to_ruby_type("D", Test)
+      }.to raise_error { |error|
+        error.should be_an_instance_of TypeError
+        error.message.should == "The constant: 'D' is not defined in the module: 'Test'."
+      }
+    end
+
+    it "should raise an error if protocol type is not a module and no type converter is defined" do
+      Warden::Protocol::TypeConverter.should_receive("[]").once.
+        with(:test).and_return(nil)
+
+      expect {
+        described_class.to_ruby_type("test", :test)
+      }.to raise_error { |error|
+        error.should be_an_instance_of TypeError
+        error.message.should == "Non-existent protocol type passed: 'test'."
+      }
+    end
+  end
+end