https://github.com/tactors/sdk

Typed, builder-first actor SDK for Go built on Temporal.io: describe stateful workflows, commands, queries, and activities with fluent APIs, then run them deterministically across Temporal workers and testsuite scenarios.
https://github.com/tactors/sdk

actors builder-pattern distributed-systems go golang robust temporal testkit typed workflow-automation

Last synced: 22 days ago
JSON representation

Typed, builder-first actor SDK for Go built on Temporal.io: describe stateful workflows, commands, queries, and activities with fluent APIs, then run them deterministically across Temporal workers and testsuite scenarios.

• Host: GitHub
• URL: https://github.com/tactors/sdk
• Owner: tactors
• License: mit
• Created: 2025-11-16T11:42:59.000Z (4 months ago)
• Default Branch: main
• Last Pushed: 2025-11-27T12:06:07.000Z (4 months ago)
• Last Synced: 2025-11-28T01:13:19.366Z (4 months ago)
• Topics: actors, builder-pattern, distributed-systems, go, golang, robust, temporal, testkit, typed, workflow-automation
• Language: Go
• Homepage:
• Size: 293 KB
• Stars: 2
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Contributing: docs/CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Tactors SDK

Tactors is a typed, builder-first actor SDK for Go. You describe state, handlers, activities, and

runtime knobs in one fluent API and receive a deterministic actor description that every runtime can

consume—no code generation or `interface{}` plumbing. We still touch Go’s `%T` formatting to label

types, but handler routing stays strongly typed.

## What you get

- Typed actor builders: fix state with `actors.NewStateful`, get typed commands/queries/activities

  via helper embeds, and build once for every runtime consumer.

- Declarative knobs: retries, timeouts, caches, queue overrides, snapshots, and validators live on

  the builder so intent is obvious.

- Temporal-first runtime: one `actors.Description` powers worker registration, Ask/Query plumbing,

  and the deterministic testsuite—no alt runtimes or codegen.

- Ops hooks: spans/metrics around commands and cross-actor calls; rotation/versioning via

  `WithSnapshot` and `actors.Patch`.

## Quick start

1) New to the ecosystem? Read [`docs/NEW_TO_TEMPORAL.md`](docs/NEW_TO_TEMPORAL.md) and

   [`docs/NEW_TO_ACTORS.md`](docs/NEW_TO_ACTORS.md) for the quick primers.

2) Build the smallest actor in [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) and run it

   against the Temporal testsuite (`go test`).

3) Browse runnable samples in [`docs/EXAMPLES.md`](docs/EXAMPLES.md) (code lives at

   https://github.com/tactors/samples).

## Docs map

- Builder reference: [`docs/ACTOR_BUILDER.md`](docs/ACTOR_BUILDER.md).

- Runtime/worker behavior: [`docs/RUNTIME_TEMPORAL.md`](docs/RUNTIME_TEMPORAL.md).

- Advanced topology: [`docs/CROSS_NAMESPACE.md`](docs/CROSS_NAMESPACE.md) (opt-in routing across Temporal namespaces).

- Temporal-first map: [`docs/INDEX.md`](docs/INDEX.md) and [`docs/TEMPORAL_MENTAL_MODEL.md`](docs/TEMPORAL_MENTAL_MODEL.md).

- Ops & maintenance: [`docs/DIAGNOSTICS.md`](docs/DIAGNOSTICS.md) and [`docs/CONTROL_WORKFLOWS.md`](docs/CONTROL_WORKFLOWS.md).

- Orchestration pattern: [`docs/ACTIVITY_FLOW_PATTERN.md`](docs/ACTIVITY_FLOW_PATTERN.md) for “actor is the graph” guidance.

- Contributing: [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md).

## Testkit quick use

- `testkit.ActorTemporalScenario` runs actors against Temporal’s testsuite. Stub activities inline

  with `WhenActivity(...)`; it infers names from typed signatures or accepts explicit names.

- Inspect merged activity options with `ExpectActivityOptions` helpers before execution.

## Temporal runtime at a glance

- `runtime` registers workflows/activities from an actor description and wires Ask/Query/Spawn to

  Temporal signals, queries, and child workflows.

- `runtime.NewWorkerSet` reuses workers per queue and rotates histories automatically when

  `WithSnapshot` or `GetContinueAsNewSuggested()` triggers.

- Queue defaults match the actor kind (`-workflow` / `-activity`), and workers

  auto-disable the unused role so activity-only or workflow-only actors do not need extra flags.

  If you explicitly point both roles at the same queue and register both, one worker serves both.

- Activity calls get safe defaults: a StartToClose of 30s and ScheduleToClose of 2m are applied if

  you don’t set either. Override with `actors.WithActivityStartToClose` or

  `actors.WithActivityScheduleToClose` per-call or via `WithActivityDefaults`.

## Repository guide

- `actors/` – builder, typed helpers, and shared primitives.

- `runtime/` – Temporal runner plus typed client utilities.

- `testkit/` – deterministic harnesses (Temporal scenario and testing helpers).

- `observability/` – pluggable tracing/metrics hooks; `internal/` – supporting packages as we flesh

  out tooling.

- Samples now live in the sibling repo: https://github.com/tactors/samples.

## Testing

Run the full suite (unit tests and Temporal testsuite scenarios) with:

```bash

GOCACHE=$(pwd)/.gocache go test ./...

```

No external Temporal server is required—the testsuite handles registration, fake time, and cleanup.

## License

Released under the [MIT License](LICENSE).