asyncmachine-go

asyncmachine-go

[!NOTE] monorepo of asyncmachine-go, a clock-based state machine with a TUI debugger, transparent RPC, and telemetry for Otel & Prom.

asyncmachine can transform blocking APIs into controllable state machines with ease. It shares similarities with Ergo's actor model, and focuses on distributed workflows like Temporal. It's lightweight and most features are optional.

import am "github.com/pancsta/asyncmachine-go/pkg/machine"
mach := am.New(nil, am.Struct{
    "Foo": {Require: am.S{"Bar"}},
    "Bar": {},
}, nil)
mach.Add1("Foo", nil)
mach.Is1("Foo") // false

Getting Started

To get started, it's recommended to read /pkg/machine first.

Packages

• /pkg/helpers Useful functions when working with async state machines.
• /pkg/history History tracking and traversal.
• /pkg/machine State machine, the main package. Dependency free and semver compatible.
• /pkg/node Work in progress.
• /pkg/rpc Remote state machine, with the same API as a local one.
• /pkg/states Reusable state definitions.
• /pkg/telemetry Telemetry exporters for am-dbg, OpenTelemetry and Prometheus.
• /pkg/pubsub Planned.
• /tools/cmd/am-dbg am-dbg is a multi-client TUI debugger.
• /tools/cmd/am-gen am-gen generates states files.
• /tools/cmd/am-vis Planned.

Case Studies

• scraphouse - decentralized web scraping using /pkg/node
• libp2p PubSub Simulator - sandbox simulator for libp2p-pubsub
• libp2p PubSub Benchmark - benchmark of libp2p-pubsub ported to asyncmachine-go
• am-dbg TUI Debugger - single state machine TUI app

Documentation

• FAQ
• API
• diagrams
• cookbook
• discussions
• manual.md | manual.pdf
  • Machine and States
    • Clock and Context
    • Auto States
    • Categories of States
    • ...
  • Changing State
    • State Mutations
    • Transition Lifecycle
    • Target States
    • Negotiation Handlers
    • Final Handlers
    • ...
  • Advanced Topics
    • Relations
    • Queue and History
    • Typesafe States
    • ...
  • Remote Machines
    • ...
  • Cheatsheet

Development

• all PRs welcome
• before
  • ./scripts/dep-taskfile.sh
  • task install-deps
• after
  • task test
  • task format
  • task lint

Changelog

Latest release: v0.7.0

• docs: update readmes, manual, cookbook for v0.7 #127 (@pancsta)
• feat: release v0.7 #126 (@pancsta)
• refac(telemetry): switch telemetry to Tracer API #125 (@pancsta)
• fix(machine): fix test -race #124 (@pancsta)
• feat(machine): add Index() and Time.Is(index) #123 (@pancsta)
• feat(machine): add Eval() detection tool #122 (@pancsta)
• feat(machine): add EnvLogLevel #121 (@pancsta)
• feat(rpc): add grpc benchmark #120 (@pancsta)
• feat(machine): add PanicToErr, PanicToErrState #119 (@pancsta)
• feat(helpers): add pkg/helpers (Add1Block, Add1AsyncBlock, ...) #118 (@pancsta)
• feat(rpc): add pkg/rpc #117 (@pancsta)
• feat(states): add pkg/states #116 (@pancsta)
• feat(machine): add state def manipulations (eg StateAdd) #115 (@pancsta)
• feat(machine): add new Tracer methods (eg VerifyStates) #114 (@pancsta)
• feat(rpc): add rpc tests, including remote machine suite #113 (@pancsta)
• feat(machine): add SetLoggerSimple, SetLoggerEmpty #112 (@pancsta)
• feat(machine): add AddErrState and unified stack traces #111 (@pancsta)

Maintenance release: v0.6.5

• fix(am-dbg): correct timeline tailing #110 (@pancsta)
• fix(am-dbg): escape secondary logtxt brackets #109 (@pancsta)
• fix(am-dbg): fix filtering in TailMode #108 (@pancsta)
• fix(am-dbg): stop playing on timeline jumps #107 (@pancsta)
• fix(am-dbg): fix changing log level removed trailing tx #106 (@pancsta)
• fix(am-dbg): allow state jump after search as type #100 #105 (@pancsta)
• fix(am-dbg): align tree rel lines #104 (@pancsta)
• fix(am-dbg): fix tree highlights for ref links #103 (@pancsta)

Changes

• Full Changelog
• Breaking Changes
• Roadmap