Skip to content
Browse files

Add documentation to protocol definition

  • Loading branch information...
1 parent 7dc5c2a commit 8dc37a30f242a289d0e4c8e5ba30bf54f37b4708 Kowshik Prakasam and Pieter Noordhuis committed Feb 27, 2013
View
25 warden-protocol/lib/warden/protocol/pb/copy_in.proto
@@ -1,3 +1,28 @@
+// 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 {
View
28 warden-protocol/lib/warden/protocol/pb/copy_out.proto
@@ -1,3 +1,31 @@
+// 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 {
View
37 warden-protocol/lib/warden/protocol/pb/create.proto
@@ -1,3 +1,40 @@
+// 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 {
View
25 warden-protocol/lib/warden/protocol/pb/destroy.proto
@@ -1,3 +1,28 @@
+// 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 {
View
17 warden-protocol/lib/warden/protocol/pb/echo.proto
@@ -1,3 +1,20 @@
+// Echoes a message.
+//
+// ### Request
+//
+// * `message`: Message to echo.
+//
+// ### Response
+//
+// * `message`: Echoed message.
+//
+// ### Errors
+//
+// None.
+//
+// ### Definition
+//
+
package warden;
message EchoRequest {
View
12 warden-protocol/lib/warden/protocol/pb/error.proto
@@ -1,3 +1,15 @@
+// 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 {
View
24 warden-protocol/lib/warden/protocol/pb/info.proto
@@ -1,3 +1,27 @@
+// 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 {
View
17 warden-protocol/lib/warden/protocol/pb/limit_bandwidth.proto
@@ -1,3 +1,20 @@
+// Limits the network bandwidth for a container.
+//
+// ### Request
+//
+// > **TODO**
+//
+// ### Response
+//
+// > **TODO**
+//
+// ### Errors
+//
+// > **TODO**
+//
+// ### Definition
+//
+
package warden;
message LimitBandwidthRequest {
View
35 warden-protocol/lib/warden/protocol/pb/limit_disk.proto
@@ -1,6 +1,37 @@
-package warden;
+// 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
+//
-// The byte limits are used to compute block limits on the server side.
+package warden;
message LimitDiskRequest {
required string handle = 1;
View
23 warden-protocol/lib/warden/protocol/pb/limit_memory.proto
@@ -1,3 +1,26 @@
+// > **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 {
View
26 warden-protocol/lib/warden/protocol/pb/link.proto
@@ -1,3 +1,29 @@
+// 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 {
View
17 warden-protocol/lib/warden/protocol/pb/list.proto
@@ -1,3 +1,20 @@
+// Lists all containers.
+//
+// ### Request
+//
+// Empty.
+//
+// ### Response
+//
+// * `handles`: List of container handles.
+//
+// ### Errors
+//
+// None.
+//
+// ### Definition
+//
+
package warden;
message ListRequest {
View
2 warden-protocol/lib/warden/protocol/pb/message.proto
@@ -1,3 +1,5 @@
+// nodoc
+
package warden;
message Message {
View
26 warden-protocol/lib/warden/protocol/pb/net_in.proto
@@ -1,3 +1,29 @@
+// 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 {
View
24 warden-protocol/lib/warden/protocol/pb/net_out.proto
@@ -1,3 +1,27 @@
+// 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 {
View
17 warden-protocol/lib/warden/protocol/pb/ping.proto
@@ -1,3 +1,20 @@
+// Pings.
+//
+// ### Request
+//
+// Empty.
+//
+// ### Response
+//
+// Empty.
+//
+// ### Errors
+//
+// None.
+//
+// ### Definition
+//
+
package warden;
message PingRequest {
View
11 warden-protocol/lib/warden/protocol/pb/resource_limits.proto
@@ -1,3 +1,14 @@
+// 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 {
View
13 warden-protocol/lib/warden/protocol/pb/run.proto
@@ -1,3 +1,16 @@
+// 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 {
View
24 warden-protocol/lib/warden/protocol/pb/spawn.proto
@@ -1,3 +1,27 @@
+// 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 {
View
29 warden-protocol/lib/warden/protocol/pb/stop.proto
@@ -1,3 +1,32 @@
+// 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 {
View
27 warden-protocol/lib/warden/protocol/pb/stream.proto
@@ -1,3 +1,30 @@
+// 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 {

0 comments on commit 8dc37a3

Please sign in to comment.
Something went wrong with that request. Please try again.