diff --git a/hst/enablement.go b/hst/enablement.go index deaacb9..7a1056d 100644 --- a/hst/enablement.go +++ b/hst/enablement.go @@ -11,14 +11,20 @@ import ( type Enablement byte const ( + // EWayland exposes a wayland pathname socket via security-context-v1. EWayland Enablement = 1 << iota + // EX11 adds the target user via X11 ChangeHosts and exposes the X11 pathname socket. EX11 + // EDBus enables the per-container xdg-dbus-proxy daemon. EDBus + // EPulse copies the PulseAudio cookie to [hst.PrivateTmp] and exposes the PulseAudio socket. EPulse + // EM is a noop. EM ) +// String returns a string representation of the flags set on [Enablement]. func (e Enablement) String() string { switch e { case 0: @@ -51,17 +57,17 @@ func (e Enablement) String() string { // NewEnablements returns the address of [Enablement] as [Enablements]. func NewEnablements(e Enablement) *Enablements { return (*Enablements)(&e) } -// enablementsJSON is the [json] representation of the [Enablement] bit field. -type enablementsJSON struct { +// Enablements is the [json] adapter for [Enablement]. +type Enablements Enablement + +// enablementsJSON is the [json] representation of [Enablements]. +type enablementsJSON = struct { Wayland bool `json:"wayland,omitempty"` X11 bool `json:"x11,omitempty"` DBus bool `json:"dbus,omitempty"` Pulse bool `json:"pulse,omitempty"` } -// Enablements is the [json] adapter for [Enablement]. -type Enablements Enablement - // Unwrap returns the underlying [Enablement]. func (e *Enablements) Unwrap() Enablement { if e == nil { diff --git a/hst/fs.go b/hst/fs.go index 07ed6b4..926d623 100644 --- a/hst/fs.go +++ b/hst/fs.go @@ -47,17 +47,16 @@ type Ops interface { Etc(host *check.Absolute, prefix string) Ops } -// ApplyState holds the address of [container.Ops] and any relevant application state. +// ApplyState holds the address of [Ops] and any relevant application state. type ApplyState struct { - // AutoEtcPrefix is the prefix for [container.AutoEtcOp]. + // AutoEtcPrefix is the prefix for [FSBind] in autoetc [FSBind.Special] condition. AutoEtcPrefix string Ops } -var ( - ErrFSNull = errors.New("unexpected null in mount point") -) +// ErrFSNull is returned by [json] on encountering a null [FilesystemConfig] value. +var ErrFSNull = errors.New("unexpected null in mount point") // FSTypeError is returned when [ContainerConfig.Filesystem] contains an entry with invalid type. type FSTypeError string @@ -90,7 +89,7 @@ func (f *FilesystemConfigJSON) Valid() bool { return f != nil && f.FilesystemConfig != nil && f.FilesystemConfig.Valid() } -// fsType holds the string representation of a [FilesystemConfig]'s concrete type. +// fsType holds the string representation of the concrete type of [FilesystemConfig]. type fsType struct { Type string `json:"type"` } diff --git a/hst/fsbind.go b/hst/fsbind.go index f94e467..bb1fc03 100644 --- a/hst/fsbind.go +++ b/hst/fsbind.go @@ -16,22 +16,23 @@ const FilesystemBind = "bind" // FSBind represents a host to container bind mount. type FSBind struct { - // mount point in container, same as Source if empty + // Pathname in the container mount namespace. Same as Source if nil. Target *check.Absolute `json:"dst,omitempty"` - // host filesystem path to make available to the container + // Pathname in the init mount namespace. Must not be nil. Source *check.Absolute `json:"src"` - // do not mount Target read-only + // Do not remount Target read-only. + // This has no effect if Source is mounted read-only in the init mount namespace. Write bool `json:"write,omitempty"` - // do not disable device files on Target, implies Write + // Allow access to devices (special files) on Target, implies Write. Device bool `json:"dev,omitempty"` - // create Source as a directory if it does not exist + // Create Source as a directory in the init mount namespace if it does not exist. Ensure bool `json:"ensure,omitempty"` - // skip this mount point if Source does not exist + // Silently skip this mount point if Source does not exist in the init mount namespace. Optional bool `json:"optional,omitempty"` - // enable special behaviour: - // for autoroot, Target must be set to [fhs.AbsRoot]; - // for autoetc, Target must be set to [fhs.AbsEtc] + /* Enable special behaviour: + For autoroot: Target must be [fhs.Root]. + For autoetc: Target must be [fhs.Etc]. */ Special bool `json:"special,omitempty"` } diff --git a/hst/fsephemeral.go b/hst/fsephemeral.go index 631235b..78c4a55 100644 --- a/hst/fsephemeral.go +++ b/hst/fsephemeral.go @@ -15,13 +15,13 @@ const FilesystemEphemeral = "ephemeral" // FSEphemeral represents an ephemeral container mount point. type FSEphemeral struct { - // mount point in container - Target *check.Absolute `json:"dst,omitempty"` - // do not mount filesystem read-only + // Pathname in the container mount namespace. + Target *check.Absolute `json:"dst"` + // Do not mount filesystem read-only. Write bool `json:"write,omitempty"` - // upper limit on the size of the filesystem + // Upper limit on the size of the filesystem. Size int `json:"size,omitempty"` - // initial permission bits of the new filesystem + // Initial permission bits of the new filesystem. Perm os.FileMode `json:"perm,omitempty"` } diff --git a/hst/fslink.go b/hst/fslink.go index 473506e..2a1e379 100644 --- a/hst/fslink.go +++ b/hst/fslink.go @@ -14,11 +14,11 @@ const FilesystemLink = "link" // FSLink represents a symlink in the container filesystem. type FSLink struct { - // link path in container + // Pathname in the container mount namespace. Target *check.Absolute `json:"dst"` - // linkname the symlink points to + // Arbitrary linkname value store in the symlink. Linkname string `json:"linkname"` - // whether to dereference linkname before creating the link + // Whether to treat Linkname as an absolute pathname and dereference before creating the link. Dereference bool `json:"dereference,omitempty"` } diff --git a/hst/fsoverlay.go b/hst/fsoverlay.go index 689970d..de4e14d 100644 --- a/hst/fsoverlay.go +++ b/hst/fsoverlay.go @@ -14,14 +14,14 @@ const FilesystemOverlay = "overlay" // FSOverlay represents an overlay mount point. type FSOverlay struct { - // mount point in container + // Pathname in the container mount namespace. Target *check.Absolute `json:"dst"` - // any filesystem, does not need to be on a writable filesystem, must not be nil + // Any filesystem, does not need to be on a writable filesystem, must not be nil. Lower []*check.Absolute `json:"lower"` - // the upperdir is normally on a writable filesystem, leave as nil to mount Lower readonly + // The upperdir is normally on a writable filesystem, leave as nil to mount Lower readonly. Upper *check.Absolute `json:"upper,omitempty"` - // the workdir needs to be an empty directory on the same filesystem as Upper, must not be nil if Upper is populated + // The workdir needs to be an empty directory on the same filesystem as Upper, must not be nil if Upper is populated. Work *check.Absolute `json:"work,omitempty"` } diff --git a/hst/hst.go b/hst/hst.go index 208b395..11e91e7 100644 --- a/hst/hst.go +++ b/hst/hst.go @@ -12,9 +12,12 @@ import ( // An AppError is returned while starting an app according to [hst.Config]. type AppError struct { - Step string - Err error - Msg string + // A user-facing description of where the error occurred. + Step string `json:"step"` + // The underlying error value. + Err error + // An arbitrary error message, overriding the return value of Message if not empty. + Msg string `json:"message,omitempty"` } func (e *AppError) Error() string { return e.Err.Error() } @@ -38,13 +41,13 @@ func (e *AppError) Message() string { // Paths contains environment-dependent paths used by hakurei. type Paths struct { - // temporary directory returned by [os.TempDir] (usually `/tmp`) + // Temporary directory returned by [os.TempDir], usually equivalent to [fhs.AbsTmp]. TempDir *check.Absolute `json:"temp_dir"` - // path to shared directory (usually `/tmp/hakurei.%d`, [Info.User]) + // Shared directory specific to the hsu userid, usually (`/tmp/hakurei.%d`, [Info.User]). SharePath *check.Absolute `json:"share_path"` - // XDG_RUNTIME_DIR value (usually `/run/user/%d`, uid) + // Checked XDG_RUNTIME_DIR value, usually (`/run/user/%d`, uid). RuntimePath *check.Absolute `json:"runtime_path"` - // application runtime directory (usually `/run/user/%d/hakurei`) + // Shared directory specific to the hsu userid located in RuntimePath, usually (`/run/user/%d/hakurei`, uid). RunDirPath *check.Absolute `json:"run_dir_path"` }