api

package
v0.0.0-...-08aea4b Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// The job was canceled by the user before it began to run.
	StatusCanceled = "Canceled"

	// The job could not be launched due to an error. This status does not
	// refer to jobs where the process exited with a non-zero exit code.
	StatusFailed = "Failed"

	// The job was launched and finished executing. This includes jobs where
	// the process exited with a non-zero exit code.
	StatusFinished = "Finished"

	// The job was forcibly killed while it was running, i.e. the job
	// process received SIGKILL.
	StatusKilled = "Killed"

	// The job was successfully submitted to the job scheduling system but
	// has not started running yet.
	StatusPending = "Pending"

	// The job is currently running.
	StatusRunning = "Running"

	// The job was running, but execution was paused and may be resumed at a
	// later time.
	StatusSuspended = "Suspended"
)

The available statuses (or states) of a Job.

View Source 
const MountTypeHost = "host"

A volume mounted from the host filesystem. This is the only widely-supported mount type.

Variables

View Source 
var (
	ErrJobNotRunning   = &Error{Code: CodeJobNotRunning}
	ErrJobNotFound     = &Error{Code: CodeJobNotFound}
	ErrInvalidJobState = &Error{Code: CodeInvalidJobState}
)

Common API errors.

View Source 
var (
	// Indicates that a mount spec (of the form `dst[:src][:ro]`) is
	// invalid.
	ErrInvalidMountSpec = fmt.Errorf("invalid mount spec")

	// Indicates that a path cannot be used as written in a mount spec.
	ErrInvalidMountPath = fmt.Errorf("invalid mount path")

	// Indicates that a port spec (of the form `port[:target]`) is invalid.
	ErrInvalidPortSpec = fmt.Errorf("invalid port spec")

	// Indicates that a port cannot be used as written in a port spec.
	ErrInvalidPort = fmt.Errorf("invalid port")

	// Indicates that an environment variable spec (of the form `env=var`)
	// is invalid.
	ErrInvalidEnvSpec = fmt.Errorf("invalid env spec")
)

Parsing errors.

View Source 
var APIVersion = Version{Major: 3, Minor: 5, Patch: 0}

APIVersion is the Launcher plugin API version supported by the types defined in this package.

Functions

func TerminalStatus 

func TerminalStatus(status string) bool

Returns true when the passed status is "terminal" -- i.e. the job's status will not change in the future.

Types

type Container 

type Container struct {
	// The name of the container image to use.
	Image string `json:"image"`

	// The ID of the user to run the container as. Optional.
	RunAsUser *int `json:"runAsUserId,omitempty"`

	// The ID of the group to run the container as. Optional.
	RunAsGroup *int `json:"runAsGroupId,omitempty"`

	// The list of additional group IDs to be added to the run-as user in
	// the container. Optional.
	SupplementalGroups []int `json:"supplementalGroupIds,omitempty"`
}

Container fields for a Job.

type Env 

type Env struct {
	// The name of the environment variable.
	Name string `json:"name"`

	// The value of the environment variable.
	Value string `json:"value"`
}

An environment variable.

func (*Env) Set 

func (e *Env) Set(s string) error

Set implements flag.Value by converting a text representation of the form `env=var` to an environment variable.

func (*Env) String 

func (e *Env) String() string

String implements fmt.Stringer and flag.Value by emitting the standard `env=var` text representation of an environment variable.

type ErrCode 

type ErrCode int
const (
	// The request failed for an undetermined reason. Used when the Plugin
	// cannot determine an appropriate error code for the error.
	CodeUnknown ErrCode = iota

	// The request is not supported by the Plugin. The runtime may also
	// return this if the Launcher sends a request that is not understood by
	// this package.
	CodeRequestNotSupported

	// The request is malformed. A Plugin may return this if it receives an
	// unexpected message from the Launcher. Usually this is only used by
	// the runtime.
	CodeInvalidRequest

	// The job does not exist in the scheduling system. The Plugin should
	// return this if the user-specified job ID does not exist.
	CodeJobNotFound

	// The request could not be completed because the Plugin had to restart.
	CodePluginRestarted

	// The request timed out while waiting for a response from the job
	// scheduling system.
	CodeTimeout

	// The job exists in the job scheduling system but is not in the running
	// state.
	CodeJobNotRunning

	// The job does not have output.
	CodeJobOutputNotFound

	// The job has an invalid job state for the requested action.
	CodeInvalidJobState

	// The job control action failed.
	CodeJobControlFailure

	// The Launcher is using a Launcher Plugin API version that is not
	// supported by the Plugin. This is sent automatically by the runtime if
	// appropriate.
	CodeUnsupportedVersion
)

An ErrCode represents a Launcher Plugin error code.

func (ErrCode) String 

func (e ErrCode) String() string

type Error 

type Error struct {
	Code ErrCode `json:"code"`
	Msg  string  `json:"message"`
}

Structured error representation for Launcher plugins.

func Errorf 

func Errorf(code ErrCode, format string, a ...interface{}) *Error

Errorf creates an error with the corresponding API code.

func (*Error) Error 

func (e *Error) Error() string

Error implements the error interface.

func (*Error) Is 

func (e *Error) Is(err error) bool

Is makes comparisons with errors.Is() possible.

type HostMount 

type HostMount struct {
	// The path of the mount on the host filesystem.
	Path string `json:"path"`
}

A volume mounted from the host filesystem. This is the only widely-supported mount type.

type Job 

type Job struct {
	// The unique ID of the Job.
	ID string `json:"id"`

	// The cluster of the Job. Optional.
	Cluster string `json:"cluster,omitempty"`

	// The name of the Job.
	Name string `json:"name,omitempty"`

	// The username of the user who launched the Job.
	User string `json:"user,omitempty"`

	// The group of the user who launched the Job. Optional.
	Group string `json:"group,omitempty"`

	// The list of queues that may be used to launch the Job, or the queue
	// that was used to run the Job.
	Queues []string `json:"queues,omitempty"`

	// The directory to use as the working directory for the Command or Exe.
	WorkDir string `json:"workingDirectory,omitempty"`

	// The container configuration of the Job, if the Cluster supports
	// containers. Optional.
	Container *Container `json:"container,omitempty"`

	// The host on which the Job was (or is being) run.
	Host string `json:"host,omitempty"`

	// The current status of the Job.
	Status string `json:"status,omitempty"`

	// The message or reason of the current status of the Job. Optional.
	StatusMsg string `json:"statusMessage,omitempty"`

	// The standard code/enum for the current status of the Job, if known.
	// Optional.
	StatusCode string `json:"statusCode,omitempty"`

	// The process ID of the Job, if applicable. Optional.
	Pid *int `json:"pid,omitempty"`

	// The exit code of the Command or Exe.
	ExitCode *int `json:"exitCode,omitempty"`

	// The shell command of the Job. Mutually exclusive with Exe.
	Command string `json:"command,omitempty"`

	// The executable of the Job. Mutually exclusive with Command.
	Exe string `json:"exe,omitempty"`

	// The location of the file which contains the standard output of the
	// Job.
	Stdout string `json:"stdoutFile,omitempty"`

	// The location of the file which contains the standard error output of
	// the Job.
	Stderr string `json:"stderrFile,omitempty"`

	// The standard input to be passed to the Command or Exe of the Job.
	Stdin string `json:"stdin,omitempty"`

	//The arguments of the Command or Exe of the Job.
	Args []string `json:"args,omitempty"`

	// The environment variables for the Job.
	Env []Env `json:"environment,omitempty"`

	// The list of placement constraints that were selected for the Job.
	Constraints []PlacementConstraint `json:"placementConstraints,omitempty"`

	// The time of the last update to the Job. Optional.
	LastUpdated *time.Time `json:"lastUpdateTime,omitempty"`

	// The time at which the Job was submitted to the Cluster. Optional.
	Submitted *time.Time `json:"submissionTime,omitempty"`

	// The exposed ports of the Job, if containers are used.
	Ports []Port `json:"exposedPorts,omitempty"`

	// The file system mounts to apply when the Job is run.
	Mounts []Mount `json:"mounts,omitempty"`

	// The custom configuration values of the Job.
	Config []JobConfig `json:"config,omitempty"`

	// The list of resource limits that were set for the Job.
	Limits []ResourceLimit `json:"resourceLimits,omitempty"`

	// The tags that were set for the Job. Used for filtering Jobs.
	Tags []string `json:"tags,omitempty"`

	// User-specified metadata for storing extension attributes.
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// The resource profile of the Job, if any. The default is always
	// "custom".
	Profile string `json:"resourceProfile,omitempty"`

	// Plugin-local storage of job attributes not exposed through Launcher's
	// existing API.
	Misc map[string]interface{} `json:"-"`
}

Launcher's representation of a job.

func (*Job) WithFields 

func (job *Job) WithFields(fields []string) *Job

WithFields returns a copy of the job with only the given fields populated. When fields is empty it returns the original job.

type JobConfig 

type JobConfig struct {
	// The name of the custom configuration value.
	Name string `json:"name"`

	// The type of the custom configuration value. Optional.
	Type string `json:"valueType,omitempty"`

	// The value of the custom configuration value. Optional.
	Value string `json:"value,omitempty"`
}

Custom Job configuration fields.

type JobFilter 

type JobFilter struct {
	// The set of tags that a job must have to be included.
	Tags []string `json:"tags,omitempty"`

	// If non-nil, the minimum submission time that a job must have to be
	// included.
	StartTime *time.Time `json:"startTime,omitempty"`

	// If non-nil, the maximum submission time that a job must have to be
	// included.
	EndTime *time.Time `json:"endTime,omitempty"`

	// If non-empty, a job must have one of these statuses to be included.
	Statuses []string `json:"statuses,omitempty"`

	// Narrow the list of returned fields.
	Fields []string `json:"fields,omitempty"`
}

A JobFilter describes a set of conditions (all optional) that must be met by a job to be included in a response.

func (*JobFilter) Includes 

func (f *JobFilter) Includes(job *Job) bool

Includes returns true if a Job meets all conditions for the filter, if any.

type JobID 

type JobID string

A JobID is represented by a string, but may be "*" in some cases to indicate any or all jobs.

type JobOperation 

type JobOperation int
const (
	// Indicates that the job should be suspended. This operation should be
	// equivalent to sending SIGSTOP.
	OperationSuspend JobOperation = iota

	// Indicates that the job should be resumed. This operation should be
	// equivalent to sending SIGCONT.
	OperationResume

	// Indicates that the job should be stopped. This operation should be
	// equivalent to sending SIGTERM.
	OperationStop

	// Indicates that the job should be killed. This operation should be
	// equivalent to sending SIGKILL.
	OperationKill

	// Indicates that a pending job should be canceled, if possible.
	OperationCancel
)

A JobOperation represents operations to control the state of a job.

func (JobOperation) String 

func (o JobOperation) String() string

func (JobOperation) ValidForStatus 

func (o JobOperation) ValidForStatus() string

type JobOutput 

type JobOutput int
const (
	OutputStdout JobOutput = iota

	OutputStderr

	OutputBoth
)

func (*JobOutput) MarshalText 

func (o *JobOutput) MarshalText() ([]byte, error)

MarshalText implements `encoding.TextMarshaler`.

func (JobOutput) String 

func (o JobOutput) String() string

func (*JobOutput) UnmarshalText 

func (o *JobOutput) UnmarshalText(text []byte) error

UnmarshalText implements `encoding.TextUnmarshaler`.

type Mount 

type Mount struct {
	// The destination path of the mount.
	Path string `json:"mountPath"`

	// Whether the source path should be mounted with write permissions.
	ReadOnly bool `json:"readOnly,omitempty"`

	// The source of the mount.
	Source MountSource `json:"mountSource"`
}

A volume mounted into a Job.

func (*Mount) Set 

func (m *Mount) Set(s string) error

Set implements flag.Value by converting a text representation of the form `src[:dst[:ro|:rw]]` to a host mount.

func (*Mount) String 

func (m *Mount) String() string

String implements fmt.Stringer and flag.Value by emitting a text representation of the form `src:dst:[:rw|:ro]` for a host mount.

type MountSource 

type MountSource struct {
	// The type of mount. The default supported options are "azureFile",
	// "cephFs", "glusterFs", "host", and "nfs". The "passthrough" value or
	// a custom value may be used for other mount types.
	Type string `json:"type"`

	// The mount source description. Must match the specified mount type.
	Source interface{} `json:"source"`
}

The underlying source for a volume mounted into a Job.

func (*MountSource) UnmarshalJSON 

func (ms *MountSource) UnmarshalJSON(data []byte) error

type Node 

type Node struct {
	Host     string     `json:"host"`
	IP       netip.Addr `json:"ipv4"`
	Port     string     `json:"port"`
	LastSeen time.Time  `json:"lastSeen"`
	Status   string     `json:"status"`
}

Represents a Launcher/plugin node when running in a load-balanced scenario.

func (*Node) Online 

func (n *Node) Online() bool

Online returns true when a node can be considered available, and false otherwise.

type PlacementConstraint 

type PlacementConstraint struct {
	// The name of the placement constraint.
	Name string `json:"name"`

	// One of the possible values of the placement constraint. Optional.
	Value string `json:"value,omitempty"`
}

A generic Job placement constraint.

type Port 

type Port struct {
	// The target port, within the container.
	TargetPort int `json:"targetPort"`

	// The published port, if different from the container port. Optional.
	PublishedPort *int `json:"publishedPort,omitempty"`

	// The network protocol to use. It should default to "TCP".
	Protocol string `json:"protocol"`
}

An exposed port for containerized jobs.

func (*Port) Set 

func (p *Port) Set(s string) error

Set implements flag.Value by converting a text representation of the form `port[:target][/protocol]` to a port.

func (*Port) String 

func (p *Port) String() string

String implements fmt.Stringer and flag.Value by emitting the standard `port:target/protocol` text representation of a port.

type ResourceLimit 

type ResourceLimit struct {
	// The type of the resource. One of "cpuCount", "cpuTime", "memory", or
	// "memorySwap".
	Type string `json:"type"`

	// The requested value of the resource. Optional when Default and/or Max
	// is given instead.
	Value string `json:"value,omitempty"`

	// The default value of the resource type. Optional when Value is present.
	Default string `json:"defaultValue,omitempty"`

	// The maximum value of the resource type. Optional when Value is present.
	Max string `json:"maxValue,omitempty"`
}

Resource controls for a Job.

type ResourceProfile 

type ResourceProfile struct {
	// The name of a resource profile.
	Name string `json:"name"`

	// A user-friendly name for the resource profile. Optional.
	DisplayName string `json:"displayName,omitempty"`

	// The corresponding resource limits for this profile. Optional.
	Limits []ResourceLimit `json:"limits,omitempty"`

	// The submission queue for this profile, if applicable. Optional.
	Queue string `json:"queue"`

	// Placement constraints for this profile. Optional.
	Constraints []PlacementConstraint `json:"placementConstraints"`
}

Details for a resource profile available on a cluster.

type Version 

type Version struct {
	Major    int    `json:"major"`
	Minor    int    `json:"minor"`
	Patch    int    `json:"patch"`
	Build    int    `json:"build,omitempty"`
	Revision string `json:"revision,omitempty"`
}

A Launcher version, including optional build and revision information.

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.