Documentation
¶
Overview ¶
Package client contains functions to create Cadence clients used to communicate to Cadence service.
Use these to perform CRUD on domains and start or query workflow executions.
Index ¶
- Constants
- func NewValue(data []byte) encoded.Value
- func NewValues(data []byte) encoded.Values
- type Client
- type DomainClient
- type HistoryEventIterator
- type Options
- type ParentClosePolicy
- type QueryWorkflowWithOptionsRequest
- type QueryWorkflowWithOptionsResponse
- type StartWorkflowOptions
- type WorkflowIDReusePolicy
- type WorkflowRun
Constants ¶
View Source
const ( // QueryTypeStackTrace is the build in query type for Client.QueryWorkflow() call. Use this query type to get the call // stack of the workflow. The result will be a string encoded in the encoded.Value. QueryTypeStackTrace string = internal.QueryTypeStackTrace // QueryTypeOpenSessions is the build in query type for Client.QueryWorkflow() call. Use this query type to get all open // sessions in the workflow. The result will be a list of SessionInfo encoded in the encoded.Value. QueryTypeOpenSessions string = internal.QueryTypeOpenSessions )
View Source
const ( // ParentClosePolicyTerminate means terminating the child workflow ParentClosePolicyTerminate = internal.ParentClosePolicyTerminate // ParentClosePolicyRequestCancel means requesting cancellation on the child workflow ParentClosePolicyRequestCancel = internal.ParentClosePolicyRequestCancel // ParentClosePolicyAbandon means not doing anything on the child workflow ParentClosePolicyAbandon = internal.ParentClosePolicyAbandon )
Variables ¶
This section is empty.
Functions ¶
func NewValue ¶ added in v0.6.1
NewValue creates a new encoded.Value which can be used to decode binary data returned by Cadence. For example: User had Activity.RecordHeartbeat(ctx, "my-heartbeat") and then got response from calling Client.DescribeWorkflowExecution. The response contains binary field PendingActivityInfo.HeartbeatDetails, which can be decoded by using:
var result string // This need to be same type as the one passed to RecordHeartbeat NewValue(data).Get(&result)
func NewValues ¶ added in v0.6.1
NewValues creates a new encoded.Values which can be used to decode binary data returned by Cadence. For example: User had Activity.RecordHeartbeat(ctx, "my-heartbeat", 123) and then got response from calling Client.DescribeWorkflowExecution. The response contains binary field PendingActivityInfo.HeartbeatDetails, which can be decoded by using:
var result1 string var result2 int // These need to be same type as those arguments passed to RecordHeartbeat NewValues(data).Get(&result1, &result2)
Types ¶
type Client ¶
type Client interface {
// StartWorkflow starts a workflow execution
// The user can use this to start using a function or workflow type name.
// Either by
// StartWorkflow(ctx, options, "workflowTypeName", arg1, arg2, arg3)
// or
// StartWorkflow(ctx, options, workflowExecuteFn, arg1, arg2, arg3)
// The errors it can return:
// - EntityNotExistsError, if domain does not exists
// - BadRequestError
// - WorkflowExecutionAlreadyStartedError
// - InternalServiceError
StartWorkflow(ctx context.Context, options StartWorkflowOptions, workflow interface{}, args ...interface{}) (*workflow.Execution, error)
// ExecuteWorkflow starts a workflow execution and return a WorkflowRun instance and error
// The user can use this to start using a function or workflow type name.
// Either by
// ExecuteWorkflow(ctx, options, "workflowTypeName", arg1, arg2, arg3)
// or
// ExecuteWorkflow(ctx, options, workflowExecuteFn, arg1, arg2, arg3)
// The errors it can return:
// - EntityNotExistsError, if domain does not exists
// - BadRequestError
// - InternalServiceError
//
// WorkflowRun has 2 methods:
// - GetRunID() string: which return the first started workflow run ID (please see below)
// - Get(ctx context.Context, valuePtr interface{}) error: which will fill the workflow
// execution result to valuePtr, if workflow execution is a success, or return corresponding
// error. This is a blocking API.
// NOTE: if the started workflow return ContinueAsNewError during the workflow execution, the
// return result of GetRunID() will be the started workflow run ID, not the new run ID caused by ContinueAsNewError,
// however, Get(ctx context.Context, valuePtr interface{}) will return result from the run which did not return ContinueAsNewError.
// Say ExecuteWorkflow started a workflow, in its first run, has run ID "run ID 1", and returned ContinueAsNewError,
// the second run has run ID "run ID 2" and return some result other than ContinueAsNewError:
// GetRunID() will always return "run ID 1" and Get(ctx context.Context, valuePtr interface{}) will return the result of second run.
// NOTE: DO NOT USE THIS API INSIDE A WORKFLOW, USE workflow.ExecuteChildWorkflow instead
ExecuteWorkflow(ctx context.Context, options StartWorkflowOptions, workflow interface{}, args ...interface{}) (WorkflowRun, error)
// GetWorkflow retrieves a workflow execution and return a WorkflowRun instance (described above)
// - workflow ID of the workflow.
// - runID can be default(empty string). if empty string then it will pick the last running execution of that workflow ID.
//
// WorkflowRun has 2 methods:
// - GetRunID() string: which return the first started workflow run ID (please see below)
// - Get(ctx context.Context, valuePtr interface{}) error: which will fill the workflow
// execution result to valuePtr, if workflow execution is a success, or return corresponding
// error. This is a blocking API.
// If workflow not found, the Get() will return EntityNotExistsError.
// NOTE: if the started workflow return ContinueAsNewError during the workflow execution, the
// return result of GetRunID() will be the started workflow run ID, not the new run ID caused by ContinueAsNewError,
// however, Get(ctx context.Context, valuePtr interface{}) will return result from the run which did not return ContinueAsNewError.
// Say ExecuteWorkflow started a workflow, in its first run, has run ID "run ID 1", and returned ContinueAsNewError,
// the second run has run ID "run ID 2" and return some result other than ContinueAsNewError:
// GetRunID() will always return "run ID 1" and Get(ctx context.Context, valuePtr interface{}) will return the result of second run.
GetWorkflow(ctx context.Context, workflowID string, runID string) WorkflowRun
// SignalWorkflow sends a signals to a workflow in execution
// - workflow ID of the workflow.
// - runID can be default(empty string). if empty string then it will pick the running execution of that workflow ID.
// - signalName name to identify the signal.
// The errors it can return:
// - EntityNotExistsError
// - InternalServiceError
SignalWorkflow(ctx context.Context, workflowID string, runID string, signalName string, arg interface{}) error
// SignalWithStartWorkflow sends a signal to a running workflow.
// If the workflow is not running or not found, it starts the workflow and then sends the signal in transaction.
// - workflowID, signalName, signalArg are same as SignalWorkflow's parameters
// - options, workflow, workflowArgs are same as StartWorkflow's parameters
// The errors it can return:
// - EntityNotExistsError, if domain does not exist
// - BadRequestError
// - InternalServiceError
SignalWithStartWorkflow(ctx context.Context, workflowID string, signalName string, signalArg interface{},
options StartWorkflowOptions, workflow interface{}, workflowArgs ...interface{}) (*workflow.Execution, error)
// CancelWorkflow cancels a workflow in execution
// - workflow ID of the workflow.
// - runID can be default(empty string). if empty string then it will pick the running execution of that workflow ID.
// The errors it can return:
// - EntityNotExistsError
// - BadRequestError
// - InternalServiceError
CancelWorkflow(ctx context.Context, workflowID string, runID string) error
// TerminateWorkflow terminates a workflow execution.
// workflowID is required, other parameters are optional.
// - workflow ID of the workflow.
// - runID can be default(empty string). if empty string then it will pick the running execution of that workflow ID.
// The errors it can return:
// - EntityNotExistsError
// - BadRequestError
// - InternalServiceError
TerminateWorkflow(ctx context.Context, workflowID string, runID string, reason string, details []byte) error
// GetWorkflowHistory gets history events of a particular workflow
// - workflow ID of the workflow.
// - runID can be default(empty string). if empty string then it will pick the last running execution of that workflow ID.
// - whether use long poll for tracking new events: when the workflow is running, there can be new events generated during iteration
// of HistoryEventIterator, if isLongPoll == true, then iterator will do long poll, tracking new history event, i.e. the iteration
// will not be finished until workflow is finished; if isLongPoll == false, then iterator will only return current history events.
// - whether return all history events or just the last event, which contains the workflow execution end result
// Example:-
// To iterate all events,
// iter := GetWorkflowHistory(ctx, workflowID, runID, isLongPoll, filterType)
// events := []*shared.HistoryEvent{}
// for iter.HasNext() {
// event, err := iter.Next()
// if err != nil {
// return err
// }
// events = append(events, event)
// }
GetWorkflowHistory(ctx context.Context, workflowID string, runID string, isLongPoll bool, filterType s.HistoryEventFilterType) HistoryEventIterator
// CompleteActivity reports activity completed.
// activity Execute method can return activity.ErrResultPending to
// indicate the activity is not completed when it's Execute method returns. In that case, this CompleteActivity() method
// should be called when that activity is completed with the actual result and error. If err is nil, activity task
// completed event will be reported; if err is CanceledError, activity task cancelled event will be reported; otherwise,
// activity task failed event will be reported.
// An activity implementation should use GetActivityInfo(ctx).TaskToken function to get task token to use for completion.
// Example:-
// To complete with a result.
// CompleteActivity(token, "Done", nil)
// To fail the activity with an error.
// CompleteActivity(token, nil, cadence.NewCustomError("reason", details)
// The activity can fail with below errors ErrorWithDetails, TimeoutError, CanceledError.
CompleteActivity(ctx context.Context, taskToken []byte, result interface{}, err error) error
// CompleteActivityById reports activity completed.
// Similar to CompleteActivity, but may save cadence user from keeping taskToken info.
// activity Execute method can return activity.ErrResultPending to
// indicate the activity is not completed when it's Execute method returns. In that case, this CompleteActivityById() method
// should be called when that activity is completed with the actual result and error. If err is nil, activity task
// completed event will be reported; if err is CanceledError, activity task cancelled event will be reported; otherwise,
// activity task failed event will be reported.
// An activity implementation should use activityID provided in ActivityOption to use for completion.
// domain name, workflowID, activityID are required, runID is optional.
// The errors it can return:
// - ErrorWithDetails
// - TimeoutError
// - CanceledError
CompleteActivityByID(ctx context.Context, domain, workflowID, runID, activityID string, result interface{}, err error) error
// RecordActivityHeartbeat records heartbeat for an activity.
// taskToken - is the value of the binary "TaskToken" field of the "ActivityInfo" struct retrieved inside the activity.
// details - is the progress you want to record along with heart beat for this activity.
// The errors it can return:
// - EntityNotExistsError
// - InternalServiceError
RecordActivityHeartbeat(ctx context.Context, taskToken []byte, details ...interface{}) error
// RecordActivityHeartbeatByID records heartbeat for an activity.
// details - is the progress you want to record along with heart beat for this activity.
// The errors it can return:
// - EntityNotExistsError
// - InternalServiceError
RecordActivityHeartbeatByID(ctx context.Context, domain, workflowID, runID, activityID string, details ...interface{}) error
// ListClosedWorkflow gets closed workflow executions based on request filters.
// Retrieved workflow executions are sorted by start time in descending order.
// (Retrieved workflow executions could also be sorted by closed time in descending order,
// if cadence server side config EnableReadFromClosedExecutionV2 is set to true.)
// Note: heavy usage of this API may cause huge persistence pressure.
// The errors it can return:
// - BadRequestError
// - InternalServiceError
// - EntityNotExistError
ListClosedWorkflow(ctx context.Context, request *s.ListClosedWorkflowExecutionsRequest) (*s.ListClosedWorkflowExecutionsResponse, error)
// ListOpenWorkflow gets open workflow executions based on request filters.
// Retrieved workflow executions are sorted by start time in descending order.
// Note: heavy usage of this API may cause huge persistence pressure.
// The errors it can return:
// - BadRequestError
// - InternalServiceError
// - EntityNotExistError
ListOpenWorkflow(ctx context.Context, request *s.ListOpenWorkflowExecutionsRequest) (*s.ListOpenWorkflowExecutionsResponse, error)
// ListWorkflow gets workflow executions based on query. This API only works with ElasticSearch,
// and will return BadRequestError when using Cassandra or MySQL. The query is basically the SQL WHERE clause,
// examples:
// - "(WorkflowID = 'wid1' or (WorkflowType = 'type2' and WorkflowID = 'wid2'))".
// - "CloseTime between '2019-08-27T15:04:05+00:00' and '2019-08-28T15:04:05+00:00'".
// - to list only open workflow use "CloseTime = missing"
// Retrieved workflow executions are sorted by StartTime in descending order when list open workflow,
// and sorted by CloseTime in descending order for other queries.
// The errors it can return:
// - BadRequestError
// - InternalServiceError
ListWorkflow(ctx context.Context, request *s.ListWorkflowExecutionsRequest) (*s.ListWorkflowExecutionsResponse, error)
// ListArchivedWorkflow gets archived workflow executions based on query. This API will return BadRequest if Cadence
// cluster or target domain is not configured for visibility archival or read is not enabled. The query is basically the SQL WHERE clause.
// However, different visibility archivers have different limitations on the query. Please check the documentation of the visibility archiver used
// by your domain to see what kind of queries are accept and whether retrieved workflow executions are ordered or not.
// The errors it can return:
// - BadRequestError
// - InternalServiceError
ListArchivedWorkflow(ctx context.Context, request *s.ListArchivedWorkflowExecutionsRequest) (*s.ListArchivedWorkflowExecutionsResponse, error)
// ScanWorkflow gets workflow executions based on query. This API only works with ElasticSearch,
// and will return BadRequestError when using Cassandra or MySQL. The query is basically the SQL WHERE clause
// (see ListWorkflow for query examples).
// ScanWorkflow should be used when retrieving large amount of workflows and order is not needed.
// It will use more ElasticSearch resources than ListWorkflow, but will be several times faster
// when retrieving millions of workflows.
// The errors it can return:
// - BadRequestError
// - InternalServiceError
ScanWorkflow(ctx context.Context, request *s.ListWorkflowExecutionsRequest) (*s.ListWorkflowExecutionsResponse, error)
// CountWorkflow gets number of workflow executions based on query. This API only works with ElasticSearch,
// and will return BadRequestError when using Cassandra or MySQL. The query is basically the SQL WHERE clause
// (see ListWorkflow for query examples).
// The errors it can return:
// - BadRequestError
// - InternalServiceError
CountWorkflow(ctx context.Context, request *s.CountWorkflowExecutionsRequest) (*s.CountWorkflowExecutionsResponse, error)
// GetSearchAttributes returns valid search attributes keys and value types.
// The search attributes can be used in query of List/Scan/Count APIs. Adding new search attributes requires cadence server
// to update dynamic config ValidSearchAttributes.
GetSearchAttributes(ctx context.Context) (*s.GetSearchAttributesResponse, error)
// QueryWorkflow queries a given workflow's last execution and returns the query result synchronously. Parameter workflowID
// and queryType are required, other parameters are optional. The workflowID and runID (optional) identify the
// target workflow execution that this query will be send to. If runID is not specified (empty string), server will
// use the currently running execution of that workflowID. The queryType specifies the type of query you want to
// run. By default, cadence supports "__stack_trace" as a standard query type, which will return string value
// representing the call stack of the target workflow. The target workflow could also setup different query handler
// to handle custom query types.
// See comments at workflow.SetQueryHandler(ctx Context, queryType string, handler interface{}) for more details
// on how to setup query handler within the target workflow.
// - workflowID is required.
// - runID can be default(empty string). if empty string then it will pick the running execution of that workflow ID.
// - queryType is the type of the query.
// - args... are the optional query parameters.
// The errors it can return:
// - BadRequestError
// - InternalServiceError
// - EntityNotExistError
// - QueryFailError
QueryWorkflow(ctx context.Context, workflowID string, runID string, queryType string, args ...interface{}) (encoded.Value, error)
// QueryWorkflowWithOptions queries a given workflow execution and returns the query result synchronously.
// See QueryWorkflowWithOptionsRequest and QueryWorkflowWithOptionsResponse for more information.
// The errors it can return:
// - BadRequestError
// - InternalServiceError
// - EntityNotExistError
// - QueryFailError
QueryWorkflowWithOptions(ctx context.Context, request *QueryWorkflowWithOptionsRequest) (*QueryWorkflowWithOptionsResponse, error)
// DescribeWorkflowExecution returns information about the specified workflow execution.
// - runID can be default(empty string). if empty string then it will pick the last running execution of that workflow ID.
//
// The errors it can return:
// - BadRequestError
// - InternalServiceError
// - EntityNotExistError
DescribeWorkflowExecution(ctx context.Context, workflowID, runID string) (*s.DescribeWorkflowExecutionResponse, error)
// DescribeTaskList returns information about the target tasklist, right now this API returns the
// pollers which polled this tasklist in last few minutes.
// The errors it can return:
// - BadRequestError
// - InternalServiceError
// - EntityNotExistError
DescribeTaskList(ctx context.Context, tasklist string, tasklistType s.TaskListType) (*s.DescribeTaskListResponse, error)
}
Client is the client for starting and getting information about a workflow executions as well as completing activities asynchronously.
type DomainClient ¶
type DomainClient interface {
// Register a domain with cadence server
// The errors it can throw:
// - DomainAlreadyExistsError
// - BadRequestError
// - InternalServiceError
Register(ctx context.Context, request *s.RegisterDomainRequest) error
// Describe a domain. The domain has 3 part of information
// DomainInfo - Which has Name, Status, Description, Owner Email
// DomainConfiguration - Configuration like Workflow Execution Retention Period In Days, Whether to emit metrics.
// ReplicationConfiguration - replication config like clusters and active cluster name
// The errors it can throw:
// - EntityNotExistsError
// - BadRequestError
// - InternalServiceError
Describe(ctx context.Context, name string) (*s.DescribeDomainResponse, error)
// Update a domain.
// The errors it can throw:
// - EntityNotExistsError
// - BadRequestError
// - InternalServiceError
Update(ctx context.Context, request *s.UpdateDomainRequest) error
}
DomainClient is the client for managing operations on the domain. CLI, tools, ... can use this layer to manager operations on domain.
func NewDomainClient ¶
func NewDomainClient(service workflowserviceclient.Interface, options *Options) DomainClient
NewDomainClient creates an instance of a domain client, to manage lifecycle of domains.
type HistoryEventIterator ¶
type HistoryEventIterator = internal.HistoryEventIterator
HistoryEventIterator is a iterator which can return history events
type Options ¶
type Options = internal.ClientOptions
Options are optional parameters for Client creation.
type ParentClosePolicy ¶ added in v0.10.0
type ParentClosePolicy = internal.ParentClosePolicy
ParentClosePolicy defines the behavior performed on a child workflow when its parent is closed
type QueryWorkflowWithOptionsRequest ¶ added in v0.9.3
type QueryWorkflowWithOptionsRequest = internal.QueryWorkflowWithOptionsRequest
QueryWorkflowWithOptionsRequest defines the request to QueryWorkflowWithOptions
type QueryWorkflowWithOptionsResponse ¶ added in v0.9.3
type QueryWorkflowWithOptionsResponse = internal.QueryWorkflowWithOptionsResponse
QueryWorkflowWithOptionsResponse defines the response to QueryWorkflowWithOptions
type StartWorkflowOptions ¶
type StartWorkflowOptions = internal.StartWorkflowOptions
StartWorkflowOptions configuration parameters for starting a workflow execution.
type WorkflowIDReusePolicy ¶
type WorkflowIDReusePolicy = internal.WorkflowIDReusePolicy
WorkflowIDReusePolicy defines workflow ID reuse behavior.
const ( // WorkflowIDReusePolicyAllowDuplicateFailedOnly allow start a workflow execution // when workflow not running, and the last execution close state is in // [terminated, cancelled, timeout, failed]. WorkflowIDReusePolicyAllowDuplicateFailedOnly WorkflowIDReusePolicy = internal.WorkflowIDReusePolicyAllowDuplicateFailedOnly // WorkflowIDReusePolicyAllowDuplicate allow start a workflow execution using // the same workflow ID,when workflow not running. WorkflowIDReusePolicyAllowDuplicate WorkflowIDReusePolicy = internal.WorkflowIDReusePolicyAllowDuplicate // WorkflowIDReusePolicyRejectDuplicate do not allow start a workflow execution using the same workflow ID at all WorkflowIDReusePolicyRejectDuplicate WorkflowIDReusePolicy = internal.WorkflowIDReusePolicyRejectDuplicate // WorkflowIDReusePolicyTerminateIfRunning terminate current running workflow using the same workflow ID if exist, // then start a new run in one transaction WorkflowIDReusePolicyTerminateIfRunning = internal.WorkflowIDReusePolicyTerminateIfRunning )
type WorkflowRun ¶
type WorkflowRun = internal.WorkflowRun
WorkflowRun represents a started non child workflow
Source Files
Click to show internal directories.
Click to hide internal directories.