diff --git a/README.md b/README.md index f8bd0535..6b2f2416 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ A protoc plugin for generating typed Temporal clients and workers in Go from pro - [ID Expressions](#id-expressions) - [CLI](#cli) - [Test Client](#test-client) + - [Documentation](#documentation) - [License](#license) ## How it works @@ -628,6 +629,10 @@ The generated code includes resources that are compatible with the Temporal Go S **_Note:_** that all queries, signals, and udpates must be called via the test environment's `RegisterDelayedCallback` method prior to invoking the test client's synchronous `` method or an asynchronous workflow run's `Get` method. +## Documentation + +- [Generated code reference](./docs/generated.md) + ## License Licensed under the [MIT License](LICENSE.md) Copyright for portions of project cludden/protoc-gen-go-temporal are held by Chad Retz, 2021 as part of project cretz/temporal-sdk-go-advanced. All other copyright for project cludden/protoc-gen-go-temporal are held by Chris Ludden, 2023. diff --git a/docs/generated.md b/docs/generated.md new file mode 100644 index 00000000..d7834dcb --- /dev/null +++ b/docs/generated.md @@ -0,0 +1,1920 @@ +# Generated Code Reference + +- [Generated Code Reference](#generated-code-reference) +- [Constants \& Variables](#constants--variables) + - [ActivityName](#activityname) + - [QueryName](#queryname) + - [SignalName](#signalname) + - [TaskQueue](#taskqueue) + - [UpdateIDExpression](#updateidexpression) + - [UpdateName](#updatename) + - [WorkflowIDExpression](#workflowidexpression) + - [WorkflowName](#workflowname) + - [WorkflowSearchAttributesMapping](#workflowsearchattributesmapping) +- [Client](#client) + - [Interface](#interface) + - [NewClient function](#newclient-function) + - [NewClientWithOptions function](#newclientwithoptions-function) + - [GetWorkflow method](#getworkflow-method) + - [Query method](#query-method) + - [Signal method](#signal-method) + - [SignalWithStartWorkflow method](#signalwithstartworkflow-method) + - [SignalWithStartWorkflow method (asynchronous)](#signalwithstartworkflow-method-asynchronous) + - [Update method](#update-method) + - [Update method (asynchronous)](#update-method-asynchronous) + - [Workflow method](#workflow-method) + - [Workflow method (asynchronous)](#workflow-method-asynchronous) + - [UpdateHandle interface](#updatehandle-interface) + - [Get method](#get-method) + - [RunID method](#runid-method) + - [UpdateID method](#updateid-method) + - [WorkflowID method](#workflowid-method) + - [WorkflowOptions struct](#workflowoptions-struct) + - [NewWorkflowOptions function](#newworkflowoptions-function) + - [WithStartWorkflowOptions method](#withstartworkflowoptions-method) + - [WorkflowRun interface](#workflowrun-interface) + - [Cancel method](#cancel-method) + - [Get method](#get-method-1) + - [ID method](#id-method) + - [Query method](#query-method-1) + - [RunID method](#runid-method-1) + - [Signal method](#signal-method-1) + - [Terminate method](#terminate-method) + - [Update method](#update-method-1) + - [Update method (asynchronous)](#update-method-asynchronous-1) +- [Worker](#worker) + - [Activities interface](#activities-interface) + - [RegisterActivities function](#registeractivities-function) + - [RegisterActivity function](#registeractivity-function) + - [Activity function](#activity-function) + - [ActivityAsync function](#activityasync-function) + - [ActivityLocal function](#activitylocal-function) + - [ActivityLocalAsync function](#activitylocalasync-function) + - [ActivityFuture struct](#activityfuture-struct) + - [Get method](#get-method-2) + - [Select method](#select-method) + - [ActivityOptions struct](#activityoptions-struct) + - [NewActivityOptions function](#newactivityoptions-function) + - [WithActivityOptions method](#withactivityoptions-method) + - [LocalActivityOptions struct](#localactivityoptions-struct) + - [Local method](#local-method) + - [NewLocalActivityOptions function](#newlocalactivityoptions-function) + - [WithLocalActivityOptions method](#withlocalactivityoptions-method) + - [Signal struct](#signal-struct) + - [Receive method](#receive-method) + - [ReceiveAsync method](#receiveasync-method) + - [Select method](#select-method-1) + - [SignalExternal function](#signalexternal-function) + - [SignalExternalAsync function](#signalexternalasync-function) + - [Workflows interface](#workflows-interface) + - [RegisterWorkflows function](#registerworkflows-function) + - [RegisterWorkflow function](#registerworkflow-function) + - [Workflow interface](#workflow-interface) + - [WorkflowChild function](#workflowchild-function) + - [WorkflowChildAsync function](#workflowchildasync-function) + - [WorkflowChildOptions struct](#workflowchildoptions-struct) + - [NewWorkflowChildOptions function](#newworkflowchildoptions-function) + - [WithChildWorkflowOptions method](#withchildworkflowoptions-method) + - [WorkflowInput struct](#workflowinput-struct) + - [WorkflowChildRun struct](#workflowchildrun-struct) + - [Get method](#get-method-3) + - [Select method](#select-method-2) + - [SelectStart method](#selectstart-method) + - [Signal method](#signal-method-2) + - [SignalAsync method](#signalasync-method) + - [WaitStart method](#waitstart-method) + +# Constants & Variables + +## ActivityName + +```go +const ActivityName string +``` + +String constants defining the canonical name for each activity + +[top](#generated-code-reference) + +## QueryName + +```go +const QueryName string +``` + +String constants defining the canonical name for each query + +[top](#generated-code-reference) + +## SignalName + +```go +const SignalName string +``` + +String constants defining the canonical name for each signal + +[top](#generated-code-reference) + +## TaskQueue + +```go +const TaskQueue string +``` + +String constants defining the default task queue name for each service that defines the `task_queue` option + +[top](#generated-code-reference) + +## UpdateIDExpression + +```go +var IDExpression *expression.Expression +``` + +Expression variable referencing the parsed [ID expression](../README.md#id-expressions) for each update that defines the `id` option + +[top](#generated-code-reference) + +## UpdateName + +```go +const UpdateName string +``` + +String constants defining the canonical name for each update + +[top](#generated-code-reference) + +## WorkflowIDExpression + +```go +var IDExpression *expression.Expression +``` + +Expression variable referencing the parsed [ID expression](../README.md#id-expressions) for each workflow that defines the `id` option + +[top](#generated-code-reference) + +## WorkflowName + +```go +const WorkflowName string +``` + +String constant defining the canonical name for each workflow + +[top](#generated-code-reference) + +## WorkflowSearchAttributesMapping + +```go +var SearchAttributesMapping *expression.Expression +``` + +Expression variable referencing the parsed search attributes expression for each workflow that defines the `search_attributes` option + +[top](#generated-code-reference) + + + +# Client + +## Interface + +```go +type Client interface {} +``` + +Interface describing the generated client for each service. A generated client provides typed methods for executing a given service's workflows, queries, signals, and updates. + +**Example** +```protobuf +service Example { + option (temporal.v1.service) = { + task_queue: 'example-v1' + }; + + rpc Hello(HelloRequest) returns (HelloResponse) { + option (temporal.v1.workflow) = { + id: 'hello/${!uuid_v4()}' + execution_timeout: { seconds: 5 } + }; + } +} +``` + +```go +type ExampleClient interface { + Hello(context.Context, *HelloRequest, ...*HelloOptions) (*HelloResponse, error) +} +``` + +[top](#generated-code-reference) + +--- + +### NewClient function + +```go +func NewClient(client.Client) Client +``` + +Constructor function that returns a new [client interface](#interface) implementation for the underlying Temporal client + +**Example** +```protobuf +service Example { + option (temporal.v1.service) = { + task_queue: 'example-v1' + }; + + rpc Hello(HelloRequest) returns (HelloResponse) { + option (temporal.v1.workflow) = { + id: 'hello/${!uuid_v4()}' + execution_timeout: { seconds: 5 } + }; + } +} +``` + +```go +func main() { + c, _ := client.Dial(client.Options{}) + example := examplev1.NewExampleClient(c) + resp, _ := example.Hello(context.Background(), &examplev1.HelloRequest{}) + log.Printf("hello workflow response: %s", resp.String()) +} +``` + +[top](#generated-code-reference) + +--- + +### NewClientWithOptions function + +```go +func NewClientWithOptions(client.Client, client.Options) (Client, error) +``` + +Constructor function that returns a new [client interface](#interface) implementation for the underlying Temporal client and provided client options. + +[top](#generated-code-reference) + +--- + +### GetWorkflow method + +```go +func (Client) WithAsync( + ctx context.Context, + workflowID string, + runID string, +) (Run, error) +``` + +Returns a [WorkflowRun](#workflowrun-interface) for an existing workflow execution. If an empty string (`""`) is provided for `runID`, the latest workflow execution will be used. + +**Example** +```protobuf +service Example { + rpc Foo(FooRequest) returns (FooResponse) { + option (temporal.v1.workflow) = {}; + } +} +``` + +```go +type ExampleClient interface { + GetFoo(ctx context.Context, workflowID, runID string) (FooRun, error) +} +``` + +[top](#generated-code-reference) + +--- + +### Query method + +```go +func (Client) ( + ctx context.Context, + workflowId string, + runId string, + [req *Request], +) ([*Response], error) +``` + +Executes the corresponding query on an existing workflow execution using the configured default options. Passing an empty string as the `runID` will target the *latest* workflow execution with `workflowID`. + +**Example** +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (FooResponse) { + option (temporal.v1.query) = {}; + } + + rpc Bar(BarRequest) returns (BarResponse) { + option (temporal.v1.query) = {}; + } +} +``` + +```go +type ExampleClient interface { + Foo(ctx context.Context, workflowID, runID string) error + Bar(ctx context.Context, workflowID, runID string, req *BarRequest) (*BarResponse, error) +} +``` + +[top](#generated-code-reference) + +--- + +### Signal method + +```go +func (Client) ( + ctx context.Context, + workflowID string, + runID string, + [req *Request], +) error +``` + +Executes the corresponding signal on an existing workflow execution using the configured default options + +**Example** +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.signal) = {}; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.signal) = {}; + } +} +``` + +```go +type ExampleClient interface { + Foo(ctx context.Context, workflowID, runID string) error + Bar(ctx context.Context, workflowID, runID string, req *BarRequest) error +} +``` + +[top](#generated-code-reference) + +--- + +### SignalWithStartWorkflow method + +```go +func (Client) With( + ctx context.Context, + [req *Request], + [signal *Request], + opts ...*Options, +) ([*Response], error) +``` + +Executes the corresponding signal against an existing workflow execution using the configured default options, starting it if necessary, and blocking until the workflow completes or errors + +**Example** +```protobuf +service Example { + rpc Foo(FooRequest) returns (FooResponse) { + option (temporal.v1.workflow) = { + signal: { ref: 'Bar', start: true } + }; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.signal) = {}; + } +} +``` + +```go +type ExampleClient interface { + FooWithBar( + ctx context.Context, + req *FooRequest, + signal *BarRequest, + opts ...*FooOptions, + ) (*FooResponse, error) +} +``` + +[top](#generated-code-reference) + +--- + +### SignalWithStartWorkflow method (asynchronous) + +```go +func (Client) WithAsync( + ctx context.Context, + [req *Request], + [signal *Request], + opts ...*Options, +) (Run, error) +``` + +Executes the corresponding signal against an existing workflow execution using the configured default options, starting it if necessary, and returning a [WorkflowRun](#workflowrun-interface) for the workflow execution + +**Example** +```protobuf +service Example { + rpc Foo(FooRequest) returns (FooResponse) { + option (temporal.v1.workflow) = { + signal: { ref: 'Bar', start: true } + }; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.signal) = {}; + } +} +``` + +```go +type ExampleClient interface { + FooWithBarAsync( + ctx context.Context, + req *FooRequest, + signal *BarRequest, + opts ...*FooOptions, + ) (FooRun, error) +} +``` + +[top](#generated-code-reference) + +--- + +### Update method + +```go +func (Client) ( + ctx context.Context, + workflowID string, + runID string, + [req *Request], + opts ...*Options, +) ([*Response], error) +``` + +Executes the corresponding update on an existing workflow execution using the configured default options, blocking until update completes or errors + +**Example** +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.update) = {}; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.update) = {}; + } + + rpc Baz(google.protobuf.Empty) returns (BazResponse) { + option (temporal.v1.update) = {}; + } + + rpc Qux(QuxRequest) returns (QuxResponse) { + option (temporal.v1.update) = {}; + } +} +``` + +```go +type ExampleClient interface { + Foo(ctx context.Context, workflowID, runID string, opts ...*FooOptions) error + Bar(ctx context.Context, workflowID, runID string, req *BarRequest, opts ...*BarOptions) error + Baz(ctx context.Context, workflowID, runID string, opts ...*BazOptions) (*BazResponse, error) + Qux(ctx context.Context, workflowID, runID string, req *QuxRequest, opts ...*QuxOptions) (*QuxResponse, error) +} +``` + +[top](#generated-code-reference) + +--- + +### Update method (asynchronous) + +```go +func (Client) Async( + ctx context.Context, + workflowID string, + runID string, + [req *Request], + opts ...*Options, +) (Handle, error) +``` + +Executes the corresponding update on an existing workflow execution using the configured default options, returning an [UpdateHandle](#updatehandle-interface) for the update execution + +**Example** +```protobuf +service Example { + rpc Foo(FooRequest) returns (FooResponse) { + option (temporal.v1.update) = {}; + } +} +``` + +```go +type ExampleClient interface { + FooAsync(ctx context.Context, workflowID, runID string, req *FooRequest, opts ...*FooOptions) (FooHandle, error) +} +``` + +[top](#generated-code-reference) + +--- + +### Workflow method + +```go +func (Client) ( + ctx context.Context, + [req *Request], + opts ...*Options, +) ([*Response], error) +``` + +Executes the corresponding workflow using the configured default options, blocking until workflow completes or errors + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Baz(google.protobuf.Empty) returns (BazResponse) { + option (temporal.v1.workflow) = {}; + } + + rpc Qux(QuxRequest) returns (QuxResponse) { + option (temporal.v1.workflow) = {}; + } +} +``` + +```go +type ExampleClient interface { + Foo(ctx context.Context, opts ...*FooOptions) error + Bar(ctx context.Context, req *BarRequest, opts ...*BarOptions) error + Baz(ctx context.Context, opts ...*BazOptions) (*BazResponse, error) + Qux(ctx context.Context, req *QuxRequest, opts ...*QuxOptions) (*QuxResponse, error) +} +``` + +[top](#generated-code-reference) + +--- + +### Workflow method (asynchronous) + +```go +func (Client) Async( + ctx context.Context, + [req *Request], + opts ...*Options, +) (Run, error) +``` + +Executes the corresponding workflow using the configured default options, returning a [WorkflowRun](#workflowrun-interface) for the workflow execution + +**Example** +```protobuf +service Example { + rpc Foo(FooRequest) returns (FooResponse) { + option (temporal.v1.workflow) = {}; + } +} +``` + +```go +type ExampleClient interface { + FooAsync(ctx context.Context, workflowID, runID string, req *FooRequest, opts ...*FooOptions) (FooRun, error) +} +``` + +[top](#generated-code-reference) + + + +## UpdateHandle interface + +```go +type Handle interface {} +``` + +Interface describing an update execution handle returned by asynchronous update methods + +[top](#generated-code-reference) + +--- + +### Get method + +```go +func (Handle) Get(ctx context.Context) ([*Response], error) +``` +Returns the update result, blocking until update completes or errors + +[top](#generated-code-reference) + +--- + +### RunID method + +```go +func (Handle) RunID() string +``` + +Returns the workflow execution ID + +[top](#generated-code-reference) + +--- + +### UpdateID method + +```go +func (Handle) UpdateID() string +``` + +Returns the update ID + +[top](#generated-code-reference) + +--- + +### WorkflowID method + +```go +func (Handle) WorkflowID() string +``` + +Returns the workflow ID + +[top](#generated-code-reference) + + + +## WorkflowOptions struct + +```go +type Options struct {} +``` + +Optional configuration for workfow methods + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = { + execution_timeout: { seconds: 60 } + }; + } +} +``` + +```go +func example(ctx context.Context, example examplev1.ExampleClient) error { + return example.Foo(ctx, examplev1.NewFooOptions(). + WithStartWorkflowOptions(client.StartWorkflowOptions{ + ExecutionTimeout: time.Seconds*30 + }), + ) +} +``` + +[top](#generated-code-reference) + +--- + +### NewWorkflowOptions function + +```go +func NewOptions() *Options +``` + +Returns a new workflow options value for the corresponding workflow + +[top](#generated-code-reference) + +--- + +### WithStartWorkflowOptions method + +```go +func (*Options) WithStartWorkflowOptions(client.StartWorkflowOptions) *Options +``` + +Sets dynamic workflow options for an individual workflow execution + +[top](#generated-code-reference) + + + +## WorkflowRun interface + +```go +type Run interface {} +``` + +Interface describing a workflow execution handle returned by asynchronous workflow methods + +[top](#generated-code-reference) + +--- + +### Cancel method + +```go +type (Run) Cancel(context.Context) error +``` + +Cancels the workflow execution + +[top](#generated-code-reference) + +--- + +### Get method + +```go +type (Run) Get(context.Context) ([*Response], error) +``` + +Returns the workflow result, blocking until workflow completes or errors + +[top](#generated-code-reference) + +--- + +### ID method + +```go +type (Run) ID() string +``` + +Returns the workflow ID + +[top](#generated-code-reference) + +--- + +### Query method + +```go +type (Run) (context.Context, [*Request]) ([*Response], error) +``` + +Executes the corresponding query against the workflow execution using the configured default options + +[top](#generated-code-reference) + +--- + +### RunID method + +```go +type (Run) RunID() string +``` + +Returns the workflow execution ID + +[top](#generated-code-reference) + +--- + +### Signal method + +```go +type (Run) (context.Context, [*Request]) error +``` + +Executes the corresponding signal against the workflow execution using the configured default options + +[top](#generated-code-reference) + +--- + +### Terminate method + +```go +type (Run) Terminate( + ctx context.Context, + reason string, + details ...any, +) error +``` + +Terminates the workflow execution + +[top](#generated-code-reference) + +--- + +### Update method + +```go +type (Run) ( + context.Context, + [*Request], + ...*Options, +) ([*Response], error) +``` + +Executes the corresponding update against the workflow execution using the configured default options, blocking until the update completes or errors + +[top](#generated-code-reference) + +--- + +### Update method (asynchronous) + +```go +type (Run) ( + context.Context, + [*Request], + ...*Options, +) (Handle, error) +``` + +Executes the corresponding query against the workflow execution using the configured default options, returning an [UpdateHandle](#updatehandle-interface) for the update execution + +[top](#generated-code-reference) + +# Worker + +## Activities interface + +```go +type Activities interface {} +``` + +Interface used to describe the required Activities struct implementation + +**Example** +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.activity) = {}; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.activity) = {}; + } + + rpc Baz(google.protobuf.Empty) returns (BazResponse) { + option (temporal.v1.activity) = {}; + } + + rpc Qux(QuxRequest) returns (QuxResponse) { + option (temporal.v1.activity) = {}; + } +} +``` + +```go +type ExampleActivities interface { + Foo(context.Context) error + Bar(context.Context, *BarRequest) error + Baz(context.Context) (*BazResponse, error) + Qux(context.Context, *QuxRequest) (*QuxResponse, error) +} +``` + +[top](#generated-code-reference) + +## RegisterActivities function + +```go +func RegisterActivities(worker.ActivityRegistry, Activities) +``` + +Registers all service activities with the provided registry + +[top](#generated-code-reference) + +## RegisterActivity function + +```go +func RegisterActivity( + worker.ActivityRegistry, + func(context.Context, [*Request]) ([*Response], error), +) +``` + +Registers the activity with the provided registry + +[top](#generated-code-reference) + +## Activity function + +```go +func ( + workflow.Context, + [*Request], + ...*ActivityOptions, +) ([*Response], error) +``` + +Executes the corresponding activity, blocking until activity completes or errors + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Bar(BarRequest) returns (BarResponse) { + option (temporal.v1.activity) = {}; + } +} +``` + +```go +type ( + Activities struct {} + + FooWorkflow struct { + *examplev1.FooInput + } +) + +func (a *Activities) Bar(ctx context.Context, req *BarRequest) (*BarResponse, error) { + return nil, nil +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + bar, err := examplev1.Bar(ctx, &examplev1.BarRequest{}) + workflow.GetLogger(ctx).Info("executed bar activity", "result", bar) + return err +} +``` + +[top](#generated-code-reference) + +## ActivityAsync function + +```go +func Async( + workflow.Context, + [*Request], + ... *ActivityOptions, +) (Future, error) +``` + +Executes the corresponding activity, returning an [ActivityFuture](#activityfuture-interface) for the activity execution + +[top](#generated-code-reference) + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Bar(BarRequest) returns (BarResponse) { + option (temporal.v1.activity) = {}; + } +} +``` + +```go +type ( + Activities struct {} + + FooWorkflow struct { + *examplev1.FooInput + } +) + +func (a *Activities) Bar(ctx context.Context, req *BarRequest) (*BarResponse, error) { + return nil, nil +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + f, err := examplev1.BarAsync(ctx, &examplev1.BarRequest{}) + if err != nil { + return fmt.Errorf("error starting bar activity: %w", err) + } + bar, err := f.Get(ctx) + workflow.GetLogger(ctx).Info("executed bar activity", "result", bar) + return err +} +``` + +[top](#generated-code-reference) + +## ActivityLocal function + +```go +func Local( + workflow.Context, + [*Request], + ... *ActivityLocalOptions, +) ([*Response], error) +``` + +Executes the corresponding activity as a [local activity](https://docs.temporal.io/activities#local-activity), blocking until local activity completes or errors + +[top](#generated-code-reference) + +## ActivityLocalAsync function + +```go +func LocalAsync( + workflow.Context, + [*Request], + ... *ActivityLocalOptions, +) (Future, error) +``` + +Executes the corresponding activity as a [local activity](https://docs.temporal.io/activities#local-activity), returning an [ActivityFuture](#activityfuture-interface) for the local activity execution + +[top](#generated-code-reference) + + + +## ActivityFuture struct + +```go +type Future struct { + Future workflow.Future +} +``` + +Struct providing an interface execution handle returned by asynchronous activity methods + +[top](#generated-code-reference) + +--- + +### Get method + +```go +func (*Future) Get(context.Context) ([*Response], error) +``` + +Returns the activity result, blocking until activity completes or errors + +[top](#generated-code-reference) + +--- + +### Select method + +```go +func (*Future) Select(workflow.Selector, func(Future)) workflow.Selector +``` + +Registers the activity execution callback with the given selector + +[top](#generated-code-reference) + +## ActivityOptions struct + +```go +type ActivityOptions struct {} +``` + +Optional configuration for activity methods + +[top](#generated-code-reference) + +--- + +### NewActivityOptions function + +```go +func NewActivityOptions() *ActivityOptions +``` + +Returns a new activity options value + +[top](#generated-code-reference) + +--- + +### WithActivityOptions method + +```go +func (*ActivityOptions) WithActivityOptions(workflow.ActivityOptions) *ActivityOptions +``` + +Sets dynamic activity options for an individual activity execution + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Bar(BarRequest) returns (BarResponse) { + option (temporal.v1.activity) = {}; + } +} +``` + +```go +type ( + Activities struct {} + + FooWorkflow struct { + *examplev1.FooInput + } +) + +func (a *Activities) Bar(ctx context.Context, req *BarRequest) (*BarResponse, error) { + return nil, nil +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + opts := workflow.GetActivityOptions(ctx) + opts.StartToCloseTimeout = time.Second*30 + bar, err := examplev1.Bar( + ctx, + &examplev1.BarRequest{}, + examplev1.NewBarActivityOptions(). + WithActivityOptions(opts), + ) + workflow.GetLogger(ctx).Info("executed bar activity", "result", bar) + return err +} +``` + +[top](#generated-code-reference) + + + +## LocalActivityOptions struct + +```go +type LocalActivityOptions struct {} +``` + +Optional configuration for local activity methods + +[top](#generated-code-reference) + +--- + +### Local method + +```go +func (*LocalActivityOptions) Local( + func(context.Context, [*Request]) ([*Response], error) +) *LocalActivityOptions +``` + +Sets the activity definition to use for the local execution + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Bar(BarRequest) returns (BarResponse) { + option (temporal.v1.activity) = {}; + } +} +``` + +```go +type ( + FooWorkflow struct { + *examplev1.FooInput + } +) + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + bar, err := examplev1.BarLocal( + ctx, + &examplev1.BarRequest{}, + examplev1.NewBarActivityOptions(). + Local(func(ctx context.Context, req *BarRequest) (*BarResponse, error) { + return nil, nil + }), + ) + workflow.GetLogger(ctx).Info("executed local bar activity", "result", bar) + return err +} +``` + +[top](#generated-code-reference) + +--- + +### NewLocalActivityOptions function + +```go +func NewLocalActivityOptions() *LocalActivityOptions +``` + +Returns a new activity local options value + +[top](#generated-code-reference) + +--- + +### WithLocalActivityOptions method + +```go +func (*LocalActivityOptions) WithLocalActivityOptions(workflow.LocalActivityOptions) *LocalActivityOptions +``` + +Sets dynamic activity options for an individual local activity execution + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Bar(BarRequest) returns (BarResponse) { + option (temporal.v1.activity) = {}; + } +} +``` + +```go +type ( + Activities struct {} + + FooWorkflow struct { + *examplev1.FooInput + } +) + +func (a *Activities) Bar(ctx context.Context, req *BarRequest) (*BarResponse, error) { + return nil, nil +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + opts := workflow.GetLocalActivityOptions(ctx) + opts.StartToCloseTimeout = time.Second*30 + bar, err := examplev1.BarLocal( + ctx, + &examplev1.BarRequest{}, + examplev1.NewBarActivityOptions(). + WithLocalActivityOptions(opts), + ) + workflow.GetLogger(ctx).Info("executed local bar activity", "result", bar) + return err +} +``` + +[top](#generated-code-reference) + + + +## Signal struct + +```go +type Signal struct { + Channel workflow.ReceiveChannel +} +``` + +Struct providing types and methods to simplify interacting with the corresponding signal from a workflow definition + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = { + signal: { ref: 'Bar' } + }; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.signal) = {}; + } +} +``` + +```go +type ( + Workflows struct{} + + FooWorkflow struct { + *examplev1.FooInput + } +) + +func (wfs *Workflows) Foo(ctx workflow.Context, input *examplev1.FooInput) (examplev1.FooWorkflow, error) { + return &FooWorkflow{input}, nil +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + workflow.NewSelector(ctx). + AddReceive(w.Bar.Channel, func(workflow.ReceiveChannel, bool) { + bar := w.Bar.ReceiveAsync() + workflow.GetLogger(ctx).Info("received bar signal", "signal", bar) + }). + Select(ctx) + return nil +} +``` + +[top](#generated-code-reference) + +--- + +### Receive method + +```go +func (*Signal) Receive(workflow.Context) ([*Request], bool) +``` + +Returns the next signal request and boolean indicating whether the channel is closed, blocking until the signal is received. + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = { + signal: { ref: 'Bar' } + }; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.signal) = {}; + } +} +``` + +```go +type ( + Workflows struct{} + + FooWorkflow struct { + *examplev1.FooInput + } +) + +func (wfs *Workflows) Foo(ctx workflow.Context, input *examplev1.FooInput) (examplev1.FooWorkflow, error) { + return &FooWorkflow{input}, nil +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + bar, _ := w.Bar.Receive(ctx) + workflow.GetLogger(ctx).Info("received bar signal", "signal", bar) + return nil +} +``` + +[top](#generated-code-reference) + +--- + +### ReceiveAsync method + +```go +func (*Signal) ReceiveAsync() (*Request | bool) +``` + +Returns the next signal request if available (bool if signal has no request payload), or nil otherwise. + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = { + signal: { ref: 'Bar', start: true } + }; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.signal) = {}; + } +} +``` + +```go +type ( + Workflows struct{} + + FooWorkflow struct { + *examplev1.FooInput + } +) + +func (wfs *Workflows) Foo(ctx workflow.Context, input *examplev1.FooInput) (examplev1.FooWorkflow, error) { + return &FooWorkflow{input}, nil +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + bar := w.Bar.ReceiveAsync() + if bar != nil { + workflow.GetLogger(ctx).Info("workflow started with bar signal", "signal", bar) + } + return nil +} +``` + +[top](#generated-code-reference) + +--- + +### Select method + +```go +func (*Signal) Select( + workflow.Selector, + func([*Request]), +) workflow.Selector +``` + +Registers the provided signal callback with the provided selector + +[top](#generated-code-reference) + + + +## SignalExternal function + +```go +func External( + ctx workflow.Context, + workflowID string, + runID string, + signal [*Request], +) error +``` + +Sends the corresponding signal to an existing workflow execution. + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = { + signal: { ref: 'Baz' } + }; + } + + rpc Baz(BazRequest) returns (google.protobuf.Empty) { + option (temporal.v1.signal) = {}; + } +} +``` + +```go +type ( + FooWorkflow struct { + *examplev1.FooInput + } + + BarWorkflow struct { + *examplev1.BarInput + } +) + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + return examplev1.BazExternal(ctx, "barID", "", &examplev1.BazRequest{}) +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + baz, _ := w.Baz.Receive(ctx) + workflow.GetLogger(ctx).Info("received baz signal", "signal", baz) + return nil +} +``` + +[top](#generated-code-reference) + + + +## SignalExternalAsync function + +```go +func ExternalAsync( + ctx workflow.Context, + workflowID string, + runID string, + signal [*Request], +) workflow.Future +``` + +Sends the corresponding signal to an existing workflow execution, returning a workflow future. + +[top](#generated-code-reference) + + + +## Workflows interface + +```go +type Workflows interface {} +``` + +Interface used to describe the required Workflows struct implementation + +**Example** +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } +} +``` + +```go +type ExampleWorkflows interface { + Foo(context.Context, *examplev1.FooInput) (examplev1.FooWorkflow, error) +} +``` + +[top](#generated-code-reference) + + + +## RegisterWorkflows function + +```go +func RegisterWorkflows(worker.WorkflowRegistry, examplev1.Workflows) +``` + +Registers all service workflows with the provided registry + +[top](#generated-code-reference) + + + +## RegisterWorkflow function + +```go +func RegisterWorkflow( + worker.WorkflowRegistry, + func(workflow.Context, *examplev1.Input) (examplev1.Workflow, error) +) +``` + +Registers the workflow with the provided registry + +[top](#generated-code-reference) + + + +## Workflow interface + +```go +type Workflow { + Execute(workflow.Context) ([*Response], error) + ([*Request]) (*Response, error) + ([*Request]) ([*Response], error) + Validate([*Request]) error +} +``` + +Interface used to describe a required Workflow struct implementation + +**Example** + +```protobuf +service Example { + rpc Foo(FooRequest) returns (FooResponse) { + option (temporal.v1.workflow) = { + query: { ref: 'QueryFoo' } + update: { ref: 'UpdateFoo' } + }; + } + + rpc QueryFoo(QueryFooRequest) returns (QueryFooResponse) { + option (temporal.v1.query) = {}; + } + + rpc UpdateFoo(UpdateFooRequest) returns (UpdateFooResponse) { + option (temporal.v1.update) = { + validate: true + }; + } +} +``` + +```go +type FooWorkflow struct { + *examplev1.FooInput +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) (*examplev1.FooResponse, error) { + return &examplev1.FooResponse{}, nil +} + +func (w *FooWorkflow) QueryFoo(req *examplev1.QueryFooRequest) (*examplev1.QueryFooResponse, error) { + return &examplev1.QueryFooResponse{}, nil +} + +func (w *FooWorkflow) UpdateFoo(ctx workflow.Context, req *examplev1.UpdateFooRequest) (*examplev1.UpdateFooResponse, error) { + return &examplev1.UpdateFooResponse{}, nil +} + +func (w *FooWorkflow) UpdateFoo(ctx workflow.Context, req *examplev1.UpdateFooRequest) error { + return nil +} +``` + +[top](#generated-code-reference) + + + +## WorkflowChild function + +```go +func Child( + workflow.Context, + [*Request], + ...*ChildOptions, +) ([*Response], error) +``` + +Executes the corresponding child workflow, blocking until child workflow completes or errors + +**Example** + +```protobuf +service Example { + rpc Foo(google.protobuf.Empty) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Bar(BarRequest) returns (BarResponse) { + option (temporal.v1.workflow) = {}; + } +} +``` + +```go +type ( + FooWorkflow struct { + *examplev1.FooInput + } + + BarWorkflow struct { + *examplev1.BarInput + } +) + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + bar, err := examplev1.BarChild(ctx, &examplev1.BarRequest{}) + workflow.GetLogger(ctx).Info("executed bar child workflow", "response", bar) + return err +} + +func (w *BarWorkflow) Execute(ctx workflow.Context) (*examplev1.BarResponse, error) { + return &examplev1.BarResponse{}, nil +} +``` + +[top](#generated-code-reference) + + + +## WorkflowChildAsync function + +```go +func Child( + workflow.Context, + [*Request], + ...*ChildOptions, +) ([*ChildRun], error) +``` + +Executes the corresponding child workflow, returning a [WorkflowChildRun](#workflowchildrun-struct) for the child workflow execution + +[top](#generated-code-reference) + + + +## WorkflowChildOptions struct + +```go +type ChildOptions struct {} +``` + +Optional configuration for child workfow functions + +[top](#generated-code-reference) + +--- + +### NewWorkflowChildOptions function + +```go +func NewChildOptions() *ChildOptions +``` + +Returns a new workflow child options value for the corresponding workflow + +[top](#generated-code-reference) + +--- + +### WithChildWorkflowOptions method + +```go +func (*Options) WithChildWorkflowOptions(workflow.ChildWorkflowOptions) *ChildOptions +``` + +Sets dynamic workflow options for an individual workflow execution + +[top](#generated-code-reference) + + + +## WorkflowInput struct + +```go +type Input struct { + [Req *Request] + [ *Signal] +} +``` + +Struct that contains references to workflow inputs and signals + +**Example** + +```protobuf +service Example { + rpc Foo(FooRequest) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = { + signal: { ref: 'Bar' } + signal: { ref: 'Baz' } + }; + } + + rpc Bar(BarRequest) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } + + rpc Baz(BazRequest) returns (google.protobuf.Empty) { + option (temporal.v1.workflow) = {}; + } +} +``` + +```go +type ( + Workflows struct {} + + FooWorkflow struct { + *examplev1.FooInput + log log.Logger + } +) + +func (w *Workflows) Foo(ctx workflow.Context, input *examplev1.FooInput) (examplev1.FooWorkflow, error) { + return &FooWorkflow{input, workflow.GetLogger(ctx)}, nil +} + +func (w *FooWorkflow) Execute(ctx workflow.Context) error { + w.log.Info("starting foo workflow", "request", w.Req) + for bar, baz := 0, 0; bar + baz < 2; { + sel := workflow.NewSelector(ctx) + if bar == 0 { + w.Bar.Select(ctx, func(signal *examplev1.BarRequest) { + w.log.Info("received bar signal", "signal", signal) + bar++ + }) + } + if baz == 0 { + w.Baz.Select(ctx, func(signal *examplev1.BazRequest) { + w.log.Info("received baz signal", "signal", signal) + baz++ + }) + } + sel.Select(ctx) + } + return nil +} +``` + +[top](#generated-code-reference) + + + +## WorkflowChildRun struct + +```go +type ChildRun struct { + Future workflow.ChildWorkflowFuture +} +``` + +Struct providing a child workflow execution handle returned by asynchronous child workflow methods + +[top](#generated-code-reference) + +--- + +### Get method + +```go +func (*ChildRun) Get(workflow.Context) ([*Response], error) +``` + +Returns the child workflow result, blocking until child workflow completes or errors + +[top](#generated-code-reference) + +--- + +### Select method + +```go +func (*ChildRun) Select( + workflow.Selector, + func(*ChildRun) +) workflow.Selector +``` + +Registers the child workflow execution and a callback with the provided selector + +[top](#generated-code-reference) + +--- + +### SelectStart method + +```go +func (*ChildRun) Select( + workflow.Selector, + func(*ChildRun) +) workflow.Selector +``` + +Registers the start of the child workflow execution and a callback with the provided selector + +[top](#generated-code-reference) + +--- + +### Signal method + +```go +func (*ChildRun) (workflow.Context, [*Request]) error +``` + +Sends the corresponding signal to the child workflow execution + +[top](#generated-code-reference) + +--- + +### SignalAsync method + +```go +func (*ChildRun) (workflow.Context, [*Request]) workflow.Future +``` + +Sends the corresponding signal to the child workflow execution + +[top](#generated-code-reference) + +--- + +### WaitStart method + +```go +func (*ChildRun) WaitStart(workflow.Context) (*workflow.Execution, error) +``` + +Blocks until the child workflow execution has started + +[top](#generated-code-reference)