serverstate

Documentation

Overview

Package serverstate exports the interface and verification harness for implementing a new state storage backend for the server.

Additional state storage backends is not an officially supported extension of Waypoint, so you do this at your own peril. It will not be supported. However, this package is exported because we maintain our own private state backends for other use cases of Waypoint.

Index

• Constants
• Variables
• type Instance
  • func (i *Instance) Proto() *pb.Instance
• type InstanceExec
• type Interface
• type Job
• type ListOperationOption
  • func ListWithOrder(f *pb.OperationOrder) ListOperationOption
  • func ListWithPhysicalState(f pb.Operation_PhysicalState) ListOperationOption
  • func ListWithStatusFilter(f ...*pb.StatusFilter) ListOperationOption
  • func ListWithWatchSet(ws memdb.WatchSet) ListOperationOption
  • func ListWithWorkspace(f *pb.Ref_Workspace) ListOperationOption
• type ListOperationOptions
  • func BuildListOperationOptions(ref *pb.Ref_Application, opts ...ListOperationOption) *ListOperationOptions
• type Pruner

Constants

const (
	DefaultUser   = "waypoint"
	DefaultUserId = "00000000000000000000000001"
)

See the docs in singleprocess.

Variables

var (
	JobWaitingTimeout   = 2 * time.Minute
	JobHeartbeatTimeout = 2 * time.Minute
)

These variables control the timeouts associated with the job system. The job system implementaions MUST use them. They are GUARANTEED to be written only when the state implementation is NOT running. Therefore, no lock is needed to read them.

These MUST be used because the tests in statetest will manipulate these to verify various behaviors.

Types

type Instance

type Instance struct {
	Id           string
	DeploymentId string
	Project      string
	Application  string
	Workspace    string
	LogBuffer    *logbuffer.Buffer
	Type         pb.Instance_Type
	DisableExec  bool
}

Instance represents a running deployment instance for an application.

func (*Instance) Proto

func (i *Instance) Proto() *pb.Instance

type InstanceExec

type InstanceExec struct {
	Id         int64
	InstanceId string

	Args []string
	Pty  *pb.ExecStreamRequest_PTY

	ClientEventCh     <-chan *pb.ExecStreamRequest
	EntrypointEventCh chan<- *pb.EntrypointExecRequest
	Connected         uint32

	// This is the context that the client side is running inside.
	// It is used by the entrypoint side to detect if the client is still
	// around or not.
	Context context.Context
}

InstanceExec represents a single exec session.

type Interface

type Interface interface {
	// Close is always called when the server is shutting down or reloading
	// the state store. This should clean up any resources (file handles, etc.)
	// that the state storage is using.
	io.Closer

	HMACKeyEmpty() bool
	HMACKeyCreateIfNotExist(id string, size int) (*pb.HMACKey, error)
	HMACKeyGet(id string) (*pb.HMACKey, error)

	ServerConfigSet(*pb.ServerConfig) error
	ServerConfigGet() (*pb.ServerConfig, error)

	UserPut(*pb.User) error
	UserGet(*pb.Ref_User) (*pb.User, error)
	UserDelete(*pb.Ref_User) error
	UserList() ([]*pb.User, error)
	UserEmpty() (bool, error)
	UserGetOIDC(iss, sub string) (*pb.User, error)
	UserGetEmail(string) (*pb.User, error)

	AuthMethodPut(*pb.AuthMethod) error
	AuthMethodGet(*pb.Ref_AuthMethod) (*pb.AuthMethod, error)
	AuthMethodDelete(*pb.Ref_AuthMethod) error
	AuthMethodList() ([]*pb.AuthMethod, error)

	RunnerCreate(*pb.Runner) error
	RunnerDelete(string) error
	RunnerOffline(string) error
	RunnerAdopt(string, bool) error
	RunnerReject(string) error
	RunnerById(string, memdb.WatchSet) (*pb.Runner, error)
	RunnerList() ([]*pb.Runner, error)

	OnDemandRunnerConfigPut(*pb.OnDemandRunnerConfig) error
	OnDemandRunnerConfigGet(*pb.Ref_OnDemandRunnerConfig) (*pb.OnDemandRunnerConfig, error)
	OnDemandRunnerConfigDelete(*pb.Ref_OnDemandRunnerConfig) error
	OnDemandRunnerConfigList() ([]*pb.OnDemandRunnerConfig, error)
	OnDemandRunnerConfigDefault() ([]*pb.Ref_OnDemandRunnerConfig, error)

	ServerURLTokenSet(string) error
	ServerURLTokenGet() (string, error)

	ServerIdSet(id string) error
	ServerIdGet() (string, error)

	CreateSnapshot(io.Writer) error
	StageRestoreSnapshot(io.Reader) error

	ConfigSet(...*pb.ConfigVar) error
	ConfigGet(*pb.ConfigGetRequest) ([]*pb.ConfigVar, error)
	ConfigGetWatch(*pb.ConfigGetRequest, memdb.WatchSet) ([]*pb.ConfigVar, error)

	ConfigSourceSet(...*pb.ConfigSource) error
	ConfigSourceGet(*pb.GetConfigSourceRequest) ([]*pb.ConfigSource, error)
	ConfigSourceGetWatch(*pb.GetConfigSourceRequest, memdb.WatchSet) ([]*pb.ConfigSource, error)

	InstanceCreate(*Instance) error
	InstanceDelete(string) error
	InstanceById(string) (*Instance, error)
	InstancesByApp(*pb.Ref_Application, *pb.Ref_Workspace, memdb.WatchSet) ([]*Instance, error)
	InstancesByDeployment(string, memdb.WatchSet) ([]*Instance, error)

	WorkspaceList() ([]*pb.Workspace, error)
	WorkspaceListByProject(*pb.Ref_Project) ([]*pb.Workspace, error)
	WorkspaceListByApp(*pb.Ref_Application) ([]*pb.Workspace, error)
	WorkspaceGet(string) (*pb.Workspace, error)
	WorkspacePut(*pb.Workspace) error

	ProjectPut(*pb.Project) error
	ProjectGet(*pb.Ref_Project) (*pb.Project, error)
	ProjectDelete(*pb.Ref_Project) error
	ProjectUpdateDataRef(*pb.Ref_Project, *pb.Ref_Workspace, *pb.Job_DataSource_Ref) error
	ProjectList() ([]*pb.Ref_Project, error)
	ProjectListWorkspaces(*pb.Ref_Project) ([]*pb.Workspace_Project, error)
	ProjectPollPeek(memdb.WatchSet) (*pb.Project, time.Time, error)
	ProjectPollComplete(*pb.Project, time.Time) error

	AppPut(*pb.Application) (*pb.Application, error)
	AppDelete(*pb.Ref_Application) error
	AppGet(*pb.Ref_Application) (*pb.Application, error)
	ApplicationPollPeek(memdb.WatchSet) (*pb.Project, time.Time, error)
	ApplicationPollComplete(*pb.Project, time.Time) error
	GetFileChangeSignal(*pb.Ref_Application) (string, error)

	ArtifactPut(bool, *pb.PushedArtifact) error
	ArtifactGet(*pb.Ref_Operation) (*pb.PushedArtifact, error)
	ArtifactLatest(*pb.Ref_Application, *pb.Ref_Workspace) (*pb.PushedArtifact, error)
	ArtifactList(*pb.Ref_Application, ...ListOperationOption) ([]*pb.PushedArtifact, error)

	BuildPut(bool, *pb.Build) error
	BuildGet(*pb.Ref_Operation) (*pb.Build, error)
	BuildLatest(*pb.Ref_Application, *pb.Ref_Workspace) (*pb.Build, error)
	BuildList(*pb.Ref_Application, ...ListOperationOption) ([]*pb.Build, error)

	DeploymentPut(bool, *pb.Deployment) error
	DeploymentGet(*pb.Ref_Operation) (*pb.Deployment, error)
	DeploymentLatest(*pb.Ref_Application, *pb.Ref_Workspace) (*pb.Deployment, error)
	DeploymentList(*pb.Ref_Application, ...ListOperationOption) ([]*pb.Deployment, error)

	ReleasePut(bool, *pb.Release) error
	ReleaseGet(*pb.Ref_Operation) (*pb.Release, error)
	ReleaseLatest(*pb.Ref_Application, *pb.Ref_Workspace) (*pb.Release, error)
	ReleaseList(*pb.Ref_Application, ...ListOperationOption) ([]*pb.Release, error)

	StatusReportPut(bool, *pb.StatusReport) error
	StatusReportGet(*pb.Ref_Operation) (*pb.StatusReport, error)
	StatusReportLatest(
		*pb.Ref_Application,
		*pb.Ref_Workspace,
		func(*pb.StatusReport) (bool, error),
	) (*pb.StatusReport, error)
	StatusReportList(*pb.Ref_Application, ...ListOperationOption) ([]*pb.StatusReport, error)

	TriggerPut(*pb.Trigger) error
	TriggerGet(*pb.Ref_Trigger) (*pb.Trigger, error)
	TriggerDelete(*pb.Ref_Trigger) error
	TriggerList(*pb.Ref_Workspace, *pb.Ref_Project, *pb.Ref_Application, []string) ([]*pb.Trigger, error)

	JobCreate(...*pb.Job) error
	JobProjectScopedRequest(*pb.Ref_Project, *pb.Job) ([]*pb.QueueJobRequest, error)
	JobList(*pb.ListJobsRequest) ([]*pb.Job, error)
	JobById(string, memdb.WatchSet) (*Job, error)
	JobPeekForRunner(context.Context, *pb.Runner) (*Job, error)
	JobAssignForRunner(context.Context, *pb.Runner) (*Job, error)
	JobAck(string, bool) (*Job, error)
	JobUpdateRef(string, *pb.Job_DataSource_Ref) error
	JobUpdate(string, func(*pb.Job) error) error
	JobComplete(string, *pb.Job_Result, error) error
	JobCancel(string, bool) error
	JobHeartbeat(string) error
	JobExpire(string) error
	JobIsAssignable(context.Context, *pb.Job) (bool, error)

	TaskPut(*pb.Task) error
	TaskGet(*pb.Ref_Task) (*pb.Task, error)
	TaskDelete(*pb.Ref_Task) error
	TaskList() ([]*pb.Task, error)
}

Interface is the primary interface implemented by an implementation.

This is an internal interface because (1) we don't expect or support any external implementations and (2) we can absolutely change this interface anytime we want or find it convenient, but we have to make sure so simultaneously modify all our implementations.

type Job

type Job struct {
	// Full job structure.
	*pb.Job

	// OutputBuffer is the terminal output for this job. This is a buffer
	// that may not contain the full amount of output depending on the
	// time of connection.
	OutputBuffer *logbuffer.Buffer

	// Blocked is true if this job is blocked for some reason. The reasons
	// a job may be blocked:
	//  - another job for the same project/app/workspace.
	//  - a dependent job hasn't completed yet
	Blocked bool
}

Job is the exported structure that is returned for most state APIs and gives callers access to more information than the pure job structure.

type ListOperationOption

type ListOperationOption func(opts *ListOperationOptions)

ListOperationOption is an exported type to set configuration for listing operations.

func ListWithOrder

func ListWithOrder(f *pb.OperationOrder) ListOperationOption

ListWithOrder sets ordering on the list operation.

func ListWithPhysicalState

func ListWithPhysicalState(f pb.Operation_PhysicalState) ListOperationOption

ListWithPhysicalState sets ordering on the list operation.

func ListWithStatusFilter

func ListWithStatusFilter(f ...*pb.StatusFilter) ListOperationOption

ListWithStatusFilter sets a status filter.

func ListWithWatchSet

func ListWithWatchSet(ws memdb.WatchSet) ListOperationOption

ListWithWatchSet registers watches for the listing, allowing the watcher to detect if new items are added.

func ListWithWorkspace

func ListWithWorkspace(f *pb.Ref_Workspace) ListOperationOption

ListWithWorkspace sets ordering on the list operation.

type ListOperationOptions

type ListOperationOptions struct {
	Application   *pb.Ref_Application
	Workspace     *pb.Ref_Workspace
	Status        []*pb.StatusFilter
	Order         *pb.OperationOrder
	PhysicalState pb.Operation_PhysicalState
	WatchSet      memdb.WatchSet
}

ListOperationOptions are options that can be set for List calls on operations for filtering and limiting the response.

func BuildListOperationOptions

func BuildListOperationOptions(ref *pb.Ref_Application, opts ...ListOperationOption) *ListOperationOptions

BuildListOperationOptions is a helper for implementations to create a ListOperationOptions from an app ref and a set of options.

type Pruner

type Pruner interface {
	Interface

	Prune() error
}

Pruner is implemented by state storage implementations that require a periodic prune. The implementation can't control when this is called, but it will be called roughly every hour or shorter.

During pruning, other operations are still allowed to come in. It is up to the state implementation to handle safe concurrency.