# specerror

package
Version: v0.9.0 Latest Latest

Go to latest
Published: Mar 6, 2019 License: Apache-2.0

## Documentation ¶

### Overview ¶

Package specerror implements runtime-spec-specific tooling for tracking RFC 2119 violations.

### Constants ¶

This section is empty.

### Variables ¶

This section is empty.

### Functions ¶

func NewError(code Code, err error, version string) error

NewError creates an Error referencing a spec violation. The error can be cast to an *Error for extracting structured information about the level of the violation and a reference to the violated spec condition.

A version string (for the version of the spec that was violated) must be set to get a working URL.

#### func NewRFCError ¶ added in v0.6.0

func NewRFCError(code Code, err error, version string) (*rfc2119.Error, error)

NewRFCError creates an rfc2119.Error referencing a spec violation.

A version string (for the version of the spec that was violated) must be set to get a working URL.

#### func NewRFCErrorOrPanic ¶ added in v0.6.0

func NewRFCErrorOrPanic(code Code, err error, version string) *rfc2119.Error

NewRFCErrorOrPanic creates an rfc2119.Error referencing a spec violation and panics on failure. This is handy for situations where you can't be bothered to check NewRFCError for failure.

### Types ¶

#### type Code ¶

type Code int64

Code represents the spec violation, enumerating both configuration violations and runtime violations.

const (
// ConfigInRootBundleDir represents "This REQUIRED file MUST reside in the root of the bundle directory"
ConfigInRootBundleDir Code = 0xa001 + iota
// ConfigConstName represents "This REQUIRED file MUST be named config.json."
ConfigConstName
// ArtifactsInSingleDir represents "When supplied, while these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle."
ArtifactsInSingleDir
)

define error codes

const (
// DefaultFilesystems represents "The following filesystems SHOULD be made available in each container's filesystem:"
DefaultFilesystems Code = 0xc001 + iota
// NSPathAbs represents "This value MUST be an absolute path in the runtime mount namespace."
NSPathAbs
// NSProcInPath represents "The runtime MUST place the container process in the namespace associated with that path."
NSProcInPath
// NSPathMatchTypeError represents "The runtime MUST generate an error if path is not associated with a namespace of type type."
NSPathMatchTypeError
// NSNewNSWithoutPath represents "If path is not specified, the runtime MUST create a new container namespace of type type."
NSNewNSWithoutPath
// NSInheritWithoutType represents "If a namespace type is not specified in the namespaces array, the container MUST inherit the runtime namespace of that type."
NSInheritWithoutType
// NSErrorOnDup represents "If a namespaces field contains duplicated namespaces with same type, the runtime MUST generate an error."
NSErrorOnDup
// UserNSMapOwnershipRO represents "The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping."
UserNSMapOwnershipRO
// DevicesAvailable represents "devices (array of objects, OPTIONAL) lists devices that MUST be available in the container."
DevicesAvailable
// DevicesFileNotMatch represents "If a file already exists at path that does not match the requested device, the runtime MUST generate an error."
DevicesFileNotMatch
// DevicesMajMinRequired represents "major, minor (int64, REQUIRED unless type is p) - major, minor numbers for the device."
DevicesMajMinRequired
// DevicesErrorOnDup represents "The same type, major and minor SHOULD NOT be used for multiple devices."
DevicesErrorOnDup
// DefaultDevices represents "In addition to any devices configured with this setting, the runtime MUST also supply default devices."
DefaultDevices
// CgroupsPathAbsOrRel represents "The value of cgroupsPath MUST be either an absolute path or a relative path."
CgroupsPathAbsOrRel
// CgroupsAbsPathRelToMount represents "In the case of an absolute path (starting with /), the runtime MUST take the path to be relative to the cgroups mount point."
CgroupsAbsPathRelToMount
// CgroupsPathAttach represents "If the value is specified, the runtime MUST consistently attach to the same place in the cgroups hierarchy given the same value of cgroupsPath."
CgroupsPathAttach
// CgroupsPathError represents "Runtimes MAY consider certain cgroupsPath values to be invalid, and MUST generate an error if this is the case."
CgroupsPathError
// DevicesApplyInOrder represents "The runtime MUST apply entries in the listed order."
DevicesApplyInOrder
// BlkIOWeightOrLeafWeightExist represents "You MUST specify at least one of weight or leafWeight in a given entry, and MAY specify both."
BlkIOWeightOrLeafWeightExist
// IntelRdtPIDWrite represents "If intelRdt is set, the runtime MUST write the container process ID to the <container-id>/tasks file in a mounted resctrl pseudo-filesystem, using the container ID from start and creating the container-id directory if necessary."
IntelRdtPIDWrite
// IntelRdtNoMountedResctrlError represents "If no mounted resctrl pseudo-filesystem is available in the runtime mount namespace, the runtime MUST generate an error."
IntelRdtNoMountedResctrlError
// NotManipResctrlWithoutIntelRdt represents "If intelRdt is not set, the runtime MUST NOT manipulate any resctrl pseudo-filesystems."
NotManipResctrlWithoutIntelRdt
// IntelRdtL3CacheSchemaWrite represents "If l3CacheSchema is set, runtimes MUST write the value to the schemata file in the <container-id> directory discussed in intelRdt."
IntelRdtL3CacheSchemaWrite
// IntelRdtL3CacheSchemaNotWrite represents "If l3CacheSchema is not set, runtimes MUST NOT write to schemata files in any resctrl pseudo-filesystems."
IntelRdtL3CacheSchemaNotWrite
// SeccSyscallsNamesRequired represents "names MUST contain at least one entry."
SeccSyscallsNamesRequired
// MaskedPathsAbs represents "maskedPaths (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read. The values MUST be absolute paths in the container namespace."
// ReadonlyPathsAbs represents "readonlyPaths (array of strings, OPTIONAL) will set the provided paths as readonly inside the container. The values MUST be absolute paths in the container namespace."
)

define error codes

const (
// WindowsLayerFoldersRequired represents "layerFolders MUST contain at least one entry."
WindowsLayerFoldersRequired Code = 0xd001 + iota
// WindowsHyperVPresent represents "If present, the container MUST be run with Hyper-V isolation."
WindowsHyperVPresent
// WindowsHyperVOmit represents "If omitted, the container MUST be run as a Windows Server container."
WindowsHyperVOmit
)

define error codes

const (
// SpecVersionInSemVer represents "ociVersion (string, REQUIRED) MUST be in SemVer v2.0.0 format and specifies the version of the Open Container Initiative Runtime Specification with which the bundle complies."
SpecVersionInSemVer Code = 0xb001 + iota
// RootOnWindowsRequired represents "On Windows, for Windows Server Containers, this field is REQUIRED."
RootOnWindowsRequired
// RootOnHyperVNotSet represents "For Hyper-V Containers, this field MUST NOT be set."
RootOnHyperVNotSet
// RootOnNonWindowsRequired represents "On all other platforms, this field is REQUIRED."
RootOnNonWindowsRequired
// RootPathOnWindowsGUID represents "On Windows, path MUST be a volume GUID path."
RootPathOnWindowsGUID
// RootPathOnPosixConvention represents "The value SHOULD be the conventional rootfs."
RootPathOnPosixConvention
// RootPathExist represents "A directory MUST exist at the path declared by the field."
RootPathExist
// RootReadonlyImplement represents "readonly (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false."
// RootReadonlyOnWindowsFalse represents "* On Windows, this field MUST be omitted or false."
// MountsInOrder represents "The runtime MUST mount entries in the listed order."
MountsInOrder
// MountsDestAbs represents "Destination of mount point: path inside container. This value MUST be an absolute path."
MountsDestAbs
// MountsDestOnWindowsNotNested represents "Windows: one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar)."
MountsDestOnWindowsNotNested
// MountsOptionsOnWindowsROSupport represents "Windows: runtimes MUST support ro, mounting the filesystem read-only when ro is given."
MountsOptionsOnWindowsROSupport
// ProcRequiredAtStart represents "This property is REQUIRED when start is called."
ProcRequiredAtStart
// ProcConsoleSizeIgnore represents "Runtimes MUST ignore consoleSize if terminal is false or unset."
ProcConsoleSizeIgnore
// ProcCwdAbs represents "cwd (string, REQUIRED) is the working directory that will be set for the executable. This value MUST be an absolute path."
ProcCwdAbs
// ProcArgsOneEntryRequired represents "This specification extends the IEEE standard in that at least one entry is REQUIRED, and that entry is used with the same semantics as execvp's *file*."
ProcArgsOneEntryRequired
// PosixProcRlimitsTypeGenError represents "The runtime MUST generate an error for any values which cannot be mapped to a relevant kernel interface."
PosixProcRlimitsTypeGenError
// PosixProcRlimitsTypeGet represents "For each entry in rlimits, a getrlimit(3) on type MUST succeed."
PosixProcRlimitsTypeGet
// PosixProcRlimitsTypeValueError represents "valid values are defined in the ... man page"
PosixProcRlimitsTypeValueError
// PosixProcRlimitsSoftMatchCur represents "rlim.rlim_cur MUST match the configured value."
PosixProcRlimitsSoftMatchCur
// PosixProcRlimitsHardMatchMax represents "rlim.rlim_max MUST match the configured value."
PosixProcRlimitsHardMatchMax
// PosixProcRlimitsErrorOnDup represents "If rlimits contains duplicated entries with same type, the runtime MUST generate an error."
PosixProcRlimitsErrorOnDup
// LinuxProcCapError represents "Any value which cannot be mapped to a relevant kernel interface MUST cause an error."
LinuxProcCapError
// LinuxProcOomScoreAdjSet represents "If oomScoreAdj is set, the runtime MUST set oom_score_adj to the given value."
// LinuxProcOomScoreAdjNotSet represents "If oomScoreAdj is not set, the runtime MUST NOT change the value of oom_score_adj."
// PlatformSpecConfOnWindowsSet represents "This MUST be set if the target platform of this spec is windows."
PlatformSpecConfOnWindowsSet
// PosixHooksPathAbs represents "This specification extends the IEEE standard in that path MUST be absolute."
PosixHooksPathAbs
// PosixHooksTimeoutPositive represents "If set, timeout MUST be greater than zero."
PosixHooksTimeoutPositive
// PosixHooksCalledInOrder represents "Hooks MUST be called in the listed order."
PosixHooksCalledInOrder
// PosixHooksStateToStdin represents "The state of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container."
PosixHooksStateToStdin
// PrestartTiming represents "The pre-start hooks MUST be called after the start operation is called but before the user-specified program command is executed."
PrestartTiming
// PoststartTiming represents "The post-start hooks MUST be called after the user-specified process is executed but before the start operation returns."
PoststartTiming
// PoststopTiming represents "The post-stop hooks MUST be called after the container is deleted but before the delete operation returns."
PoststopTiming
// AnnotationsKeyValueMap represents "Annotations MUST be a key-value map."
AnnotationsKeyValueMap
// AnnotationsKeyString represents "Keys MUST be strings."
AnnotationsKeyString
// AnnotationsKeyRequired represents "Keys MUST NOT be an empty string."
AnnotationsKeyRequired
// AnnotationsKeyReversedDomain represents "Keys SHOULD be named using a reverse domain notation - e.g. com.example.myKey."
AnnotationsKeyReversedDomain
// AnnotationsKeyReservedNS represents "Keys using the org.opencontainers namespace are reserved and MUST NOT be used by subsequent specifications."
AnnotationsKeyReservedNS
// AnnotationsKeyIgnoreUnknown represents "Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key."
AnnotationsKeyIgnoreUnknown
// AnnotationsValueString represents "Values MUST be strings."
AnnotationsValueString
// ExtensibilityIgnoreUnknownProp represents "Runtimes that are reading or processing this configuration file MUST NOT generate an error if they encounter an unknown property."
ExtensibilityIgnoreUnknownProp
// ValidValues represents "Runtimes that are reading or processing this configuration file MUST generate an error when invalid or unsupported values are encountered."
ValidValues
)

define error codes

const (
// NonError represents that an input is not an error
NonError Code = 0x1a001 + iota
// NonRFCError represents that an error is not a rfc2119 error
NonRFCError
)
const (
// EntityOperSameContainer represents "The entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container."
EntityOperSameContainer Code = 0xe001 + iota
// StateIDUniq represents "id (string, REQUIRED) is the container's ID. This MUST be unique across all containers on this host."
StateIDUniq
// StateNewStatus represents "Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above."
StateNewStatus
// DefaultStateJSONPattern represents "When serialized in JSON, the format MUST adhere to the default pattern."
DefaultStateJSONPattern
// EnvCreateImplement represents "The container's runtime environment MUST be created according to the configuration in config.json."
EnvCreateImplement
// EnvCreateError represents "If the runtime is unable to create the environment specified in the config.json, it MUST generate an error."
EnvCreateError
// ProcNotRunAtResRequest represents "While the resources requested in the config.json MUST be created, the user-specified program (from process) MUST NOT be run at this time."
ProcNotRunAtResRequest
// ConfigUpdatesWithoutAffect represents "Any updates to config.json after this step MUST NOT affect the container."
// PrestartHooksInvoke represents "The prestart hooks MUST be invoked by the runtime."
PrestartHooksInvoke
// PrestartHookFailGenError represents "If any prestart hook fails, the runtime MUST generate an error, stop the container, and continue the lifecycle at step 9."
PrestartHookFailGenError
// ProcImplement represents "The runtime MUST run the user-specified program, as specified by process."
ProcImplement
// PoststartHooksInvoke represents "The poststart hooks MUST be invoked by the runtime."
PoststartHooksInvoke
// PoststartHookFailGenWarn represents "If any poststart hook fails, the runtime MUST log a warning, but the remaining hooks and lifecycle continue as if the hook had succeeded."
PoststartHookFailGenWarn
// UndoCreateSteps represents "The container MUST be destroyed by undoing the steps performed during create phase (step 2)."
UndoCreateSteps
// PoststopHooksInvoke represents "The poststop hooks MUST be invoked by the runtime."
PoststopHooksInvoke
// PoststopHookFailGenWarn represents "If any poststop hook fails, the runtime MUST log a warning, but the remaining hooks and lifecycle continue as if the hook had succeeded."
PoststopHookFailGenWarn
// ErrorsLeaveStateUnchange represents "Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging."
ErrorsLeaveStateUnchange
// WarnsLeaveFlowUnchange represents "Unless otherwise stated, logging a warning does not change the flow of the operation; it MUST continue as if the warning had not been logged."
WarnsLeaveFlowUnchange
// DefaultOperations represents "Unless otherwise stated, runtimes MUST support the default operations."
DefaultOperations
// QueryWithoutIDGenError represents "This operation MUST generate an error if it is not provided the ID of a container."
QueryWithoutIDGenError
// QueryNonExistGenError represents "Attempting to query a container that does not exist MUST generate an error."
QueryNonExistGenError
// QueryStateImplement represents "This operation MUST return the state of a container as specified in the State section."
QueryStateImplement
// CreateWithBundlePathAndID represents "This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container."
CreateWithBundlePathAndID
// CreateWithUniqueID represents "If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST generate an error and a new container MUST NOT be created."
CreateWithUniqueID
// CreateNewContainer represents "This operation MUST create a new container."
CreateNewContainer
// PropsApplyExceptProcOnCreate represents "All of the properties configured in config.json except for process MUST be applied."
PropsApplyExceptProcOnCreate
// ProcArgsApplyUntilStart represents process.args MUST NOT be applied until triggered by the start operation."
ProcArgsApplyUntilStart
// PropApplyFailGenError represents "If the runtime cannot apply a property as specified in the configuration, it MUST generate an error."
PropApplyFailGenError
// PropApplyFailNotCreate represents "If the runtime cannot apply a property as specified in the configuration, a new container MUST NOT be created."
PropApplyFailNotCreate
// StartWithoutIDGenError represents "start operation MUST generate an error if it is not provided the container ID."
StartWithoutIDGenError
// StartNotCreatedHaveNoEffect represents "Attempting to start a container that is not created MUST have no effect on the container."
StartNotCreatedHaveNoEffect
// StartNotCreatedGenError represents "Attempting to start a container that is not created MUST generate an error."
StartNotCreatedGenError
// StartProcImplement represents "start operation MUST run the user-specified program as specified by process."
StartProcImplement
// StartWithProcUnsetGenError represents "start operation MUST generate an error if process was not set."
StartWithProcUnsetGenError
// KillWithoutIDGenError represents "kill operation MUST generate an error if it is not provided the container ID."
KillWithoutIDGenError
// KillNonCreateRunHaveNoEffect represents "Attempting to send a signal to a container that is neither created nor running MUST have no effect on the container."
KillNonCreateRunHaveNoEffect
// KillNonCreateRunGenError represents "Attempting to send a signal to a container that is neither created nor running MUST generate an error."
KillNonCreateRunGenError
// KillSignalImplement represents "kill operation MUST send the specified signal to the container process."
KillSignalImplement
// DeleteWithoutIDGenError represents "delete operation MUST generate an error if it is not provided the container ID."
DeleteWithoutIDGenError
// DeleteNonStopHaveNoEffect represents "Attempting to delete a container that is not stopped MUST have no effect on the container."
DeleteNonStopHaveNoEffect
// DeleteNonStopGenError represents "Attempting to delete a container that is not stopped MUST generate an error."
DeleteNonStopGenError
// DeleteResImplement represents "Deleting a container MUST delete the resources that were created during the create step."
DeleteResImplement
// DeleteOnlyCreatedRes represents "Note that resources associated with the container, but not created by this container, MUST NOT be deleted."
DeleteOnlyCreatedRes
)

define error codes

const (
// DefaultRuntimeLinuxSymlinks represents "While creating the container (step 2 in the lifecycle), runtimes MUST create default symlinks if the source file exists after processing mounts."
DefaultRuntimeLinuxSymlinks Code = 0xf001 + iota
)

define error codes

#### func FindError ¶

func FindError(err error, code Code) Code

FindError finds an error from a source error (multiple error) and returns the error code if found. If the source error is nil or empty, return NonError. If the source error is not a multiple error, return NonRFCError.

#### type Error ¶

type Error struct {
// Err holds the RFC 2119 violation.
Err rfc2119.Error

// Code is a matchable holds a Code
Code Code
}

Error represents a runtime-spec violation.

#### func (*Error) Error ¶

func (err *Error) Error() string

Error returns the error message with specification reference.

#### type LevelErrors ¶ added in v0.3.0

type LevelErrors struct {
// Warnings holds Errors that were below a compliance-level threshold.
Warnings []*Error

// Error holds errors that were at or above a compliance-level
// threshold, as well as errors that are not Errors.
Error *multierror.Error
}

LevelErrors represents Errors filtered into fatal and warnings.

#### func SplitLevel ¶ added in v0.3.0

func SplitLevel(errIn error, level rfc2119.Level) (levelErrors LevelErrors, errOut error)

SplitLevel removes RFC 2119 errors with a level less than 'level' from the source error. If the source error is not a multierror, it is returned unchanged.