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 ¶
View Source
const QueryTypeStackTrace string = internal.QueryTypeStackTrace
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.
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
// - WorkflowExecutionAlreadyStartedError
// - 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)
// 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
// - workflow, workflowArgs are same as StartWorkflow's parameters
// - options.WorkflowIDReusePolicy will be ignored, and WorkflowIDReusePolicyAllowDuplicate will be used as the policy
// 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.
// 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
// The errors it can return:
// - BadRequestError
// - InternalServiceError
// - EntityNotExistError
ListClosedWorkflow(ctx context.Context, request *s.ListClosedWorkflowExecutionsRequest) (*s.ListClosedWorkflowExecutionsResponse, error)
// ListClosedWorkflow gets open workflow executions based on request filters
// The errors it can return:
// - BadRequestError
// - InternalServiceError
// - EntityNotExistError
ListOpenWorkflow(ctx context.Context, request *s.ListOpenWorkflowExecutionsRequest) (*s.ListOpenWorkflowExecutionsResponse, 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)
// 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 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, timeouted, 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 )
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.