specerror

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 6, 2019 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewError 

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."
	MaskedPathsAbs
	// 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."
	ReadonlyPathsAbs
)

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."
	RootReadonlyImplement
	// RootReadonlyOnWindowsFalse represents "* On Windows, this field MUST be omitted or false."
	RootReadonlyOnWindowsFalse
	// 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."
	LinuxProcOomScoreAdjSet
	// LinuxProcOomScoreAdjNotSet represents "If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`."
	LinuxProcOomScoreAdjNotSet
	// 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."
	ConfigUpdatesWithoutAffect
	// 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.