ranbot-ai/temporal-golang-pro

Temporal Go SDK (temporal-golang-pro)

Overview

Expert-level guide for building resilient, scalable, and deterministic distributed systems using the Temporal Go SDK. This skill transforms vague orchestration requirements into production-grade Go implementations, focusing on durable execution, strict determinism, and enterprise-scale worker configuration.

When to Use This Skill

• Designing Distributed Systems: When building microservices that require durable state and reliable orchestration.
• Implementing Complex Workflows: Using the Go SDK to handle long-running processes (days/months) or complex Saga patterns.
• Optimizing Performance: When workers need fine-tuned concurrency, mTLS security, or custom interceptors.
• Ensuring Reliability: Implementing idempotent activities, graceful error handling, and sophisticated retry policies.
• Maintenance & Evolution: Versioning running workflows or performing zero-downtime worker updates.

Do not use this skill when

• Using Temporal with other SDKs (Python, Java, TypeScript) - refer to their specific -pro skills.
• The task is a simple request/response without durability or coordination needs.
• High-level design without implementation (use workflow-orchestration-patterns).

Step-by-Step Guide

1. Gather Context: Proactively ask for:
   • Target Temporal Cluster (Cloud vs. Self-hosted) and Namespace.
   • Task Queue names and expected throughput.
   • Security requirements (mTLS paths, authentication).
   • Failure modes and desired retry/timeout policies.
2. Verify Determinism: Before suggesting workflow code, verify against these 5 Rules:
   • No native Go concurrency (goroutines).
   • No native time (time.Now, time.Sleep).
   • No non-deterministic map iteration (must sort keys).
   • No direct external I/O or network calls.
   • No non-deterministic random numbers.
3. Implement Incrementally: Start with shared Protobuf/Data classes, then Activities, then Workflows, and finally Workers.
4. Leverage Resources: If the implementation requires advanced patterns (Sagas, Interceptors, Replay Testing), explicitly refer to the implementation playbook and testing strategies.

Capabilities

Go SDK Implementation

• Worker Management: Deep knowledge of worker.Options, including MaxConcurrentActivityTaskPollers, WorkerStopTimeout, and StickyScheduleToStartTimeout.
• Interceptors: Implementing Client, Worker, and Workflow interceptors for cross-cutting concerns (logging, tracing, auth).
• Custom Data Converters: Integrating Protobuf, encrypted payloads, or custom JSON marshaling.

Advanced Workflow Patterns

• Durable Concurrency: Using workflow.Go, workflow.Channel, and workflow.Selector instead of native primitives.
• Versioning: Implementing safe code evolution using workflow.GetVersion and workflow.GetReplaySafeLogger.
• Large-scale Processing: Pattern for ContinueAsNew to manage history size limits (defaults: 50MB or 50K events).
• Child Workflows: Managing lifecycle, cancellation, and parent-child signal propagation.

Testing & Observability

• Testsuite Mastery: Using WorkflowTestSuite for unit and functional testing with deterministic time control.
• Mocking: Sophisticated activity and child workflow mocking strategies.
• Replay Testing: Validating code changes against production event histories.
• Metrics: Configuring Prometheus/OpenTelemetry exporters for worker performance tracking.

Examples

Example 1: Versioned Workflow (Deterministic)

// Note: imports omitted. Requires 'go.temporal.io/sdk/workflow', 'go.temporal.io/sdk/temporal', and 'time'.
func SubscriptionWorkflow(ctx workflow.Context, userID string) error {
    // 1. Versioning for logic evolution (v1 = DefaultVersion)
    v := workflow.GetVersion(ctx, "billing_logic", workflow.DefaultVersion, 2)

    for i := 0; i < 12; i++ {
        ao := workflow.ActivityOptions{
            StartToCloseTimeout: 5 * time.Minute,
            RetryPolicy: &temporal.RetryPolicy{MaximumAttempts: 3},
        }
        ctx = workflow.WithActivityOptions(ctx, ao)

        // 2. Activity Execution (Always handle errors)
        err := workflow.ExecuteActivity(ctx, ChargePaymentActivity, userID).Get(ctx, nil)
        if err != nil {
            workflow.GetLogger(ctx).Error("Payment failed", "Error", err)
            return err
        }

        // 3. Durable Sleep (Time-skipping safe)
        sleepDuration := 30 * 24 * time.Hour
        if v >= 2 {
            sleepDuration = 28 * 24 * time.Hour
        }

        if err := workflow.Sleep(ctx, sleepDuration); err != nil {
            return err
        }
    }
    return nil
}

Example 2: Full mTLS Worker Setup

func RunSecureWorker() error {
    // 1. Load Client Certificate and Key
    cert, err := tls.LoadX509KeyPair("client.pem", "client.key")
    if err != nil {