diff --git a/docs/develop/go/index.mdx b/docs/develop/go/index.mdx index 15723c7de2..f0152a6a28 100644 --- a/docs/develop/go/index.mdx +++ b/docs/develop/go/index.mdx @@ -96,6 +96,14 @@ Complete Activities asynchronously. - [How to asynchronously complete an Activity](/develop/go/asynchronous-activity-completion) +## [Standalone Activities](/develop/go/standalone-activities) + +Execute Activities independently without a Workflow using the Temporal Client. + +- [How to execute a Standalone Activity](/develop/go/standalone-activities#execute-activity) +- [How to get the result of a Standalone Activity](/develop/go/standalone-activities#get-activity-result) +- [How to get a handle to an existing Standalone Activity](/develop/go/standalone-activities#get-activity-handle) + ## [Versioning](/develop/go/versioning) Change Workflow Definitions without causing non-deterministic behavior in running Workflows. diff --git a/docs/develop/go/standalone-activities.mdx b/docs/develop/go/standalone-activities.mdx new file mode 100644 index 0000000000..f7872a201d --- /dev/null +++ b/docs/develop/go/standalone-activities.mdx @@ -0,0 +1,443 @@ +--- +id: standalone-activities +title: Standalone Activities - Go SDK +sidebar_label: Standalone Activities +toc_max_heading_level: 4 +keywords: + - standalone activity + - activity execution + - execute activity + - activity handle + - list activities + - count activities + - go sdk +tags: + - Activities + - Temporal Client + - Go SDK + - Temporal SDKs +description: Execute Activities independently without a Workflow using the Temporal Go SDK. +--- + +:::tip SUPPORT, STABILITY, and DEPENDENCY INFO + +Temporal Go SDK support for Standalone Activities is at +[Pre-release](/evaluate/development-production-features/release-stages#pre-release). + +All APIs are experimental and may be subject to backwards-incompatible changes. + +::: + +Standalone Activities are Activity Executions that run independently, without being orchestrated by a Workflow. Instead +of starting an Activity from within a Workflow Definition using `workflow.ExecuteActivity()`, you start a Standalone +Activity directly from a Temporal Client using `client.ExecuteActivity()`. + +The Activity definition and Worker registration are identical to regular Activities, and only the execution path +differs. + +This page covers the following: + +- [Run the Temporal Development Server with Standalone Activities enabled](#run-the-temporal-standalone-activity-development-server) +- [Define your Activity](#define-activity) +- [Run a Worker with the Activity registered](#run-worker) +- [Execute a Standalone Activity](#execute-activity) +- [Get the result of a Standalone Activity](#get-activity-result) +- [Get a handle to an existing Standalone Activity](#get-activity-handle) +- [List Standalone Activities](#list-activities) +- [Count Standalone Activities](#count-activities) +- [Run Standalone Activities with Temporal Cloud](#run-standalone-activities-temporal-cloud) + +:::note + +This documentation uses source code from the +[Go sample](https://github.com/temporalio/samples-go/tree/main/standalone-activity/helloworld). + +::: + +## Run the Temporal Development Server with Standalone Activities enabled {#run-the-temporal-standalone-activity-development-server} + +Prerequisites: + +- Install the latest Temporal CLI + + 🚧 Please build from development branch: https://github.com/temporalio/cli/tree/release/v1.6.x-standalone-activity +- [Install the latest Temporal Go SDK](https://docs.temporal.io/develop/go/core-application#install-a-temporal-sdk) + (v1.40.0 or higher recommended) + +The first step in running a Standalone Activity involves starting a Temporal server. + +``` +temporal server start-dev +``` + +This command automatically starts the Temporal development server with the Web UI, and creates the `default` Namespace. +It uses an in-memory database, so do not use it for real use cases. + +The Temporal Server should now be available for client connections on `localhost:7233`, and the +Temporal Web UI should now be accessible at [http://localhost:8233](http://localhost:8233). Standalone +Activities are available from the nav bar item located towards the top left of the page: + +Standalone Activities Web UI nav bar item + +Clone the [samples-go](https://github.com/temporalio/samples-go) repository to follow along: + +``` +git clone https://github.com/temporalio/samples-go.git +cd samples-go +``` + +## Define your Activity {#define-activity} + +Define your Activity in a shared file so that both the Worker and starter can reference it. + +The sample project is structured as follows: + +``` +standalone-activity/helloworld/ +├── activity.go +├── worker/ +│ └── main.go +└── starter/ + └── main.go +``` + +[standalone-activity/helloworld/activity.go](https://github.com/temporalio/samples-go/blob/main/standalone-activity/helloworld/activity.go) + +```go +package helloworld + +import ( + "context" + "go.temporal.io/sdk/activity" +) + +func Activity(ctx context.Context, name string) (string, error) { + logger := activity.GetLogger(ctx) + logger.Info("Activity", "name", name) + return "Hello " + name + "!", nil +} +``` + +## Run a Worker with the Activity registered {#run-worker} + +Running a Worker for Standalone Activities is the same as running a Worker for Workflow-driven Activities — you create a +Worker, register the Activity, and call `Run()`. The Worker doesn't need to know whether the Activity will be invoked +from a Workflow or as a Standalone Activity. + +See [How to develop a Worker in Go](/develop/go/core-application#develop-worker) for more details on Worker setup and +configuration options. + +[standalone-activity/helloworld/worker/main.go](https://github.com/temporalio/samples-go/blob/main/standalone-activity/helloworld/worker/main.go) + +```go +package main + +import ( + "github.com/temporalio/samples-go/standalone-activity/helloworld" + "go.temporal.io/sdk/client" + "go.temporal.io/sdk/contrib/envconfig" + "go.temporal.io/sdk/worker" + "log" +) + +func main() { + c, err := client.Dial(envconfig.MustLoadDefaultClientOptions()) + if err != nil { + log.Fatalln("Unable to create client", err) + } + defer c.Close() + + w := worker.New(c, "standalone-activity-helloworld", worker.Options{}) + + w.RegisterActivity(helloworld.Activity) + + err = w.Run(worker.InterruptCh()) + if err != nil { + log.Fatalln("Unable to start worker", err) + } +} +``` + +To run the Worker: + +``` +go run standalone-activity/helloworld/worker/main.go +``` + +## Execute a Standalone Activity {#execute-activity} + +Use [`client.ExecuteActivity()`](https://pkg.go.dev/go.temporal.io/sdk/client#Client) to start a Standalone Activity +Execution. This is called from application code (for example, a starter program), not from inside a Workflow Definition. + +`ExecuteActivity` returns an [`ActivityHandle`](https://pkg.go.dev/go.temporal.io/sdk/client#ActivityHandle) that you +can use to get the result, describe, cancel, or terminate the Activity. + +The following starter program demonstrates how to execute a Standalone Activity, get its result, list activities, and +count activities: + +[standalone-activity/helloworld/starter/main.go](https://github.com/temporalio/samples-go/blob/main/standalone-activity/helloworld/starter/main.go) + +```go +package main + +import ( + "context" + "github.com/temporalio/samples-go/standalone-activity/helloworld" + "go.temporal.io/sdk/client" + "go.temporal.io/sdk/contrib/envconfig" + "log" + "time" +) + +func main() { + c, err := client.Dial(envconfig.MustLoadDefaultClientOptions()) + if err != nil { + log.Fatalln("Unable to create client", err) + } + defer c.Close() + + activityOptions := client.StartActivityOptions{ + ID: "standalone_activity_helloworld_ActivityID", + TaskQueue: "standalone-activity-helloworld", + ScheduleToCloseTimeout: 10 * time.Second, + } + + handle, err := c.ExecuteActivity(context.Background(), activityOptions, helloworld.Activity, "Temporal") + if err != nil { + log.Fatalln("Unable to execute activity", err) + } + + log.Println("Started standalone activity", "ActivityID", handle.GetID(), "RunID", handle.GetRunID()) + + var result string + err = handle.Get(context.Background(), &result) + if err != nil { + log.Fatalln("Unable get standalone activity result", err) + } + log.Println("Activity result:", result) + + resp, err := c.ListActivities(context.Background(), client.ListActivitiesOptions{ + Query: "TaskQueue = 'standalone-activity-helloworld'", + }) + if err != nil { + log.Fatalln("Unable to list activities", err) + } + + log.Println("ListActivity results") + for info, err := range resp.Results { + if err != nil { + log.Fatalln("Error iterating activities", err) + } + log.Printf("\tActivityID: %s, Type: %s, Status: %v\n", + info.ActivityID, info.ActivityType, info.Status) + } + + resp1, err := c.CountActivities(context.Background(), client.CountActivitiesOptions{ + Query: "TaskQueue = 'standalone-activity-helloworld'", + }) + if err != nil { + log.Fatalln("Unable to count activities", err) + } + + log.Println("Total activities:", resp1.Count) +} +``` + +You can pass the Activity as either a function reference or a string Activity type name: + +```go +handle, err := c.ExecuteActivity(ctx, options, helloworld.Activity, "arg1") + +// Using a string type name +handle, err := c.ExecuteActivity(ctx, options, "Activity", "arg1") +``` + +`client.StartActivityOptions` requires `ID`, `TaskQueue`, and at least one of `ScheduleToCloseTimeout` or +`StartToCloseTimeout`. See [`StartActivityOptions`](https://pkg.go.dev/go.temporal.io/sdk/client#StartActivityOptions) +in the API reference for the full set of options. + +To run the starter (in a separate terminal from the Worker): + +``` +go run standalone-activity/helloworld/starter/main.go +``` + +## Get the result of a Standalone Activity {#get-activity-result} + +Use `ActivityHandle.Get()` to block until the Activity completes and retrieve its result. This is analogous to calling +`Get()` on a `WorkflowRun`. + +```go +var result string +err = handle.Get(context.Background(), &result) +if err != nil { + log.Fatalln("Activity failed", err) +} +log.Println("Activity result:", result) +``` + +If the Activity completed successfully, the result is deserialized into the provided pointer. If the Activity failed, +the failure is returned as an error. + +## Get a handle to an existing Standalone Activity {#get-activity-handle} + +Use `client.GetActivityHandle()` to create a handle to a previously started Standalone Activity. This is analogous to +`client.GetWorkflow()` for Workflow Executions. + +Both `ActivityID` and `RunID` are required. + +```go +handle := c.GetActivityHandle(client.GetActivityHandleOptions{ + ActivityID: "my-standalone-activity-id", + RunID: "the-run-id", +}) + +// Use the handle to get the result, describe, cancel, or terminate +var result string +err := handle.Get(context.Background(), &result) +if err != nil { + log.Fatalln("Unable to get activity result", err) +} +``` + +## List Standalone Activities {#list-activities} + +Use [`client.ListActivities()`](https://pkg.go.dev/go.temporal.io/sdk/client#Client) to list Standalone Activity +Executions that match a [List Filter](/list-filter) query. The result contains an iterator that yields +[`ActivityExecutionInfo`](https://pkg.go.dev/go.temporal.io/sdk/client#ActivityExecutionInfo) entries. + +```go +resp, err := c.ListActivities(context.Background(), client.ListActivitiesOptions{ + Query: "TaskQueue = 'standalone-activity-helloworld'", +}) +if err != nil { + log.Fatalln("Unable to list activities", err) +} + +for info, err := range resp.Results { + if err != nil { + log.Fatalln("Error iterating activities", err) + } + log.Printf("ActivityID: %s, Type: %s, Status: %v\n", + info.ActivityID, info.ActivityType, info.Status) +} +``` + +The `Query` field accepts the same [List Filter](/list-filter) syntax used for Workflow Visibility. For example, +`"ActivityType = 'Activity' AND Status = 'Running'"`. + +You can also list activities using the Temporal CLI: + +``` +temporal activity list +``` + +## Count Standalone Activities {#count-activities} + +Use [`client.CountActivities()`](https://pkg.go.dev/go.temporal.io/sdk/client#Client) to count Standalone Activity +Executions that match a [List Filter](/list-filter) query. + +```go +resp, err := c.CountActivities(context.Background(), client.CountActivitiesOptions{ + Query: "TaskQueue = 'standalone-activity-helloworld'", +}) +if err != nil { + log.Fatalln("Unable to count activities", err) +} + +log.Println("Total activities:", resp.Count) +``` + +## Run Standalone Activities with Temporal Cloud {#run-standalone-activities-temporal-cloud} + +This section assumes you are already familiar with +[how to connect a Worker to Temporal Cloud](https://docs.temporal.io/develop/go/core-application#run-a-temporal-cloud-worker). +The same [source code](https://github.com/temporalio/samples-go/tree/main/standalone-activity/helloworld) is used in +this section. The `tcld` CLI will be used to create a Namespace, and mTLS client certificates will be used to securely +connect the Worker to Temporal Cloud. + +### Install the latest `tcld` CLI and generate certificates + +To install the latest version of the `tcld` CLI, run the following command (on MacOS): + +``` +brew install temporalio/brew/tcld +``` + +If you don't already have certificates, you can generate them for mTLS Worker authentication using the command below: + +``` +tcld gen ca --org $YOUR_ORG_NAME --validity-period 1y --ca-cert ca.pem --ca-key ca.key +``` + +These certificates will be valid for one year. + +### Create your Namespace + +If you don't already have a Namespace, create one for your Standalone Activities: + +``` +tcld login + +tcld namespace create \ + --namespace \ + --cloud-provider aws \ + --region us-west-2 \ + --ca-certificate-file 'path/to/your/ca.pem' \ + --retention-days 1 +``` + +Alternatively, you can create a Namespace through the UI: +[https://cloud.temporal.io/namespaces](https://cloud.temporal.io/namespaces). + +### Run a Worker connected to Temporal Cloud with TLS certificates + +The sample uses [`envconfig.MustLoadDefaultClientOptions()`](https://pkg.go.dev/go.temporal.io/sdk/contrib/envconfig) to +read connection options from [environment variables](/references/client-environment-configuration). Set the following +environment variables before running the Worker: + +``` +export TEMPORAL_ADDRESS=.tmprl.cloud:7233 +export TEMPORAL_NAMESPACE= +export TEMPORAL_TLS_CLIENT_CERT_PATH='path/to/your/ca.pem' +export TEMPORAL_TLS_CLIENT_KEY_PATH='path/to/your/ca.key' +``` + +Then run the Worker: + +``` +go run standalone-activity/helloworld/worker/main.go +``` + +### Execute a Standalone Activity on Temporal Cloud + +In a separate terminal, set the same environment variables and run the starter: + +``` +export TEMPORAL_ADDRESS=.tmprl.cloud:7233 +export TEMPORAL_NAMESPACE= +export TEMPORAL_TLS_CLIENT_CERT_PATH='path/to/your/ca.pem' +export TEMPORAL_TLS_CLIENT_KEY_PATH='path/to/your/ca.key' + +go run standalone-activity/helloworld/starter/main.go +``` + +### Run a Worker connected to Temporal Cloud with API keys + +Alternatively, you can use an API key instead of TLS certificates: + +``` +export TEMPORAL_ADDRESS=..api.temporal.io:7233 +export TEMPORAL_NAMESPACE= +export TEMPORAL_API_KEY= +``` + +Then run the Worker and starter the same way: + +``` +go run standalone-activity/helloworld/worker/main.go +``` + +``` +go run standalone-activity/helloworld/starter/main.go +``` diff --git a/sidebars.js b/sidebars.js index 6fae131fb6..da79c9a4d1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -105,6 +105,7 @@ module.exports = { 'develop/go/message-passing', 'develop/go/cancellation', 'develop/go/asynchronous-activity-completion', + 'develop/go/standalone-activities', 'develop/go/versioning', 'develop/go/observability', 'develop/go/benign-exceptions', diff --git a/static/img/standalone-activities-ui-nav.png b/static/img/standalone-activities-ui-nav.png new file mode 100644 index 0000000000..733e4f6f2e Binary files /dev/null and b/static/img/standalone-activities-ui-nav.png differ