repository·main·Indexed 41 days ago
https://github.com/cludden/protoc-gen-go-temporalA protoc plugin that automates the generation of typed Temporal client and worker code in Go from protobuf definitions, reducing boilerplate and enforcing best practices.
protoc-gen-go-temporal is a protoc plugin designed to generate typed Temporal clients and workers in Go directly from protobuf schemas.
It is used to:
Beyond the core Client and Worker, the plugin can generate several specialized helpers:
protoc-gen-go-temporal plugin facilitates this by generating type-safe helper functions that wrap these cross-namespace operations as activities.The protoc-gen-go-temporal plugin generates Go code that maps Protobuf service definitions to Temporal primitives. The generated documentation organizes these mappings into several key categories:
This structure allows developers to define their Temporal orchestration logic using standard Protobuf service definitions, which are then compiled into type-safe Go interfaces for interacting with the Temporal cluster.
The plugin can optionally generate a CLI application for interacting with your workflows:
For atomic initialization, you can start remote workflows with an initial signal or update. This ensures the remote workflow begins its lifecycle with the necessary state already present.
// Signal with Start
run, err := examplev1xns.CreateFooWithSetFooProgressAsync(ctx,
&examplev1.CreateFooRequest{Name: "signal-start-foo"},
&examplev1.SetFooProgressRequest{Progress: 0.25},
)
// Update with Start
updateResult, run, err := examplev1xns.CreateFooWithUpdateFooProgress(ctx,
&examplev1.CreateFooRequest{Name: "update-start-foo"},
&examplev1.SetFooProgressRequest{Progress: 0.5},
)For every Activity defined in your Protobuf service, the generator produces a corresponding <Activity>Future struct. This struct wraps the underlying workflow.Future from the Temporal Go SDK and provides convenient methods for interacting with asynchronous activity executions. All asynchronous activity helpers (e.g., BarAsync) return this type.
// Example of an asynchronous activity helper returning a Future
barF, err := examplev1.BarAsync(ctx, &examplev1.BarInput{})A Duration represents a signed, fixed-length span of time using seconds and nanos (nanosecond resolution). It is independent of calendars and is used to represent the difference between two Timestamp values.
JSON Mapping:
In JSON, Duration is encoded as a string with an s suffix (e.g., "3s" or "3.000000001s").
The plugin generates several key components:
Provides methods for:
client.StartWorkflowOptions, client.UpdateWorkflowWithOptionsRequest, and more.Provides functions for:
workflow.ActivityOptions, workflow.ChildWorkflowOptions, timeouts, parent close policies, and retry policies.Provides commands for:
:::warning Update-with-start is considered experimental. :::
Update-with-start allows you to start a workflow and immediately apply an update atomically. This ensures the workflow starts with the desired state modification already applied.
To enable this, configure the Protobuf service definition using the (temporal.v1.workflow).update.start option. In Go, the generated client provides a method (e.g., CreateFooWithUpdateFooProgress) that returns both the result of the initial update and a handle to the workflow run.
// Protobuf configuration
service Example {
rpc CreateFoo(CreateFooRequest) returns (CreateFooResponse) {
option (temporal.v1.workflow) = {
update: { ref: "UpdateFooProgress", start: true }
};
}
rpc UpdateFooProgress(SetFooProgressRequest) returns (GetFooProgressResponse) {
option (temporal.v1.update) = {};
}
}// Go usage
updateResult, workflowRun, err := client.CreateFooWithUpdateFooProgress(ctx,
&examplev1.CreateFooRequest{Name: "test"},
&examplev1.SetFooProgressRequest{Progress: 50.0},
)
// Access workflow run
finalResult, err := workflowRun.Get(ctx)The Shopping Cart example demonstrates several advanced Temporal patterns implemented via the generated code:
Describe query to allow external inspection of the workflow's current state without modifying it.Checkout signal to trigger specific workflow transitions (like completion) asynchronously.UpdateCart pattern to modify state with built-in validation logic (e.g., preventing the removal of items that aren't in the cart).ContinueAsNew suggestions to prevent workflow history from exceeding size limits in long-running sessions.The plugin generates a TestClient that mirrors your production client interface but is designed to work within Temporal's testsuite.TestWorkflowEnvironment. This client allows you to interact with workflows, signals, queries, and updates in a deterministic test environment.
To initialize a test client, use the generated constructor (e.g., NewTestExampleClient) which requires:
*testsuite.TestWorkflowEnvironment.// Constructor for test client
func NewTestExampleClient(
env *testsuite.TestWorkflowEnvironment,
workflows ExampleWorkflows,
activities ExampleActivities,
) *TestExampleClient
// The client provides the same methods as the production client:
// - Workflow execution: CreateFoo, CreateFooAsync, GetCreateFoo
// - Signals: SetFooProgress
// - Queries: GetFooProgress
// - Updates: UpdateFooProgress