DOCSEARCHbyAlgolia
Submit Docs

AsyncMachine Go Documentation

website·Indexed 32 days ago

https://asyncmachine.dev

A framework for asynchronous state machines where code is bound to states rather than transitions. It includes asyncmachine-go (v0.19.3), aRPC for clock-based RPC, a decentralized synchronization network via pkg/pubsub, and a suite of developer tools including am-dbg (TUI debugger), am-gen (schema bootstrapper), and am-vis (diagram renderer). Supports WebAssembly via WebSockets and MessageChannels.

Tokens
42.5K
Snippets
257
Records
366
Agent score
66%

What's inside AsyncMachine

  1. Overview of aRPC for state machines

    aRPC is a transparent, clock-based RPC implementation for state machines using asyncmachine-go. It is built on top of cenkalti/rpc2 and soheilhy/cmux, with optional overlay via tmc/go-iroh. It optimizes performance by executing many API methods locally, as state changes are regularly pushed from the server to the client. It supports state checking, mutations, and state waiting, as well as WebSockets with authentication and iroh overlay (UDP/HTTP3 QUIC, ACLs, encryption, and NAT bypass).

  2. Overview of am-dbg TUI Debugger

    am-dbg is a lightweight, multi-client TUI debugger designed for async state machines. It can handle hundreds of simultaneous streams and provides a timeline of transitions for precise searching and drill-down of state mutations. Key capabilities include time travel (navigating between different state machines), a states tree with search-as-you-type, and a dedicated log reader for LogOps and SemLogger entries.

  3. Overview of available state schema mixins

    The pkg/states package provides common state schema mixins to simplify the composition and exchange of state-based APIs. Available schemas include:

    • BasicStatesDef: Includes Start, Ready, and Healthcheck states.
    • ConnectedStatesDef: Manages client connections across 4 states.
    • DisposedStatesDef: Handles asynchronous disposal.
    import ssam "github.com/pancsta/asyncmachine-go/pkg/states"

  4. Overview of Distributed Workflow Orchestration in /pkg/node

    /pkg/node implements distributed workflows using state-based orchestration of worker pools. It utilizes a failsafe supervision system and state machines for workers and clients. Because each worker runs in a separate OS process, all actors communicate via aRPC.

    Workflow Rules:

    • A worker can serve only one client.
    • A supervisor can serve many clients.
    • A client maintains a direct connection to its assigned worker.
    • A supervisor can supervise only one kind of worker.
    • A client can be connected to one supervisor.

  5. Overview of the WASM Workflow example

    The WASM Workflow example demonstrates a distributed computation (DAG-shaped hashing) involving 5 machines: one server-side orchestrator and four browser-based threads (browser1 through browser4). The browser threads consist of one UI thread and three WebWorkers. The workflow includes simulated random errors (corrupted hashes and failures) to demonstrate the Orchestrator's ability to retry specific nodes or restart the entire workflow. Communication is handled via single-direction aRPC connections from the Orchestrator to workers, while WebWorkers communicate using MessageChannel, ports, and copy-less ArrayBuffer transfers.

  6. Overview of asyncmachine-go PubSub

    The pkg/pubsub package implements a trustful, decentralized synchronization network. It allows peers to expose state machines and gossip about them to other peers. Remote state machines are exposed as pkg/rpc.NetworkMachine. This system is primarily used to match Clients with Supervisors from pkg/node. It is built on top of libp2p gossipsub, utilizing gossip for network topology, machine schemas, and clock updates. It supports state checking and state waiting, but does not support state mutations.

  7. Overview of mutation history tracking in pkg/history

    pkg/history provides mutation history tracking and traversal to help make informed decisions about state flow. It tracks machine time (including subsets for tracked states, diffs, and sums) and binds mutations to UTC human time. It can be used to resurrect state machines after a restart via the Machine.Import() method, which adds the MachineRestored state and increments the MachineTick by +1. This layer is compatible with both local and network machines via the Tracer API.

  8. Integrate asyncmachine-go with AI via MCP and external tools

    asyncmachine-go provides several integration points for AI agents and tools:

    • MCP Servers: State machines can be exposed as Model Context Protocol (MCP) servers via /pkg/integrations/mcp. Additionally, the am-dbg tool provides an MCP server specifically for automated debugging.
    • AI Layers: The secai project implements an AI layer on top of asyncmachine.
    • Documentation AI: context7 provides a search engine, chatbot, and MCP server specifically for asyncmachine documentation.
    • Skill Definitions: SKILL.md files located in /docs/editors provide detailed skill definitions for AI consumption.

  9. asyncmachine-go Developer Tools Overview

    The asyncmachine-go ecosystem provides several CLI tools for debugging, visualization, and generation:

    • am-dbg: Multi-client TUI debugger.
    • arpc: Network-native REPL and CLI.
    • am-vis: Generates D2 diagrams.
    • am-gen: Generates schema files and Grafana dashboards.
    • am-relay: Rotates logs and relays WASM.

  10. Implement lock-free Actor Model using Mutation Queues

    AsyncMachine employs a queue of mutations to enable a lock-free implementation of the Actor Model.

  11. Use dbg for TUI Debugging

    The dbg telemetry system is used by the am-dbg TUI Debugger. It delivers DbgMsg and DbgMsgStruct via standard net/rpc and can be consumed by custom clients.