docs: update readmes v0.12

Author: pancsta

FAQ.md

@@ -52,7 +52,7 @@ aRPC auto syncs only clock values, which technically is `[n]uint64` (`n` = numbe
 
 ## Does asyncmachine return data?
 
-No, just yes/no/later (`Executed`, `Canceled`, `Queued`).
+No, just yes/no/later (`Executed`, `Canceled`, `Queued`). Use channels in mutation args for returning local data and the `SendPayload` state for aRPC.
 
 ## Does asyncmachine return errors?
 
@@ -73,6 +73,10 @@ The queue executes on the thread which caused the mutation, while handlers execu
 Each handler usually forks another goroutine to unblock the next handler. The amount of active goroutines can be limited
 with `amhelp.Pool` (`errgroup`) per a state, machine, or both. It's a form of structured concurrency.
 
+## What should be a "state"?
+
+Only interesting things - if we don't care about something to be a separate entity, there's no need to orchestrate it as a separate state.
+
 ## What's the origin of asyncmachine?
 
 It was a [self-research prototype](https://github.com/TobiaszCudnik/asyncmachine) between 2012 and 2019. There's a

README.md

@@ -12,6 +12,7 @@
     <a href="#samples">Samples</a> .
     <a href="#getting-started">Getting Started</a> .
     <a href="#packages">Packages</a> .
+    <a href="#devtools">Devtools</a> .
     <a href="#apps">Apps</a> .
     <a href="#documentation">Docs</a> .
     <a href="#development">Dev</a> .
@@ -28,13 +29,14 @@
 </div>
 
 > [!NOTE]
-> State machines communicate through states (mutations, checking, and waiting).
+> State machines communicate through states.
 
 **asyncmachine-go** is a batteries-included graph control flow library implementing [AOP](https://en.wikipedia.org/wiki/Aspect-oriented_programming)
 and [Actor Model](https://en.wikipedia.org/wiki/Actor_model) through a **[clock-based state-machine](/pkg/machine/README.md)**.
-It features [atomic transitions](/docs/manual.md#transition-lifecycle), [transparent RPC](/pkg/rpc/README.md),
-[TUI debugger](/tools/cmd/am-dbg/README.md), [telemetry](/pkg/telemetry/README.md), [REPL](/tools/cmd/arpc/README.md),
-[remote workers](/pkg/node/README.md), and [diagrams](https://github.com/pancsta/asyncmachine-go/pull/216).
+It features [atomic transitions](/docs/manual.md#transition-lifecycle), [relations with consensus](/docs/manual.md#relations),
+[transparent RPC](/pkg/rpc/README.md), [TUI debugger](/tools/cmd/am-dbg/README.md),
+[telemetry](/pkg/telemetry/README.md), [REPL](/tools/cmd/arpc/README.md), [remote workers](/pkg/node/README.md),
+and [diagrams](https://github.com/pancsta/asyncmachine-go/pull/216).
 
 As a control flow library, it decides about running of predefined bits of code (transition handlers) - their order and
 which ones to run, according to currently active states (flags). Thanks to a [novel state machine](/pkg/machine/README.md),
@@ -53,17 +55,20 @@ It aims to create **autonomous** workflows with **organic** control flow and **s
 Each state represents:
 
 - binary flag
-- node in a multigraph
+- ID
+- node with relations
 - AOP aspect
-- metric
-- trace
+- logical clock
 - subscription topic
 - multiple methods
+- metric
+- trace
+- lock
 - breakpoint
 
 Besides workflows, it can be used for **stateful applications** of any size - daemons, UIs, configs, bots, firewalls,
-synchronization consensus, games, smart graphs, microservice orchestration, contracts, simulators, as well as
-**"real-time" systems** which rely on instant cancellations.
+synchronization consensus, games, smart graphs, microservice orchestration, robots, contracts, streams, DI containers,
+test scenarios, simulators, as well as **"real-time" systems** which rely on instant cancelation.
 
 ![diagram](https://github.com/pancsta/assets/blob/main/asyncmachine-go/am-vis.svg?raw=true)
 
@@ -79,63 +84,99 @@ The top layers depend on the bottom ones.
     <td>.</td>
     <td>.</td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
     <td colspan="1" align=center><a href="pkg/pubsub/README.md">PubSub</a></td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
+    <td>.</td>
   </tr>
+
   <tr>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
     <td colspan="3" align=center><a href="pkg/node/README.md">Workers</a></td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
+    <td>.</td>
   </tr>
+
   <tr>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
     <td colspan="5" align=center><a href="pkg/rpc/README.md">RPC</a></td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
   </tr>
+
   <tr>
+    <td>.</td>
+    <td>.</td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
     <td colspan="7" align=center><a href="pkg/machine/README.md#aop-handlers">Handlers</a></td>
     <td>.</td>
     <td>.</td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
   </tr>
+
   <tr>
+    <td>.</td>
+    <td>.</td>
     <td>.</td>
     <td>.</td>
     <td colspan="9" align=center>🐇 <a href="pkg/machine/README.md">Machine API</a></td>
     <td>.</td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
   </tr>
+
   <tr>
+    <td>.</td>
+    <td>.</td>
     <td>.</td>
     <td colspan="11" align=center><a href="pkg/machine/README.md#relations">Relations</a></td>
     <td>.</td>
+    <td>.</td>
+    <td>.</td>
   </tr>
+
   <tr>
+    <td>.</td>
+    <td>.</td>
     <td colspan="13" align=center><a href="pkg/machine/README.md#multi-state"><b><u>
         States
     </u></b></a></td>
+    <td>.</td>
+    <td>.</td>
   </tr>
 </table>
 
@@ -254,31 +295,34 @@ All examples and benchmarks can be found in [`/examples`](/examples/README.md).
 - 🦾 **[`/pkg/machine`](pkg/machine/README.md)** is the main package
 - [`/pkg/node`](pkg/node) shows a high-level usage
 - examples in [`/examples`](/examples/README.md) are good for a general grasp
+  - with [`/examples/mach_template`](/examples/mach_template) being ready for copy-paste
 - [`/docs/manual.md`](/docs/manual.md)
   and [`/docs/diagrams.md`](/docs/diagrams.md) go deeper into implementation details
 - [`/tools/cmd/am-gen`](/tools/cmd/am-gen) will bootstrap
-- [`/examples/mach_template`](/examples/mach_template) is copy-paste ready
-- [`/tools/cmd/am-dbg`](/tools/cmd/am-dbg) records every detail
-- [reading tests](https://github.com/search?q=repo%3Apancsta%2Fasyncmachine-go+path%3A%2F.*_test.go%2F&type=code)
+- [`/tools/cmd/am-dbg`](/tools/cmd/am-dbg) will record every detail
+- and [reading tests](https://github.com/search?q=repo%3Apancsta%2Fasyncmachine-go+path%3A%2F.*_test.go%2F&type=code)
   is always a good idea
 
 ## [Packages](/pkg)
 
-This monorepo offers the following importable packages and runnable tools, especially:
+This monorepo offers the following importable packages, especially:
 
 - 🦾 **[`/pkg/machine`](/pkg/machine/README.md) State machine, dependency free, semver compatible.**
 - [`/pkg/states`](/pkg/states/README.md) Reusable state schemas, handlers, and piping.
 - [`/pkg/helpers`](/pkg/helpers/README.md) Useful functions when working with async state machines.
 - [`/pkg/telemetry`](/pkg/telemetry/README.md) Telemetry exporters for dbg, metrics, traces, and logs.
 
-Remaining packages:
+Other packages:
 
 - [`/pkg/graph`](/pkg/graph) Multigraph of interconnected state machines.
 - [`/pkg/history`](/pkg/history/README.md) History tracking and traversal.
 - [`/pkg/integrations`](/pkg/integrations/README.md) NATS and other JSON integrations.
 - [`/pkg/node`](/pkg/node/README.md) Distributed worker pools with supervisors.
 - [`/pkg/rpc`](/pkg/rpc/README.md) Remote state machines, with the same API as local ones.
 - [`/pkg/pubsub`](/pkg/pubsub/README.md) Decentralized PubSub based on libp2p gossipsub.
+
+## [Devtools](/tools)
+
 - [`/tools/cmd/am-dbg`](/tools/cmd/am-dbg/README.md) Multi-client TUI debugger.
 - [`/tools/cmd/am-gen`](/tools/cmd/am-gen/README.md) Generates schema files and Grafana dashboards.
 - [`/tools/cmd/am-vis`](https://github.com/pancsta/asyncmachine-go/pull/216) Generates diagrams of interconnected state machines.
@@ -305,6 +349,14 @@ Remaining packages:
     - [Changing State](/docs/manual.md#changing-state)
     - [Advanced Topics](/docs/manual.md#advanced-topics)
     - [Cheatsheet](/docs/manual.md#cheatsheet)
+    
+## Goals
+
+- scale up, not down
+- defaults work by default
+- everything can be traced and debugged
+- automation is evolution
+- state != data
 
 ## Community
 

docs/env-configs.md

@@ -164,7 +164,7 @@ AM_PUBSUB_DBG=1
 # defaults to ""
 AM_REPL_ADDR=1
 
-# REPL address file dir path (`addrDir/mach-id.addr`). Optional.
+# REPL address file dir path (for `$AM_REPL_DIR/mach-id.addr`). Optional.
 # defaults to ""
-AM_REPL_ADDR_DIR=tmp
+AM_REPL_DIR=tmp
 ```

examples/tree_state_source/README.md

@@ -38,6 +38,8 @@ type FlightsStatesDef struct {
 
     // ...
 
+	// inherit from BasicStatesDef
+	*ssam.BasicStatesDef
     // inherit from rpc/WorkerStatesDef
     *ssrpc.WorkerStatesDef
 }

pkg/machine/README.md

@@ -173,7 +173,7 @@ func (h *Handlers) ProcessingFileState(e *am.Event) {
     // no blocking
     // lock-free critical section
     mach := e.Machine
-    // clock-based context
+    // clock-based expiration context
     stateCtx := mach.NewStateCtx("ProcessingFile")
     // unblock
     go func() {
@@ -209,6 +209,9 @@ func (h *Handlers) ProcessingFileState(e *am.Event) {
 // wait for EventConnected to be activated with an arg ID=123
 <-mach.WhenArgs("EventConnected", am.A{"ID": 123}, nil)
 
+// wait for Foo to have a tick >= 6
+<-mach.WhenTime1("Foo", 6, nil)
+
 // wait for Foo to have a tick >= 6 and Bar tick >= 10
 <-mach.WhenTime(am.S{"Foo", "Bar"}, am.Time{6, 10}, nil)
 
@@ -343,6 +346,7 @@ The most common API methods are listed below. There's more for [local state mach
 but all of these are also implemented in the [transparent RPC layer](/pkg/rpc/README.md).
 
 ```go
+// TODO update
 // A (arguments) is a map of named arguments for a Mutation.
 type A map[string]any
 // S (state names) is a string list of state names.
@@ -506,6 +510,7 @@ Release Candidate, semantically versioned, not optimized yet.
 - [SQL relations](https://en.wikipedia.org/wiki/SQL)
 - [Paxos negotiation](https://en.wikipedia.org/wiki/Paxos_(computer_science))
 - [logical clock](https://en.wikipedia.org/wiki/Logical_clock)
+- [programming by contract](https://en.wikipedia.org/wiki/Design_by_contract)
 - [non-blocking](https://en.wikipedia.org/wiki/Non-blocking_algorithm)
 - [Actor Model](https://en.wikipedia.org/wiki/Actor_model)
 - [causal inference](https://en.wikipedia.org/wiki/Causal_inference)

pkg/states/ss_disposed.go

@@ -68,7 +68,7 @@ func (h *DisposedHandlers) RegisterDisposalEnter(e *am.Event) bool {
 	fn, ok := e.Args[DisposedArgHandler].(am.HandlerDispose)
 	ret := ok && fn != nil
 	// avoid errs on check mutations
-	if ret == false && !e.IsCheck {
+	if !ret && !e.IsCheck {
 		err := fmt.Errorf("%w: DisposedArgHandler invalid", am.ErrInvalidArgs)
 		e.Machine().AddErr(err, nil)
 	}

pkg/telemetry/README.md

@@ -60,13 +60,16 @@ added as well.
 See [/docs/env-configs.md](/docs/env-configs.md) for the required environment variables.
 
 ```go
-// root machines only
-if mach.ParentId() == "" {
-    // open telemetry traces
-    err = amtele.MachBindOtelEnv(mach)
-    if err != nil {
+import amtele "github.com/pancsta/asyncmachine-go/pkg/telemetry"
+
+// ...
+
+var mach *am.Machine
+
+// open telemetry traces
+err = amtele.MachBindOtelEnv(mach)
+if err != nil {
     mach.AddErr(err, nil)
-    }
 }
 ```
 
@@ -127,11 +130,14 @@ Tracers are inherited from parent machines.
 See [/docs/env-configs.md](/docs/env-configs.md) for the required environment variables.
 
 ```go
-// root machines only
-if mach.ParentId() == "" {
-    // export metrics to prometheus
-    metrics := amprom.MachMetricsEnv(mach)
-}
+import amtele "github.com/pancsta/asyncmachine-go/pkg/telemetry"
+
+// ...
+
+var mach *am.Machine
+
+// export metrics to prometheus
+metrics := amprom.MachMetricsEnv(mach)
 ```
 
 ### Manual Prometheus Setup
@@ -142,6 +148,7 @@ import (
     am "github.com/pancsta/asyncmachine-go/pkg/machine"
     amprom "github.com/pancsta/asyncmachine-go/pkg/telemetry/prometheus"
     "github.com/prometheus/client_golang/prometheus/push"
+)
 
 // ...
 
@@ -166,13 +173,13 @@ Loki is the easiest way to persist distributed logs from asyncmachine. You'll ne
 See [/docs/env-configs.md](/docs/env-configs.md) for the required environment variables.
 
 ```go
-import (
-    amtele "github.com/pancsta/asyncmachine-go/pkg/telemetry"
-)
+import amtele "github.com/pancsta/asyncmachine-go/pkg/telemetry"
 
 // ...
 
 var mach *am.Machine
+
+// export logs to Loki logger
 amtele.BindLokiEnv(mach)
 ```