lro

package module
v0.9.1 Latest Latest
Warning

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

 Go to latest Published: Feb 22, 2024 License: Apache-2.0 Imports: 19 Imported by: 0

README

Long-Running Operations (LROs)

Background

Long-running operations (LROs) are a pattern in resource-driven design where an operation takes an extended period of time to complete. This can be due to a number of factors, such as the size of the operation, the amount of data involved, or the availability of resources.

LROs are often used for tasks such as:

  • Copying large amounts of data
  • Processing large amounts of data
  • Running complex queries
  • Executing long-running tasks

LROs can be implemented in a number of ways, but the most common approach is to use a client-server model. In this model, the client initiates the operation and the server performs the operation in the background. The client can then poll the server to check the status of the operation until it is complete.

More details on LROs are available at: https://google.aip.dev/151

This package makes managing LROs on your server super simple. 😎

Documentation

Overview

Package lro provides a client for managing long-running operations (LROs) using Google Cloud Bigtable. LROs are a pattern in resource-driven design where an operation takes an extended period of time to complete. This can be due to a number of factors, such as the size of the operation, the amount of data involved, or the availability of resources.

The lro package provides a number of features for managing LROs, including:

  • Creating LROs: The CreateOperation method creates a new LRO and stores it in Bigtable.
  • Getting LROs: The GetOperation method gets an LRO from Bigtable.
  • Updating LROs: The SetSuccessful and SetFailed methods update the status of an LRO in Bigtable.
  • Waiting for LROs to finish: The WaitOperation method returns the LRO when it is done or when a specified timeout is reached.

// More details on LROs are available at: https://google.aip.dev/151

Index

Constants

View Source 
const (
	ColumnFamily       = "0"
	ParentlessOpColumn = "0"
)

Bigtable constants

View Source 
const (
	// MetaKeyAlisLroParent specifies the metadata key name
	// for a long-running operation parent
	MetaKeyAlisLroParent = "x-alis-lro-parent"
)

Metadata constants

Variables

View Source 
var EOF = errors.New("EOF")

EOF is the error returned when no more entities (such as children operations) are available. Functions should return EOF only to signal a graceful end read.

Functions

func WaitOperation added in v0.5.1 

func WaitOperation(ctx context.Context, op *longrunningpb.Operation, origin origin,
	metadataCallback func(*anypb.Any) error,
	pollingFrequency time.Duration,
) (*longrunningpb.Operation, error)

WaitOperation waits for the operation to complete. The metadataCallback parameter can be used to handle metadata provided by the operation. The origin is the service from which the operation originates and should implement the origin interface.

Types

type Client added in v0.0.2 

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

Client manages the instance of the Bigtable table.

func NewClient 

func NewClient(ctx context.Context, googleProject string, bigTableInstance string, table string, rowKeyPrefix string) (*Client, error)

NewClient creates a new lro Client object. The function takes three arguments:

  • googleProject: The ID of the Google Cloud project that the LroClient object will use.
  • bigTableInstance: The name of the Bigtable instance that the LroClient object will use.
  • table: The name of the Bigtable table that the LroClient object will use.
  • rowKeyPrefix: This should be an empty string if you have a dedicated table for long-running ops, but if you are sharing a table, the rowKeyPrefix can be used to separate your long-op data from other data in the table

func (*Client) BatchWaitOperations added in v0.7.0 

func (c *Client) BatchWaitOperations(ctx context.Context, operations []*longrunningpb.Operation, timeout *durationpb.Duration) ([]*longrunningpb.Operation, error)

BatchWaitOperations is a batch version of the WaitOperation method.

func (*Client) CreateOperation added in v0.0.2 

func (c *Client) CreateOperation(ctx *context.Context, opts *CreateOptions) (*longrunningpb.Operation, error)

CreateOperation stores a new long-running operation in bigtable, with done=false

func (*Client) ForwardIncomingParentMetadata added in v0.8.1 

func (c *Client) ForwardIncomingParentMetadata(ctx context.Context) context.Context

ForwardIncomingParentMetadata forwards the incoming context metadata with the operation name, using the key as MetaKeyAlisLroParent

func (*Client) GetOperation added in v0.0.2 

func (c *Client) GetOperation(ctx context.Context, operationName string) (*longrunningpb.Operation, error)

GetOperation can be used directly in your GetOperation rpc method to return a long-running operation to a client

func (*Client) GetParent added in v0.8.0 

func (c *Client) GetParent(ctx context.Context, operation string) (string, error)

GetParent attempts to retrieve the parent operation name for a specified operation

func (*Client) ListImmediateChildrenOperations added in v0.8.0 

func (c *Client) ListImmediateChildrenOperations(ctx context.Context, parent string, opts *ListImmediateChildrenOperationsOptions) ([]*longrunningpb.Operation, string, error)

ListImmediateChildrenOperations provides the list of immediate children for a given operation

func (*Client) SetFailed added in v0.0.2 

func (c *Client) SetFailed(ctx context.Context, operationName string, error error, metadata proto.Message) (*longrunningpb.Operation, error)

SetFailed updates an existing long-running operation's done field to true, sets the error and updates the metadata if metaOptions.Update is true

func (*Client) SetParentInOutgoingMetadata added in v0.8.1 

func (c *Client) SetParentInOutgoingMetadata(ctx context.Context, operationName string) context.Context

SetOutgoingContextParentOperation appends the outgoing context metadata with the operation name, using the key as MetaKeyAlisLroParent

func (*Client) SetSuccessful added in v0.0.2 

func (c *Client) SetSuccessful(ctx context.Context, operationName string, response proto.Message, metadata proto.Message) (*longrunningpb.Operation, error)

SetSuccessful updates an existing long-running operation's done field to true, sets the response and updates the metadata if provided.

func (*Client) TraverseChildrenOperations added in v0.8.0 

func (c *Client) TraverseChildrenOperations(ctx context.Context, operation string, opts *TraverseChildrenOperationsOptions) ([]*OperationNode, error)

TraverseChildrenOperations returns a tree of all children for a given parent operation

func (*Client) UpdateMetadata added in v0.1.0 

func (c *Client) UpdateMetadata(ctx context.Context, operationName string, metadata proto.Message) (*longrunningpb.Operation, error)

UpdateMetadata updates an existing long-running operation's metadata. Metadata typically contains progress information and common metadata such as create time.

func (*Client) WaitOperation added in v0.0.6 

func (c *Client) WaitOperation(ctx context.Context, req *longrunningpb.WaitOperationRequest, metadataCallback func(*anypb.Any)) (*longrunningpb.Operation, error)

WaitOperation can be used directly in your WaitOperation rpc method to wait for a long-running operation to complete. The metadataCallback parameter can be used to handle metadata provided by the operation. Note that if you do not specify a timeout, the timeout is set to 49 seconds.

type CreateOptions added in v0.1.0 

type CreateOptions struct {
	Id       string     // Id is used to provide user defined operation Ids
	Parent   string     // Parent is the parent long-running operation responsible for creating the new LRO.  Format should be operations/*
	Metadata *anypb.Any // Metadata object as defined for the relevant LRO metadata response.
}

CreateOptions provide additional, optional, parameters to the CreateOperation method.

type ErrInvalidNextToken added in v0.8.0 

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

func (ErrInvalidNextToken) Error added in v0.8.0 

func (e ErrInvalidNextToken) Error() string

type ErrNotFound 

type ErrNotFound struct {
	Operation string // unavailable locations
}

ErrNotFound is returned when the requested operation does not exist in bigtable

func (ErrNotFound) Error 

func (e ErrNotFound) Error() string

type ErrWaitDeadlineExceeded added in v0.3.0 

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

ErrWaitDeadlineExceeded is returned when the WaitOperation exceeds the specified, or default, timeout

func (ErrWaitDeadlineExceeded) Error added in v0.3.0 

func (e ErrWaitDeadlineExceeded) Error() string

type InvalidOperationName 

type InvalidOperationName struct {
	Name string // unavailable locations
}

func (InvalidOperationName) Error 

func (e InvalidOperationName) Error() string

type ListImmediateChildrenOperationsOptions added in v0.8.0 

type ListImmediateChildrenOperationsOptions struct {
	// The maximum number of children operations to return.
	// If not specified, the entire list is returned.
	PageSize int
	// A page token, received from a previous ListImmediateChildrenOperations call.
	// If not specified, the first page of results is returned.
	//
	// When paginating, all other parameters provided to `ListBooks` must match
	// the call that provided the page token.
	PageToken string
}

ListImmediateChildrenOperationsOptions is an optional parameter that can be provided to ListImmediateChildrenOperations

type OperationNode added in v0.8.0 

type OperationNode struct {
	// The name of the operation.
	//
	// In the case that ChildrenOperations
	// exist, Operation represents a parent
	// operation that can be further traversed.
	// Else, the operation is the last node in
	// the overall operation tree.
	Operation string
	// The set of children operations to
	// the Operation.
	ChildrenOperations []*OperationNode
}

OperationNode provides a data structure to represent the relationship between an operation and potential children operations.

type TraverseChildrenOperationsOptions added in v0.8.0 

type TraverseChildrenOperationsOptions struct {
	// The maximum depth of the tree to return. If not specified, the entire tree is returned.
	MaxDepth int
}

TraverseChildrenOperationsOptions is an optional parameter that can be provided to TraverseChildrenOperations

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.