temporal

README

temporal

The temporal package provides a thin wrapper around the Temporal Go SDK for dialling a client and building activity options with sensible defaults. It is intended for services that use Temporal for workflow orchestration and want a consistent way to connect and configure activities without repeating the same boilerplate in every project.

Import

import "github.com/raykavin/gobox/temporal"

What it provides

• NewClient() for dialling a Temporal server with host, port, and namespace validation
• TemporalConfig for carrying connection parameters with Viper-compatible mapstructure tags
• DefaultActivityOpts() for building workflow.ActivityOptions with a sensible retry policy
• functional options for overriding specific activity fields: WithTaskQueue, WithStartToCloseTimeout, WithScheduleToCloseTimeout, WithMaximumAttempts, WithRetryPolicy

Main types

• TemporalConfig: connection settings (Host, Port, Namespace, TaskQueue)
• ActivityOption: func(*workflow.ActivityOptions) applied by DefaultActivityOpts

Connecting

package main

import (
    "log"

    "github.com/raykavin/gobox/temporal"
)

func main() {
    c, err := temporal.NewClient("default", "localhost", 7233)
    if err != nil {
        log.Fatal(err)
    }
    defer c.Close()

    // use c as a normal temporal client.Client
}

Activity options inside a workflow

import (
    "time"

    "github.com/raykavin/gobox/temporal"
    "go.temporal.io/sdk/workflow"
)

func MyWorkflow(ctx workflow.Context, input string) error {
    opts := temporal.DefaultActivityOpts(
        temporal.WithStartToCloseTimeout(30 * time.Minute),
        temporal.WithMaximumAttempts(5),
        temporal.WithTaskQueue("heavy-processing"),
    )
    ctx = workflow.WithActivityOptions(ctx, opts)

    var result string
    return workflow.ExecuteActivity(ctx, MyActivity, input).Get(ctx, &result)
}

Loading from config

TemporalConfig is designed to be populated from a YAML file via Viper:

temporal:
  host: localhost
  port: 7233
  namespace: default
  task_queue: my-service

var cfg temporal.TemporalConfig
if err := viper.UnmarshalKey("temporal", &cfg); err != nil {
    log.Fatal(err)
}

c, err := temporal.NewClient(cfg.Namespace, cfg.Host, cfg.Port)

Default activity options

Field	Default
StartToCloseTimeout	1h
RetryPolicy.InitialInterval	5s
RetryPolicy.MaximumInterval	1m
RetryPolicy.BackoffCoefficient	2.0
RetryPolicy.MaximumAttempts	3

Errors

Sentinel	Cause
ErrEmptyHost	host argument is empty
ErrEmptyNamespace	namespace argument is empty

Notes

• NewClient returns a client.Client from the Temporal SDK; the caller is responsible for calling Close() when done
• DefaultActivityOpts does not set ScheduleToCloseTimeout; use WithScheduleToCloseTimeout to add an end-to-end deadline
• passing WithMaximumAttempts(0) enables unlimited retries per the Temporal SDK convention
• DefaultActivityOpts is safe to call from workflow code; it allocates a new RetryPolicy on every call

Documentation

Overview

Package temporal provides a thin wrapper around the Temporal Go SDK for dialling a client and building activity options with sensible defaults.

Connecting

c, err := temporal.NewClient("default", "localhost", 7233)
if err != nil {
    log.Fatal(err)
}
defer c.Close()

Activity options

DefaultActivityOpts returns activity options with a 1 h StartToClose timeout and a capped exponential-backoff retry policy (3 attempts, 5 s initial interval, 1 min cap). Pass functional options to override specific fields.

opts := temporal.DefaultActivityOpts(
    temporal.WithStartToCloseTimeout(30 * time.Minute),
    temporal.WithMaximumAttempts(5),
)
ctx = workflow.WithActivityOptions(ctx, opts)
workflow.ExecuteActivity(ctx, myActivity, input)

Config struct

TemporalConfig carries the four connection parameters and is intended for use with the config package (mapstructure tags are included for Viper).

var cfg temporal.TemporalConfig
// populate from Viper / env ...
c, err := temporal.NewClient(cfg.Namespace, cfg.Host, cfg.Port)

Index

• Variables
• func DefaultActivityOpts(opts ...ActivityOption) workflow.ActivityOptions
• func NewClient(namespace, host string, port uint16) (client.Client, error)
• type ActivityOption
  • func WithMaximumAttempts(n int32) ActivityOption
  • func WithRetryPolicy(p *temporal.RetryPolicy) ActivityOption
  • func WithScheduleToCloseTimeout(d time.Duration) ActivityOption
  • func WithStartToCloseTimeout(d time.Duration) ActivityOption
  • func WithTaskQueue(taskQueue string) ActivityOption
• type TemporalConfig

Variables

var (
	ErrEmptyHost      = errors.New("temporal host cannot be empty")
	ErrEmptyNamespace = errors.New("temporal namespace cannot be empty")
)

Sentinel errors returned when dialing the Temporal client.

Functions

func DefaultActivityOpts

func DefaultActivityOpts(opts ...ActivityOption) workflow.ActivityOptions

DefaultActivityOpts returns activity options with sensible defaults: a 1h StartToClose timeout and a capped exponential-backoff retry policy. Pass options to customize specific fields, e.g.:

opts := temporal.DefaultActivityOpts(
	temporal.WithTaskQueue("audit"),
	temporal.WithStartToCloseTimeout(30*time.Minute),
)

func NewClient

func NewClient(namespace, host string, port uint16) (client.Client, error)

NewClient dials a Temporal server and returns a connected client. Host and namespace are required.

Types

type ActivityOption

type ActivityOption func(*workflow.ActivityOptions)

ActivityOption customizes the activity options produced by DefaultActivityOpts. Options are applied in order.

func WithMaximumAttempts

func WithMaximumAttempts(n int32) ActivityOption

WithMaximumAttempts overrides the retry policy's maximum attempts. A value of 0 means unlimited retries, per the Temporal SDK.

func WithRetryPolicy

func WithRetryPolicy(p *temporal.RetryPolicy) ActivityOption

WithRetryPolicy replaces the entire retry policy.

func WithScheduleToCloseTimeout

func WithScheduleToCloseTimeout(d time.Duration) ActivityOption

WithScheduleToCloseTimeout sets the ScheduleToClose timeout (unset by default).

func WithStartToCloseTimeout

func WithStartToCloseTimeout(d time.Duration) ActivityOption

WithStartToCloseTimeout overrides the StartToClose timeout.

func WithTaskQueue

func WithTaskQueue(taskQueue string) ActivityOption

WithTaskQueue routes the activity to a specific task queue. An empty value leaves the workflow's default task queue in place.

type TemporalConfig

type TemporalConfig struct {
	Host      string `mapstructure:"host"`
	Port      uint16 `mapstructure:"port"`
	Namespace string `mapstructure:"namespace"`
	TaskQueue string `mapstructure:"task_queue"`
}

TemporalConfig is the configuration for connecting to a Temporal server.