Merge pull request #185 from cf-guardian/typed_errors

Add rich errors to the API

container.go

@@ -14,58 +14,65 @@ type Container interface {
 
 	// Returns the current run state of the container.
 	//
-	// Errors: container no longer exists,
+	// Errors:
-	//         system error.
+	// ContainerDestroyed - Container no longer exists,
-	RunState() (*RunState, error)
+	// SystemError - System error.
+	RunState() (*RunState, Error)
 
 	// Returns the current config of the container.
 	Config() *Config
 
 	// Start a process inside the container. Returns the PID of the new process (in the caller process's namespace) and a channel that will return the exit status of the process whenever it dies.
 	//
-	// Errors: container no longer exists,
+	// Errors:
-	//         config is invalid,
+	// ContainerDestroyed - Container no longer exists,
-	//         container is paused,
+	// ConfigInvalid - config is invalid,
-	//         system error.
+	// ContainerPaused - Container is paused,
-	Start(*ProcessConfig) (pid int, exitChan chan int, err error)
+	// SystemError - System error.
+	Start(config *ProcessConfig) (pid int, exitChan chan int, err Error)
 
 	// Destroys the container after killing all running processes.
 	//
 	// Any event registrations are removed before the container is destroyed.
 	// No error is returned if the container is already destroyed.
 	//
-	// Errors: system error.
+	// Errors:
-	Destroy() error
+	// SystemError - System error.
+	Destroy() Error
 
 	// Returns the PIDs inside this container. The PIDs are in the namespace of the calling process.
 	//
-	// Errors: container no longer exists,
+	// Errors:
-	//         system error.
+	// ContainerDestroyed - Container no longer exists,
+	// SystemError - System error.
 	//
 	// Some of the returned PIDs may no longer refer to processes in the Container, unless
 	// the Container state is PAUSED in which case every PID in the slice is valid.
-	Processes() ([]int, error)
+	Processes() ([]int, Error)
 
 	// Returns statistics for the container.
 	//
-	// Errors: container no longer exists,
+	// Errors:
-	//         system error.
+	// ContainerDestroyed - Container no longer exists,
-	Stats() (*ContainerStats, error)
+	// SystemError - System error.
+	Stats() (*ContainerStats, Error)
 
 	// If the Container state is RUNNING or PAUSING, sets the Container state to PAUSING and pauses
 	// the execution of any user processes. Asynchronously, when the container finished being paused the
 	// state is changed to PAUSED.
 	// If the Container state is PAUSED, do nothing.
 	//
-	// Errors: container no longer exists,
+	// Errors:
-	//         system error.
+	// ContainerDestroyed - Container no longer exists,
-	Pause() error
+	// SystemError - System error.
+	Pause() Error
 
 	// If the Container state is PAUSED, resumes the execution of any user processes in the
 	// Container before setting the Container state to RUNNING.
 	// If the Container state is RUNNING, do nothing.
 	//
-	// Errors: container no longer exists,
+	// Errors:
-	//         system error.
+	// ContainerDestroyed - Container no longer exists,
-	Resume() error
+	// SystemError - System error.
+	Resume() Error
 }

error.go

@@ -0,0 +1,37 @@
+package libcontainer
+
+// API error code type.
+type ErrorCode int
+
+// API error codes.
+const (
+	// Factory errors
+	IdInUse ErrorCode = iota
+	InvalidIdFormat
+	// TODO: add Load errors
+
+	// Container errors
+	ContainerDestroyed
+	ContainerPaused
+
+	// Common errors
+	ConfigInvalid
+	SystemError
+)
+
+// API Error type.
+type Error interface {
+	error
+
+	// Returns the stack trace, if any, which identifies the
+	// point at which the error occurred.
+	Stack() []byte
+
+	// Returns a verbose string including the error message
+	// and a representation of the stack trace suitable for
+	// printing.
+	Detail() string
+
+	// Returns the error code for this error.
+	Code() ErrorCode
+}

factory.go

@@ -12,13 +12,13 @@ type Factory interface {
 	// Returns the new container with a running process.
 	//
 	// Errors:
-	// id is already in use by a container
+	// IdInUse - id is already in use by a container
-	// id has incorrect format
+	// InvalidIdFormat - id has incorrect format
-	// config is invalid
+	// ConfigInvalid - config is invalid
-	// System error
+	// SystemError - System error
 	//
 	// On error, any partially created container parts are cleaned up (the operation is atomic).
-	Create(id string, config *Config) (Container, error)
+	Create(id string, config *Config) (Container, Error)
 
 	// Load takes an ID for an existing container and reconstructs the container
 	// from the state.
@@ -27,5 +27,6 @@ type Factory interface {
 	// Path does not exist
 	// Container is stopped
 	// System error
-	Load(id string) (Container, error)
+	// TODO: fix description
+	Load(id string) (Container, Error)
 }