operations

Documentation

Index

• func Clone() map[string]*Operation
• func ForwardedOperationResponse(op *api.Operation) response.Response
• func ForwardedOperationWebSocket(id string, source *websocket.Conn) response.Response
• func Init(d bool)
• func OperationResponse(op *Operation) response.Response
• func OperationWebSocket(op *Operation) response.Response
• func PruneExpiredOperations(ctx context.Context, s *state.State) error
• type Operation
  • func ConstructOperationFromDB(ctx context.Context, tx *sql.Tx, s *state.State, dbOp *cluster.Operation) (*Operation, error)
  • func OperationGetInternal(id string) (*Operation, error)
  • func ScheduleServerOperation(s *state.State, args OperationArgs) (*Operation, error)
  • func ScheduleUserOperationFromOperation(s *state.State, op *Operation, args OperationArgs) (*Operation, error)
  • func ScheduleUserOperationFromRequest(s *state.State, r *http.Request, args OperationArgs) (*Operation, error)
  • func (op *Operation) AddChildren(children ...*Operation)
  • func (op *Operation) Cancel()
  • func (op *Operation) CheckRequestor(r *http.Request) error
  • func (op *Operation) Children() []*Operation
  • func (op *Operation) Class() OperationClass
  • func (op *Operation) CommitMetadata() error
  • func (op *Operation) Connect(r *http.Request, w http.ResponseWriter) (chan error, error)
  • func (op *Operation) EntityURL() *api.URL
  • func (op *Operation) EventLifecycleRequestor() *api.EventLifecycleRequestor
  • func (op *Operation) ExtendMetadata(metadata map[string]any) error
  • func (op *Operation) ID() string
  • func (op *Operation) Inputs() map[string]any
  • func (op *Operation) IsRunning() bool
  • func (op *Operation) Metadata() map[string]any
  • func (op *Operation) Parent() *Operation
  • func (op *Operation) ProgressHandler(action string) ioprogress.ProgressHandler
  • func (op *Operation) Project() string
  • func (op *Operation) Render() (string, *api.Operation)
  • func (op *Operation) RenderFullWithoutProgress() (string, *api.OperationFull)
  • func (op *Operation) RenderWithoutProgress() (string, *api.Operation)
  • func (op *Operation) Requestor() *request.RequestorAuditor
  • func (op *Operation) Resources() map[entity.Type][]api.URL
  • func (op *Operation) SetEventServer(events *events.Server)
  • func (op *Operation) Status() api.StatusCode
  • func (op *Operation) Type() operationtype.Type
  • func (op *Operation) URL() string
  • func (op *Operation) UpdateMetadata(opMetadata map[string]any) error
  • func (op *Operation) Wait(ctx context.Context) error
• type OperationArgs
• type OperationClass
  • func (t OperationClass) String() string
• type OperationScheduler

Functions

func Clone

func Clone() map[string]*Operation

Clone returns a clone of the internal operations map containing references to the actual operations.

func ForwardedOperationResponse

func ForwardedOperationResponse(op *api.Operation) response.Response

ForwardedOperationResponse creates a response that forwards the metadata of an operation created on another node.

func ForwardedOperationWebSocket

func ForwardedOperationWebSocket(id string, source *websocket.Conn) response.Response

ForwardedOperationWebSocket returns a new forwarded websocket operation.

func Init

func Init(d bool)

Init sets the debug value for the operations package.

func OperationResponse

func OperationResponse(op *Operation) response.Response

OperationResponse returns an operation response.

func OperationWebSocket

func OperationWebSocket(op *Operation) response.Response

OperationWebSocket returns a new websocket operation.

func PruneExpiredOperations

func PruneExpiredOperations(ctx context.Context, s *state.State) error

PruneExpiredOperations deletes database entries of all operations which finished more than 24 hours ago. Normally, operations are cleared 5 seconds after they finish. However, more complex operations, such as bulk operations, are only cleared by this task, to allow more time to inspect their results.

Types

type Operation

type Operation struct {
	// contains filtered or unexported fields
}

Operation represents an operation.

func ConstructOperationFromDB

func ConstructOperationFromDB(ctx context.Context, tx *sql.Tx, s *state.State, dbOp *cluster.Operation) (*Operation, error)

ConstructOperationFromDB is a constructor of a single Operation object based on its database representation. ConstructOperationFromDB doesn't populate the parent field, as that would require loading all other operations from the DB. Instead, the caller is expected to set the parent field on the returned Operation object based on other loaded operations, if needed.

func OperationGetInternal

func OperationGetInternal(id string) (*Operation, error)

OperationGetInternal returns the operation with the given id. It returns an error if it doesn't exist.

func ScheduleServerOperation

func ScheduleServerOperation(s *state.State, args OperationArgs) (*Operation, error)

ScheduleServerOperation schedules a new Operation that runs as a server background task.

func ScheduleUserOperationFromOperation

func ScheduleUserOperationFromOperation(s *state.State, op *Operation, args OperationArgs) (*Operation, error)

ScheduleUserOperationFromOperation schedules a new Operation from the given operation. The operation must have a requestor as that is used for auditing.

func ScheduleUserOperationFromRequest

func ScheduleUserOperationFromRequest(s *state.State, r *http.Request, args OperationArgs) (*Operation, error)

ScheduleUserOperationFromRequest schedules a new Operation from the given HTTP request. The request context must contain the requestor as that is used for auditing. The operation will keep a reference to the parent HTTP request until it completes so that it can report success or failure for API metrics.

func (*Operation) AddChildren

func (op *Operation) AddChildren(children ...*Operation)

AddChildren adds a child operation to the parent operation. It also sets the parent of the child operation to the parent operation.

func (*Operation) Cancel

func (op *Operation) Cancel()

Cancel cancels a running operation. If the operation cannot be cancelled, it returns an error.

func (*Operation) CheckRequestor

func (op *Operation) CheckRequestor(r *http.Request) error

CheckRequestor checks that the requestor of a given HTTP request is equal to the requestor of the operation.

func (*Operation) Children

func (op *Operation) Children() []*Operation

Children returns the child operations if this operation is a parent operation, or an empty slice if this operation is not a parent operation.

func (*Operation) Class

func (op *Operation) Class() OperationClass

Class returns the operation class.

func (*Operation) CommitMetadata

func (op *Operation) CommitMetadata() error

CommitMetadata commits the metadata and status of the operation to the database, and updates the updatedAt time.

func (*Operation) Connect

func (op *Operation) Connect(r *http.Request, w http.ResponseWriter) (chan error, error)

Connect connects a websocket operation. If the operation is not a websocket operation or the operation is not running, it returns an error.

func (*Operation) EntityURL

func (op *Operation) EntityURL() *api.URL

EntityURL returns the primary entity URL for the Operation. This is used by the LXD shutdown process to determine if it should wait for any operations to complete.

func (*Operation) EventLifecycleRequestor

func (op *Operation) EventLifecycleRequestor() *api.EventLifecycleRequestor

EventLifecycleRequestor returns the api.EventLifecycleRequestor for the operation.

func (*Operation) ExtendMetadata

func (op *Operation) ExtendMetadata(metadata map[string]any) error

ExtendMetadata updates the metadata of the operation with the additional data provided. It returns an error if the operation is not pending or running, or the operation is read-only.

func (*Operation) ID

func (op *Operation) ID() string

ID returns the operation ID.

func (*Operation) Inputs

func (op *Operation) Inputs() map[string]any

Inputs returns the operation inputs from the database.

func (*Operation) IsRunning

func (op *Operation) IsRunning() bool

IsRunning returns true if the operation run hook is still in progress.

func (*Operation) Metadata

func (op *Operation) Metadata() map[string]any

Metadata returns a copy of the operation Metadata.

func (*Operation) Parent

func (op *Operation) Parent() *Operation

Parent returns the parent operation if this operation is a child operation, or nil if this operation is not a child operation.

func (*Operation) ProgressHandler

func (op *Operation) ProgressHandler(action string) ioprogress.ProgressHandler

ProgressHandler implements ioprogress.ProgressReporter. This is used by instance and storage drivers to report I/O progress as they perform different actions (migration, download, image unpack, etc.).

func (*Operation) Project

func (op *Operation) Project() string

Project returns the operation project.

func (*Operation) Render

func (op *Operation) Render() (string, *api.Operation)

Render renders the operation structure. Returns URL of operation and operation info.

func (*Operation) RenderFullWithoutProgress

func (op *Operation) RenderFullWithoutProgress() (string, *api.OperationFull)

RenderFullWithoutProgress renders the operation structure, including child operations, without progress metadata.

func (*Operation) RenderWithoutProgress

func (op *Operation) RenderWithoutProgress() (string, *api.Operation)

RenderWithoutProgress renders the operation structure without progress metadata. This is used when operation constructed from the database is returned via API, as database likely contains stale progress metadata. Progress should be consumed from the websocket events, so it doesn't need to be returned in the API response.

func (*Operation) Requestor

func (op *Operation) Requestor() *request.RequestorAuditor

Requestor returns the initial requestor for this operation.

func (*Operation) Resources

func (op *Operation) Resources() map[entity.Type][]api.URL

Resources returns the operation resources.

func (*Operation) SetEventServer

func (op *Operation) SetEventServer(events *events.Server)

SetEventServer allows injection of event server.

func (*Operation) Status

func (op *Operation) Status() api.StatusCode

Status returns the operation status.

func (*Operation) Type

func (op *Operation) Type() operationtype.Type

Type returns the db operation type.

func (*Operation) URL

func (op *Operation) URL() string

URL returns the operation URL.

func (*Operation) UpdateMetadata

func (op *Operation) UpdateMetadata(opMetadata map[string]any) error

UpdateMetadata updates the metadata of the operation. It returns an error if the operation is not pending or running, or the operation is read-only. The api.MetadataEntityURL field is retained unless the caller sets api.MetadataEntityURL in the input map.

func (*Operation) Wait

func (op *Operation) Wait(ctx context.Context) error

Wait for the operation to be done. Returns non-nil error if operation failed or context was cancelled.

type OperationArgs

type OperationArgs struct {
	ProjectName string
	Type        operationtype.Type
	Class       OperationClass
	EntityURL   *api.URL
	Resources   map[entity.Type][]api.URL
	Metadata    map[string]any
	RunHook     func(ctx context.Context, op *Operation) error
	ConnectHook func(op *Operation, r *http.Request, w http.ResponseWriter) error

	Inputs map[string]any
	// ConflictReference allows to create the operation only if no other operation with the same conflict reference is running.
	// Empty ConflictReference means the operation can be started anytime.
	ConflictReference string
	Children          []*OperationArgs
	// contains filtered or unexported fields
}

OperationArgs contains all the arguments for operation creation.

type OperationClass

type OperationClass int

OperationClass represents the OperationClass type.

const (
	// OperationClassTask represents the Task OperationClass.
	OperationClassTask OperationClass = 1
	// OperationClassWebsocket represents the Websocket OperationClass.
	OperationClassWebsocket OperationClass = 2
	// OperationClassToken represents the Token OperationClass.
	OperationClassToken OperationClass = 3
)

func (OperationClass) String

func (t OperationClass) String() string

type OperationScheduler

type OperationScheduler func(s *state.State, args OperationArgs) (*Operation, error)

OperationScheduler is a signature used in function arguments where the function is used to deduplicate operation argument initialisation logic where the operation can be scheduled within an HTTP request or within an operation.