warden-protocol 0.1.3

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

@@ -0,0 +1,35 @@
+// Copies files into a container.
+//
+// File permissions and symbolic links are be preserved, while hard links
+// are materialized. If the source path contains a trailing `/`, only the
+// contents of the directory will be copied. Otherwise, the outermost
+// directory, along with its contents, will be copied. The unprivileged
+// user inside the container is made owner of the resulting files.
+//
+// ### Request
+//
+// * `handle`: Container handle.
+// * `src_path`: Path on the host to copy from.
+// * `dst_path`: Path in the container to copy to.
+//
+// ### Response
+//
+// Empty.
+//
+// ### Errors
+//
+// > **TODO**
+//
+// ### Definition
+//
+
+package warden;
+
+message CopyInRequest {
+  required string handle = 1;
+  required string src_path = 2;
+  required string dst_path = 3;
+}
+
+message CopyInResponse {
+}

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

@@ -0,0 +1,39 @@
+// Copies files out of a container.
+//
+// File permissions and symbolic links are be preserved, while hard links
+// are materialized. If the source path contains a trailing `/`, only the
+// contents of the directory will be copied. Otherwise, the outermost
+// directory, along with its contents, will be copied.
+//
+// By default, the files on the host will be owned by root.
+// If the `owner` field in the request is specified (in the form of `USER:GROUP`),
+// the resulting files and directories will be owned by this user and group.
+//
+// ### Request
+//
+// * `handle`: Container handle.
+// * `src_path`: Path in the container to copy from.
+// * `dst_path`: Path on the host to copy to.
+//
+// ### Response
+//
+// Empty.
+//
+// ### Errors
+//
+// > **TODO**
+//
+// ### Definition
+//
+
+package warden;
+
+message CopyOutRequest {
+  required string handle = 1;
+  required string src_path = 2;
+  required string dst_path = 3;
+  optional string owner = 4;
+}
+
+message CopyOutResponse {
+}

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

@@ -0,0 +1,65 @@
+// Creates a new container.
+//
+// ### Request
+//
+// All parameters are optional.
+//
+// * `bind_mounts`: Contains the paths that should be mounted in the
+// container's filesystem. The `src_path` field for every bind mount holds the
+// path as seen from the host, where the `dst_path` field holds the path as
+// seem from the container.
+//
+// * `grace_time`: Can be used to specify how long a container can go
+// unreferenced by any client connection. After this time, the container will
+// automatically be destroyed. If not specified, the container will be
+// subject to the globally configured grace time.
+//
+// * `handle`: If specified, its value must be used to refer to the
+// container in future requests. If it is not specified,
+// warden uses its internal container ID as the container handle.
+//
+// > **TODO**: `network` and `rootfs`
+//
+// ### Response
+//
+// The `handle` field contains the handle that must be used to refer to the
+// container in future request. It is the same as the `handle` field in the
+// request, if it was passed.
+//
+// ### Errors
+//
+// * When the `handle`, if specified, is already taken.
+// * When one of the `bind_mount` paths does not exist.
+// * When resource allocations fail (subnet, user ID, etc).
+//
+// ### Definition
+//
+
+package warden;
+
+message CreateRequest {
+  message BindMount {
+    enum Mode {
+      RO = 0;
+      RW = 1;
+    }
+
+    required string src_path = 1;
+    required string dst_path = 2;
+    required Mode mode = 3;
+  }
+
+  repeated BindMount bind_mounts = 1;
+
+  optional uint32 grace_time = 2;
+
+  optional string handle = 3;
+
+  optional string network = 4;
+
+  optional string rootfs = 5;
+}
+
+message CreateResponse {
+  required string handle = 1;
+}

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

@@ -0,0 +1,33 @@
+// Destroys a container.
+//
+// When a container is destroyed, its resource allocations are released,
+// its filesystem is removed, and all references to its handle are removed.
+//
+// All resources that have been acquired during the lifetime of the container are released.
+// Examples of these resources are its subnet, its UID, and ports that were redirected to the container.
+//
+// > **TODO** Link to list of resources that can be acquired during the lifetime of a container.
+//
+// ### Request
+//
+// * `handle`: Container handle.
+//
+// ### Response
+//
+// Empty.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+//
+// ### Definition
+//
+
+package warden;
+
+message DestroyRequest {
+  required string handle = 1;
+}
+
+message DestroyResponse {
+}

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

@@ -0,0 +1,26 @@
+// Echoes a message.
+//
+// ### Request
+//
+// * `message`: Message to echo.
+//
+// ### Response
+//
+// * `message`: Echoed message.
+//
+// ### Errors
+//
+// None.
+//
+// ### Definition
+//
+
+package warden;
+
+message EchoRequest {
+  required string message = 1;
+}
+
+message EchoResponse {
+  required string message = 1;
+}

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

@@ -0,0 +1,19 @@
+// This is only a response.
+// If an error occurs while executing a request, it is captured and returned as an `ErrorResponse`.
+//
+// ### Response
+//
+// * `message`: Error message.
+// * `data`: Unused.
+// * `backtrace`: Unused.
+//
+// ### Definition
+//
+
+package warden;
+
+message ErrorResponse {
+  optional string message = 2;
+  optional string data = 4;
+  repeated string backtrace = 3;
+}

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

@@ -0,0 +1,95 @@
+// Returns information about a container.
+//
+// ### Request
+//
+// * `handle`: Container handle.
+//
+// ### Response
+//
+// * `state`: Either "active" or "stopped".
+// * `events`: List of events that occurred for the container. It currently includes only "oom" (Out Of Memory) event if it occurred.
+// * `host_ip`: IP address of the host side of the container's virtual ethernet pair.
+// * `container_ip`: IP address of the container side of the container's virtual ethernet pair.
+// * `container_path`: Path to the directory holding the container's files (both its control scripts and filesystem).
+// * `job_ids`: List of running jobs.
+//
+// > **TODO** Describe different types of stats.
+//
+// ### Errors
+//
+// * When `handle` does not refer to a container.
+//
+// ### Definition
+//
+
+package warden;
+
+message InfoRequest {
+  required string handle = 1;
+}
+
+message InfoResponse {
+  message MemoryStat {
+    optional uint64 cache                     =  1;
+    optional uint64 rss                       =  2;
+    optional uint64 mapped_file               =  3;
+    optional uint64 pgpgin                    =  4;
+    optional uint64 pgpgout                   =  5;
+    optional uint64 swap                      =  6;
+    optional uint64 pgfault                   =  7;
+    optional uint64 pgmajfault                =  8;
+    optional uint64 inactive_anon             =  9;
+    optional uint64 active_anon               = 10;
+    optional uint64 inactive_file             = 11;
+    optional uint64 active_file               = 12;
+    optional uint64 unevictable               = 13;
+    optional uint64 hierarchical_memory_limit = 14;
+    optional uint64 hierarchical_memsw_limit  = 15;
+    optional uint64 total_cache               = 16;
+    optional uint64 total_rss                 = 17;
+    optional uint64 total_mapped_file         = 18;
+    optional uint64 total_pgpgin              = 19;
+    optional uint64 total_pgpgout             = 20;
+    optional uint64 total_swap                = 21;
+    optional uint64 total_pgfault             = 22;
+    optional uint64 total_pgmajfault          = 23;
+    optional uint64 total_inactive_anon       = 24;
+    optional uint64 total_active_anon         = 25;
+    optional uint64 total_inactive_file       = 26;
+    optional uint64 total_active_file         = 27;
+    optional uint64 total_unevictable         = 28;
+  }
+
+  message CpuStat {
+    optional uint64 usage  = 1; // Nanoseconds
+    optional uint64 user   = 2; // Hz (USER_HZ specifically)
+    optional uint64 system = 3; // Hz
+  }
+
+  message DiskStat {
+    optional uint64 bytes_used  = 1;
+    optional uint64 inodes_used = 2;
+  }
+
+  message BandwidthStat {
+    optional uint64 in_rate   = 1;
+    optional uint64 in_burst  = 2;
+    optional uint64 out_rate  = 3;
+    optional uint64 out_burst = 4;
+  }
+
+  optional string state = 10;
+
+  repeated string events = 20;
+
+  optional string host_ip        = 30;
+  optional string container_ip   = 31;
+  optional string container_path = 32;
+
+  optional MemoryStat memory_stat       = 40;
+  optional CpuStat cpu_stat             = 41;
+  optional DiskStat disk_stat           = 42;
+  optional BandwidthStat bandwidth_stat = 43;
+
+  repeated uint64 job_ids = 44;
+}

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

@@ -0,0 +1,30 @@
+// Limits the network bandwidth for a container.
+//
+// ### Request
+//
+// > **TODO**
+//
+// ### Response
+//
+// > **TODO**
+//
+// ### Errors
+//
+// > **TODO**
+//
+// ### Definition
+//
+
+package warden;
+
+message LimitBandwidthRequest {
+  required string handle = 1;
+
+  required uint64 rate  = 2; // Bandwidth rate in byte(s)/sec
+  required uint64 burst = 3; // Allow burst size in byte(s)
+}
+
+message LimitBandwidthResponse {
+  required uint64 rate  = 1; // Bandwidth rate in byte(s)/sec
+  required uint64 burst = 2; // Allow burst size in byte(s)
+}

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

@@ -0,0 +1,70 @@
+// Limits the disk usage for a container.
+//
+// The disk limits that are set by this command only have effect for the container's unprivileged user.
+// Files/directories created by its privileged user are not subject to these limits.
+//
+// > **TODO** Link to page explaining how disk management works.
+//
+// ### Request
+//
+// * `handle`: Container handle.
+// * `block_soft`: New soft block limit.
+// * `block_hard`: New hard block limit.
+// * `inode_soft`: New soft inode limit.
+// * `inode_hard`: New hard inode limit.
+// * `byte_soft`: New soft block limit specified in bytes. Only has effect when `block_soft` is not specified.
+// * `byte_hard`: New hard block limit specified in bytes. Only has effect when `block_hard` is not specified.
+//
+// ### Response
+//
+// * `block_soft`: Soft block limit.
+// * `block_hard`: Hard block limit.
+// * `inode_soft`: Soft inode limit.
+// * `inode_hard`: Hard inode limit.
+// * `byte_soft`: Soft block limit specified in bytes.
+// * `byte_hard`: Hard block limit specified in bytes.
+//
+// ### Errors
+//
+// > **TODO**
+//
+// ### Definition
+//
+
+package warden;
+
+message LimitDiskRequest {
+  required string handle = 1;
+
+  optional uint64 block_limit = 10; // Alias for `block_hard`
+  optional uint64 block       = 11; // Alias for `block_hard`
+  optional uint64 block_soft  = 12;
+  optional uint64 block_hard  = 13;
+
+  optional uint64 inode_limit = 20; // Alias for `inode_hard`
+  optional uint64 inode       = 21; // Alias for `inode_hard`
+  optional uint64 inode_soft  = 22;
+  optional uint64 inode_hard  = 23;
+
+  optional uint64 byte_limit  = 30; // Alias for `byte_hard`
+  optional uint64 byte        = 31; // Alias for `byte_hard`
+  optional uint64 byte_soft   = 32;
+  optional uint64 byte_hard   = 33;
+}
+
+message LimitDiskResponse {
+  optional uint64 block_limit = 10; // Alias for `block_hard`
+  optional uint64 block       = 11; // Alias for `block_hard`
+  optional uint64 block_soft  = 12;
+  optional uint64 block_hard  = 13;
+
+  optional uint64 inode_limit = 20; // Alias for `inode_hard`
+  optional uint64 inode       = 21; // Alias for `inode_hard`
+  optional uint64 inode_soft  = 22;
+  optional uint64 inode_hard  = 23;
+
+  optional uint64 byte_limit  = 30; // Alias for `byte_hard`
+  optional uint64 byte        = 31; // Alias for `byte_hard`
+  optional uint64 byte_soft   = 32;
+  optional uint64 byte_hard   = 33;
+}

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

@@ -0,0 +1,34 @@
+// > **TODO** Link to page explaining how memory limits works.
+//
+// ### Request
+//
+// The field `limit_in_bytes` is optional.
+// When it is not specified, the memory usage limit will not be changed.
+// When it is specified, but not a multiple of the page size,
+// it is rounded up to the nearest multiple of the page size (the default page size is 4K).
+//
+// * `handle`: Container handle.
+// * `limit_in_bytes`: New memory usage limit in bytes.
+//
+// ### Response
+//
+// * `limit_in_bytes`: Memory usage limit in bytes.
+//
+// ### Errors
+//
+// > **TODO**
+//
+// ### Definition
+//
+
+package warden;
+
+message LimitMemoryRequest {
+  required string handle = 1;
+
+  optional uint64 limit_in_bytes = 2;
+}
+
+message LimitMemoryResponse {
+  optional uint64 limit_in_bytes = 1;
+}