operations

Documentation

Index

• Constants
• func NewError(operation Operation) error
• func PollInterval(interval time.Duration) grpc.CallOption
• type CurrentStep
• type Error
  • func (e *Error) Error() string
• type Operation
  • func New(operation *common.Operation, service common.OperationServiceClient) (Operation, error)
  • func NewCompleted(operation *common.Operation) (Operation, error)
• type OperationProgressTracker
  • func WrapProgressTracker(operation *opWrapper) OperationProgressTracker

Constants

const DefaultPollInterval = 1 * time.Second

Functions

func NewError

func NewError(operation Operation) error

NewError returns nil if the operation is successful and *Error otherwise.

func PollInterval

func PollInterval(interval time.Duration) grpc.CallOption

PollInterval returns grpc.CallOption you can pass to [Operation.Wait] to override the DefaultPollInterval.

If an interval isn't positive, the DefaultPollInterval is used.

Types

type CurrentStep

type CurrentStep interface {
	// Description returns a human-readable description the step
	Description() string

	// StartedAt returns the step start timestamp
	StartedAt() time.Time

	// FinishedAt returns the step finished timestamp or zero time if the step is not finished yet
	FinishedAt() time.Time

	// WorkDone returns the number of done ticks and total ticks of work for the step
	// supplied with this current step, if known.
	WorkDone() *common.ProgressTracker_WorkDone

	// WorkFraction returns the fraction of work completed for the operation
	// supplied with this progress tracker.
	// If the operation has no work, it returns 0.0.
	// If the operation is finished, it returns 1.0.
	// The second return value indicates whether the work fraction is available.
	// It is false if there are no work information.
	WorkFraction() (float64, bool)
}

type Error

type Error struct {
	Operation Operation
	Code      codes.Code
	Message   string
}

Error is returned by [Operation.Wait] if the operation is failed.

func (*Error) Error

func (e *Error) Error() string

type Operation

type Operation interface {
	// Done returns true if the operation is completed.
	Done() bool

	// Successful returns true if the operation is completed and status code is OK.
	Successful() bool

	// Poll fetches an updated operation from the server.
	// It does nothing if the operation is done.
	Poll(context.Context, ...grpc.CallOption) (Operation, error)

	// Wait polls the operation from the server until it's done.
	//
	// Important: It returns [*Error] if operation is not successful.
	//
	// Use [PollInterval] call option to override the [DefaultPollInterval].
	Wait(context.Context, ...grpc.CallOption) (Operation, error)

	// ID returns operation ID.
	ID() string

	// Description returns a human-readable description of the operation.
	Description() string

	// CreatedAt returns the operation creation timestamp.
	CreatedAt() time.Time

	// CreatedBy returns the operation initiator ID.
	CreatedBy() string

	// FinishedAt returns the completion timestamp if the operation is done and nil otherwise.
	FinishedAt() *time.Time

	// Request returns the request that generated this operation.
	Request() proto.Message

	// RequestHeaders returns headers of the request that generated this operation.
	RequestHeaders() http.Header

	// ResourceID returns ID of the resource that this operation creates, updates, deletes or otherwise changes.
	// It may be empty, see API documentation.
	ResourceID() string

	// ProgressData returns additional information about the progress of the operation.
	// It returns nil if a proto message is not present or is the google.protobuf.Empty.
	// Must be nil after operation is done.
	ProgressData() proto.Message

	// ProgressTracker returns a ProgressTracker for this operation.
	// Information about this operation's progress, if this operation tracks its progress.
	// If the operation tracks its progress, `ProgressTracker` will be present both
	// while the operation is running and after it has been completed.
	ProgressTracker() OperationProgressTracker

	// Status returns the status of the completed operation and nil otherwise.
	// The operation is successful if `Status() != nil && Status().Code() == codes.OK`.
	Status() *status.Status

	// Raw returns underlying protobuf operation.
	Raw() *common.Operation
}

Operation is a wrapper over protobuf operation message. All mutating service methods returns it. An operations can be either synchronous or asynchronous. Synchronous operations are completed immediately, while asynchronous operations may take time to finish. The client should call Wait to ensure an operation is fully completed.

func New

func New(operation *common.Operation, service common.OperationServiceClient) (Operation, error)

New validates an operation and returns Operation wrapper.

func NewCompleted

func NewCompleted(operation *common.Operation) (Operation, error)

NewCompleted accepts completed operation and returns Operation wrapper. Unlike New it doesn't accept common.OperationServiceClient as the operation is done. It returns an error if the operation is incomplete.

type OperationProgressTracker

type OperationProgressTracker interface {
	CurrentStep

	// EstimatedFinishedAt returns the estimated finished at time of the operation
	// supplied with this progress tracker. If not set, returns zero time.
	// For the finished operation, it returns the actual finished at time.
	EstimatedFinishedAt() time.Time

	// TimeFraction returns the fraction of time elapsed for the operation
	// supplied with this progress tracker.
	// If the operation has not started yet, it returns 0.0.
	// If the operation is finished, it returns 1.0.
	// The second return value indicates whether the time fraction is available.
	// It is false if the start time is unknown.
	TimeFraction() (float64, bool)

	// Steps returns the steps of the operation supplied with this progress tracker.
	// May contain only currently running steps or both finished and currently running steps.
	// May contain only a subset of finished steps.
	// May be empty if there are no steps or the steps are not provided.
	Steps() []CurrentStep
}

func WrapProgressTracker

func WrapProgressTracker(operation *opWrapper) OperationProgressTracker