stateous 0.2.2__tar.gz → 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {stateous-0.2.2 → stateous-0.4.0}/.gitignore +2 -0
- {stateous-0.2.2 → stateous-0.4.0}/PKG-INFO +2 -2
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/agents.md +2 -2
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/context-notes-memory.md +2 -1
- stateous-0.4.0/docs/concepts/data.md +115 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/guards.md +11 -3
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/model.md +6 -48
- stateous-0.4.0/docs/concepts/notices.md +68 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/parallel.md +4 -2
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/pause-resume-cancel.md +4 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/reliability.md +4 -2
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/tasks-and-routines.md +3 -3
- stateous-0.4.0/docs/concepts/tenancy.md +79 -0
- stateous-0.4.0/docs/concepts/transports.md +67 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/two-sides.md +2 -2
- {stateous-0.2.2 → stateous-0.4.0}/docs/getting-started.md +94 -25
- stateous-0.4.0/docs/how-to/embed-a-control-plane.md +123 -0
- stateous-0.4.0/docs/how-to/run-replicas.md +70 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/run-supervisors.md +28 -1
- {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/steer-tokens.md +8 -2
- {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/use-postgres.md +4 -5
- {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/write-a-routine.md +8 -2
- stateous-0.4.0/docs/how-to/write-a-transport.md +109 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/write-a-workflow.md +7 -3
- stateous-0.4.0/docs/index.md +50 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/inside/data.md +58 -13
- stateous-0.4.0/docs/inside/words.md +39 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/inside/workflows.md +5 -5
- {stateous-0.2.2 → stateous-0.4.0}/docs/reference/cli.md +32 -7
- {stateous-0.2.2 → stateous-0.4.0}/docs/reference/files.md +2 -1
- {stateous-0.2.2 → stateous-0.4.0}/docs/reference/http.md +10 -3
- stateous-0.4.0/docs/reference/python.md +156 -0
- {stateous-0.2.2 → stateous-0.4.0}/mkdocs.yml +8 -0
- {stateous-0.2.2 → stateous-0.4.0}/pyproject.toml +34 -3
- {stateous-0.2.2 → stateous-0.4.0}/scripts/check.py +1 -1
- stateous-0.4.0/src/stateous/__init__.py +141 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/main.py +27 -1
- stateous-0.4.0/src/stateous/cli/migrating.py +29 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/running.py +30 -8
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/serving.py +59 -151
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/starter.py +21 -24
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/tokens.py +47 -4
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/client/client.py +48 -12
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/codegen.py +2 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/compile.py +13 -4
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/exclusive.py +1 -1
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/validate.py +20 -0
- stateous-0.4.0/src/stateous/control/access.py +20 -0
- stateous-0.4.0/src/stateous/control/answer.py +102 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/api.py +246 -166
- stateous-0.4.0/src/stateous/control/checks.py +147 -0
- stateous-0.4.0/src/stateous/control/clock.py +112 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/engine.py +281 -141
- stateous-0.4.0/src/stateous/control/errors.py +120 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/graph.py +28 -5
- stateous-0.4.0/src/stateous/control/ids.py +31 -0
- stateous-0.4.0/src/stateous/control/inprocess.py +53 -0
- stateous-0.4.0/src/stateous/control/notices.py +106 -0
- stateous-0.4.0/src/stateous/control/plane.py +779 -0
- stateous-0.4.0/src/stateous/control/scope.py +56 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/__init__.py +2 -2
- stateous-0.4.0/src/stateous/control/store/errors.py +25 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/migrations/__init__.py +37 -32
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/migrations/env.py +3 -2
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/migrations/versions/0001_baseline.py +69 -4
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/store.py +608 -33
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/tables.py +74 -0
- stateous-0.4.0/src/stateous/control/waiting.py +85 -0
- stateous-0.4.0/src/stateous/model/branches.py +32 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/context.py +19 -3
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/graph_file.py +24 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/guards.py +29 -15
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/wire.py +17 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/workflow.py +58 -6
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/folder.py +2 -0
- stateous-0.4.0/src/stateous/supervisor/remote.py +184 -0
- stateous-0.4.0/src/stateous/supervisor/retrying.py +146 -0
- stateous-0.4.0/src/stateous/supervisor/run.py +58 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/supervisor.py +56 -20
- stateous-0.4.0/src/stateous/testing.py +213 -0
- stateous-0.4.0/src/stateous/transport/__init__.py +28 -0
- stateous-0.4.0/src/stateous/transport/calling.py +98 -0
- stateous-0.4.0/src/stateous/transport/errors.py +21 -0
- stateous-0.4.0/src/stateous/transport/messages.py +79 -0
- stateous-0.4.0/src/stateous/transport/protocol.py +55 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_concepts.py +76 -10
- {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_how_to.py +0 -2
- {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_numbers.py +2 -2
- {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_reference.py +19 -8
- {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_site.py +2 -2
- {stateous-0.2.2 → stateous-0.4.0}/tests/e2e/test_example.py +14 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/conftest.py +7 -9
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/supervising.py +3 -2
- stateous-0.4.0/tests/integration/test_api_authorize.py +161 -0
- stateous-0.4.0/tests/integration/test_api_labels.py +80 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_api_parallel.py +3 -1
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_api_refusals.py +3 -3
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_api_tasks.py +9 -14
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_api_tokens.py +4 -4
- stateous-0.4.0/tests/integration/test_claim_wait.py +177 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_client.py +5 -3
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_prepare_serve.py +1 -1
- stateous-0.4.0/tests/integration/test_supervise_api.py +145 -0
- stateous-0.4.0/tests/postgres/test_given_engine.py +73 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_migrations.py +2 -27
- stateous-0.4.0/tests/postgres/test_namespace.py +101 -0
- stateous-0.4.0/tests/postgres/test_notices.py +72 -0
- stateous-0.4.0/tests/postgres/test_ready_across_replicas.py +125 -0
- stateous-0.4.0/tests/postgres/test_replicas.py +223 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_serving.py +7 -7
- {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_time_limits.py +11 -6
- stateous-0.4.0/tests/transport/memory_queue.py +52 -0
- stateous-0.4.0/tests/transport/test_kit.py +109 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_clock.py +2 -1
- stateous-0.4.0/tests/unit/cli/test_command_failures.py +191 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_init_workflow.py +4 -4
- stateous-0.4.0/tests/unit/cli/test_migrate.py +95 -0
- stateous-0.4.0/tests/unit/cli/test_running_paths.py +267 -0
- stateous-0.4.0/tests/unit/cli/test_serving_refusals.py +70 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_show_children.py +1 -1
- stateous-0.4.0/tests/unit/cli/test_show_context.py +130 -0
- stateous-0.4.0/tests/unit/client/test_client_requests.py +90 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_codegen.py +63 -0
- stateous-0.4.0/tests/unit/compiler/test_exclusive_domains.py +112 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_load.py +8 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_validate.py +37 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/support.py +18 -1
- stateous-0.4.0/tests/unit/control/test_answer.py +154 -0
- stateous-0.4.0/tests/unit/control/test_api_edges.py +69 -0
- stateous-0.4.0/tests/unit/control/test_authorize.py +166 -0
- stateous-0.4.0/tests/unit/control/test_claim_labels.py +83 -0
- stateous-0.4.0/tests/unit/control/test_engine_edges.py +255 -0
- stateous-0.4.0/tests/unit/control/test_explicit_migrations.py +84 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_graph.py +8 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_inputs.py +14 -5
- stateous-0.4.0/tests/unit/control/test_into_engine.py +187 -0
- stateous-0.4.0/tests/unit/control/test_labels.py +98 -0
- stateous-0.4.0/tests/unit/control/test_made_ids.py +71 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_migrations.py +16 -82
- stateous-0.4.0/tests/unit/control/test_namespace.py +41 -0
- stateous-0.4.0/tests/unit/control/test_notices_delivered.py +219 -0
- stateous-0.4.0/tests/unit/control/test_notices_labels.py +41 -0
- stateous-0.4.0/tests/unit/control/test_notices_written.py +159 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_parallel.py +6 -6
- stateous-0.4.0/tests/unit/control/test_plane.py +181 -0
- stateous-0.4.0/tests/unit/control/test_replicas.py +14 -0
- stateous-0.4.0/tests/unit/control/test_scope_keys.py +93 -0
- stateous-0.4.0/tests/unit/control/test_scopes.py +205 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_serving.py +2 -16
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_store.py +0 -16
- stateous-0.4.0/tests/unit/control/test_store_edges.py +74 -0
- stateous-0.4.0/tests/unit/control/test_task_ready.py +101 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_tasks.py +4 -3
- stateous-0.4.0/tests/unit/control/test_waiting.py +59 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_context.py +44 -3
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_contract.py +4 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_graph_file.py +14 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_guards.py +43 -8
- stateous-0.4.0/tests/unit/model/test_into.py +192 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/fakes.py +37 -6
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_folder.py +17 -0
- stateous-0.4.0/tests/unit/supervisor/test_http_transport.py +150 -0
- stateous-0.4.0/tests/unit/supervisor/test_outbox_errors.py +39 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_remote.py +11 -32
- stateous-0.4.0/tests/unit/supervisor/test_remote_answers.py +129 -0
- stateous-0.4.0/tests/unit/supervisor/test_retrying.py +116 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_supervisor_edges.py +32 -20
- stateous-0.4.0/tests/unit/supervisor/test_supervisor_faults.py +546 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_supervisor_outbox.py +6 -8
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/test_layout.py +1 -0
- stateous-0.4.0/tests/unit/test_public_names.py +49 -0
- stateous-0.4.0/tests/unit/transport/test_calling.py +170 -0
- stateous-0.4.0/tests/unit/transport/test_messages.py +80 -0
- stateous-0.2.2/docs/index.md +0 -44
- stateous-0.2.2/docs/reference/python.md +0 -46
- stateous-0.2.2/src/stateous/__init__.py +0 -24
- stateous-0.2.2/src/stateous/control/store/errors.py +0 -10
- stateous-0.2.2/src/stateous/control/store/migrations/versions/0002_claims.py +0 -34
- stateous-0.2.2/src/stateous/control/store/migrations/versions/0003_children.py +0 -40
- stateous-0.2.2/src/stateous/supervisor/remote.py +0 -238
- stateous-0.2.2/tests/unit/test_public_names.py +0 -19
- {stateous-0.2.2 → stateous-0.4.0}/LICENSE +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/NOTICE +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/README.md +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/timers.md +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/change-a-workflow.md +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/inside/event-graph.md +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/docs/reference/limits.md +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc/build/sdlc.json +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc/flow.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc/schemas.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc-supervisor/coding.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc-supervisor/contract.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc-supervisor/stateous.yaml +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc-supervisor/testing.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/__main__.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/__init__.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/errors.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/project_file.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/client/__init__.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/__init__.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/load.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/plot.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/__init__.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/migrations/script.py.mako +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/__init__.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/contract.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/durations.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/events.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/host.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/py.typed +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/__init__.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/outbox.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/registry.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/conftest.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/docs/pages.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_inside.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/examples/fake_phd.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/examples/test_coding.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/examples/test_sdlc.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_parallel_flow.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_project_uv_sync.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_serve_command.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_supervise_cli.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_supervise_process.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_supervisor_flow.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_token_commands.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/parallel.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_concurrency.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_connection.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_closed_output.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_compile_command.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_configure_logging.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_errors.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_graceful_server.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_listen.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_project_file.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_startup.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_supervise_helpers.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_supervised_server.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_token_lines.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_compile.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_exclusive.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_plot.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_case_race.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_claim_requests.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_clock.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_deadlock.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_engine.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_parallel_steering.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_pause.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_durations.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_host.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_wire.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_workflow.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_open.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_outbox.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_registry.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_supervisor.py +0 -0
- {stateous-0.2.2 → stateous-0.4.0}/tests/unit/test_test_databases.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: stateous
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: A process as a graph of states. A control plane keeps every token durable.
|
|
5
5
|
Project-URL: Homepage, https://github.com/StateousLabs/stateous
|
|
6
6
|
Project-URL: Source, https://github.com/StateousLabs/stateous
|
|
@@ -33,7 +33,7 @@ Requires-Dist: starlette>=0.40
|
|
|
33
33
|
Requires-Dist: typer>=0.12
|
|
34
34
|
Requires-Dist: uvicorn>=0.30
|
|
35
35
|
Provides-Extra: phd
|
|
36
|
-
Requires-Dist: poly-harness-dispatcher>=0.
|
|
36
|
+
Requires-Dist: poly-harness-dispatcher>=0.2; extra == 'phd'
|
|
37
37
|
Description-Content-Type: text/markdown
|
|
38
38
|
|
|
39
39
|
# Stateous
|
|
@@ -6,7 +6,7 @@ A routine runs a coding agent with the library PHD, and Stateous keeps the agent
|
|
|
6
6
|
|
|
7
7
|
## Why it exists
|
|
8
8
|
|
|
9
|
-
A coding agent can work for an hour, hang, or crash with its computer. Its answer must
|
|
9
|
+
A coding agent can work for an hour, hang, or crash with its computer. Its answer must name one of the events that the state allows. When it fails, the next try should continue its session, not start again.
|
|
10
10
|
|
|
11
11
|
Stateous and PHD share this work. PHD runs the agent and checks its answer. Stateous keeps the task, the retries and the session id. PHD knows nothing of workflows, and it does not report to Stateous.
|
|
12
12
|
|
|
@@ -137,7 +137,7 @@ async def code(ctx: TicketContext) -> events.done | events.stuck:
|
|
|
137
137
|
|
|
138
138
|
## Guarantees
|
|
139
139
|
|
|
140
|
-
- Only an
|
|
140
|
+
- Only an event that the state can emit is accepted. PHD checks it, and the control plane checks it again.
|
|
141
141
|
- The task's lease stays alive while the routine runs, for as long as the agent works.
|
|
142
142
|
- When the token leaves the state, or is cancelled, the supervisor cancels the routine at the next heartbeat, and PHD stops the run.
|
|
143
143
|
- The session id in `ctx.memory` stays after a crash, so the next attempt can resume the session.
|
|
@@ -25,9 +25,10 @@ These are the fields of `ctx`:
|
|
|
25
25
|
| `ctx.note(text)` | One line of progress in the token's history. It is sent at once. |
|
|
26
26
|
| `ctx.token` | The token's id. |
|
|
27
27
|
| `ctx.task` | The task's id. |
|
|
28
|
+
| `ctx.labels` | The token's labels, for example `{"user": "u42"}`: they tell which tenant the token is of. |
|
|
28
29
|
| `ctx.visit` | 1 the first time the token is in this state, 2 the next time, and so on. |
|
|
29
30
|
| `ctx.attempt` | 1, then 2 after a retry, and so on. |
|
|
30
|
-
| `ctx.entered_by` | The event that brought the token here
|
|
31
|
+
| `ctx.entered_by` | The name of the event that brought the token here, as `ctx.entered_by.name`. In the first state, it is `__started__`. A routine does not get the payload: an event whose payload the token keeps declares `into=`. See [Where data goes](data.md). |
|
|
31
32
|
| `ctx.schedule(event, after="10m")` | A timer. See [Timers and timeouts](timers.md). |
|
|
32
33
|
|
|
33
34
|
### The context
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Where data goes
|
|
2
|
+
|
|
3
|
+
## In one sentence
|
|
4
|
+
|
|
5
|
+
A routine reads and writes only the context: an event says why a token moved, and `into=` keeps its payload in the context.
|
|
6
|
+
|
|
7
|
+
## Why it exists
|
|
8
|
+
|
|
9
|
+
A token carries data from state to state. Without one rule, data can go to many places, and you must choose each time.
|
|
10
|
+
|
|
11
|
+
Stateous has two rules, and the API follows them:
|
|
12
|
+
|
|
13
|
+
1. **Data.** A routine reads and writes only the context. An event's name and payload say *why* the token moved. Guards and the history read the payload. If the token must keep a payload, the event declares `into=`.
|
|
14
|
+
2. **Decisions.** Routines decide, and guards only route. A routine returns the event that names its decision. A guard only chooses a transition, from data that is already there.
|
|
15
|
+
|
|
16
|
+
## How it works
|
|
17
|
+
|
|
18
|
+
| Place | What it is for | Who reads it | When it is saved |
|
|
19
|
+
|---|---|---|---|
|
|
20
|
+
| The context, `ctx["key"]` | The data of the token: all that later states need. | Each routine of the token, and the guards. | With the event, or not at all. |
|
|
21
|
+
| An event's payload | Why the token moved, for example a `Verdict`. | The guards, and the history. Not the routines. | With the event, in the history. |
|
|
22
|
+
| `into="key"` on an event | Keeps the event's payload in the context, as `ctx["key"]`. | Each later routine, through the context. | With the event, before the guards run. |
|
|
23
|
+
| `ctx.memory` | The routine's own bookkeeping, for example an agent's session id. | The routine of the same state, on a retry or a later visit. | At once. |
|
|
24
|
+
| `ctx.note(text)` | One line of progress, for people. | People, in the history. | At once. |
|
|
25
|
+
| `inputs=` on a parallel state | Data that goes down, from the parent's context to each child's context. | The routines of the child. | When the child starts. |
|
|
26
|
+
| `into="key"` on a parallel state | Data that comes back up: the `Branches` of the join, with each child's context. | Each later routine of the parent. | When the join is met. |
|
|
27
|
+
|
|
28
|
+
Some facts:
|
|
29
|
+
|
|
30
|
+
- A routine knows which event brought the token in: `ctx.entered_by.name`, for example `timeout`. It does not get that event's payload. For the payload, declare `into=`.
|
|
31
|
+
- `into=` works for each source of the event: a routine's report, `stateous token fire`, a timer and a resume.
|
|
32
|
+
- If a routine writes the same key that the event's `into=` names, the payload wins.
|
|
33
|
+
- `stateous compile` checks `into=`. The field must be in the context model, and its type must take the payload model, for example `Verdict` or `Verdict | None`.
|
|
34
|
+
- `stateous token show` prints the context, so you can see what each routine wrote.
|
|
35
|
+
|
|
36
|
+
## Example
|
|
37
|
+
|
|
38
|
+
This is a `triage` workflow for support tickets. `classify` decides if a ticket is urgent. `escalate` pages an engineer. `answer` writes the reply.
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
# triage/schemas.py
|
|
42
|
+
from pydantic import BaseModel
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class Ticket(BaseModel):
|
|
46
|
+
title: str
|
|
47
|
+
body: str
|
|
48
|
+
on_call: str = "" # escalate writes it
|
|
49
|
+
reply: str = "" # answer writes it
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The rule "the body has the word 'down'" is a decision. So a routine makes it, and returns `urgent` or `normal`. A guard does not search the text.
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
# triage-supervisor/classify.py
|
|
56
|
+
import re
|
|
57
|
+
|
|
58
|
+
from stateous import on_state
|
|
59
|
+
|
|
60
|
+
from contract import TicketContext, events, states
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@on_state(states.classify)
|
|
64
|
+
def classify(ctx: TicketContext) -> events.urgent | events.normal:
|
|
65
|
+
if re.search(r"\bdown\b", ctx["body"].lower()):
|
|
66
|
+
return events.urgent()
|
|
67
|
+
return events.normal()
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`escalate` writes the engineer's name to the context. `answer`, a later state, reads it there:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
# triage-supervisor/escalate.py
|
|
74
|
+
from stateous import on_state
|
|
75
|
+
|
|
76
|
+
from contract import TicketContext, events, states
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@on_state(states.escalate)
|
|
80
|
+
def escalate(ctx: TicketContext) -> events.paged:
|
|
81
|
+
ctx["on_call"] = "Ada"
|
|
82
|
+
ctx.note("paged Ada")
|
|
83
|
+
return events.paged()
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
# triage-supervisor/answer.py
|
|
88
|
+
from stateous import on_state
|
|
89
|
+
|
|
90
|
+
from contract import TicketContext, events, states
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
@on_state(states.answer)
|
|
94
|
+
def answer(ctx: TicketContext) -> events.replied:
|
|
95
|
+
if ctx["on_call"]:
|
|
96
|
+
ctx["reply"] = f"This is urgent. {ctx['on_call']} works on it now."
|
|
97
|
+
else:
|
|
98
|
+
ctx["reply"] = "Thank you. We reply soon."
|
|
99
|
+
return events.replied()
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`stateous token show TICKET-1` then prints the context with `on_call` and `reply`.
|
|
103
|
+
|
|
104
|
+
## Guarantees
|
|
105
|
+
|
|
106
|
+
- A routine's context changes and an event's `into=` are saved in one transaction with the event, or not at all.
|
|
107
|
+
- A routine never sees a payload. So it cannot depend on data that the token does not keep.
|
|
108
|
+
- `stateous compile` refuses an `into=` whose field is not in the context model. It also refuses a field whose type does not take the payload.
|
|
109
|
+
|
|
110
|
+
## See also
|
|
111
|
+
|
|
112
|
+
- [Context, notes and memory](context-notes-memory.md): each field of `ctx`.
|
|
113
|
+
- [Guards](guards.md): what a guard can read.
|
|
114
|
+
- [Parallel and nested work](parallel.md): `inputs=` and `into=` on a parallel state.
|
|
115
|
+
- [The model](model.md): the words context, payload and event.
|
|
@@ -6,10 +6,12 @@ A guard is a small condition in `when=` that chooses which transition an event t
|
|
|
6
6
|
|
|
7
7
|
## Why it exists
|
|
8
8
|
|
|
9
|
-
One
|
|
9
|
+
One event can lead to different places. For example, a failed test run goes back to `coding` two times, but the third failure ends the token. The routine must not know this rule, because it does not see the graph.
|
|
10
10
|
|
|
11
11
|
So the graph holds the rule, as a guard on the transition. Stateous checks the guards when you compile, so a token never has two ways to go.
|
|
12
12
|
|
|
13
|
+
Routines decide, and guards only route. A decision about the work, such as "the body of the ticket has the word 'down'", is the work of a routine. The routine returns the event that names the decision, for example `urgent` or `normal`. A guard only chooses a transition from data that is already there: a count, a field of the payload, a field of the context. So the guard language has no text search and no arithmetic. See [Where data goes](data.md).
|
|
14
|
+
|
|
13
15
|
## How it works
|
|
14
16
|
|
|
15
17
|
A guard is an expression in a small language. It is not Python, and nothing runs it as Python. It can use these items:
|
|
@@ -38,6 +40,14 @@ When an event comes, the control plane looks at the transitions from the token's
|
|
|
38
40
|
2. If no guard matches, the token takes the transition with `otherwise=True`.
|
|
39
41
|
3. If no guard matches and there is no `otherwise=True`, the control plane refuses the event. The token stays where it is.
|
|
40
42
|
|
|
43
|
+
**The rule of `otherwise=True`.** This is the one place where the docs give this rule:
|
|
44
|
+
|
|
45
|
+
- A transition that is the only one from its state on its event needs no guard and no `otherwise=True`.
|
|
46
|
+
- When a state has two or more transitions on one event, each has a guard, except at most one. That one has no guard, and it must have `otherwise=True`: it is the fallback.
|
|
47
|
+
- The fallback is optional. With no fallback, an event that no guard matches is refused.
|
|
48
|
+
|
|
49
|
+
Compile stops if a transition breaks this rule.
|
|
50
|
+
|
|
41
51
|
### The overlap check
|
|
42
52
|
|
|
43
53
|
`stateous compile` makes sure that the guards on one state and one event never overlap. Two guards overlap when some data can make both of them true.
|
|
@@ -46,8 +56,6 @@ If two guards can overlap, compile stops with an error, and it gives an example
|
|
|
46
56
|
|
|
47
57
|
Compile also stops when it cannot prove that two guards never overlap. This occurs when a guard compares two values with each other, orders a list, or uses `branches`. Then make one transition the fallback with `otherwise=True`.
|
|
48
58
|
|
|
49
|
-
Next to transitions with guards, a transition without a guard must have `otherwise=True`. Compile stops if it does not.
|
|
50
|
-
|
|
51
59
|
## Example
|
|
52
60
|
|
|
53
61
|
In `sdlc`, the event `failed` has two transitions from `testing`:
|
|
@@ -10,7 +10,7 @@ A long process has many steps, and each step can take minutes or days. A step ca
|
|
|
10
10
|
|
|
11
11
|
Stateous puts the process in one graph. The graph tells all the places where a run can be, and all the ways to go on. A run never moves in a way that the graph does not show.
|
|
12
12
|
|
|
13
|
-
This page defines each word
|
|
13
|
+
This page defines each word that you need to build with Stateous. Every other page uses each word in the same sense. The words of how Stateous works inside, such as lease and outbox, are on [The words inside](../inside/words.md).
|
|
14
14
|
|
|
15
15
|
## How it works
|
|
16
16
|
|
|
@@ -44,7 +44,7 @@ Two states are Stateous's own. `START` is where each token begins, and `END` is
|
|
|
44
44
|
|
|
45
45
|
### event
|
|
46
46
|
|
|
47
|
-
|
|
47
|
+
What happened in a state, for example `passed` or `failed`. Only an event moves a token. Its name and its payload say why the token moved.
|
|
48
48
|
|
|
49
49
|
Stateous has three events of its own: `timeout`, `error` and `joined`. Your transitions use them by name. You cannot declare them, and you cannot fire them.
|
|
50
50
|
|
|
@@ -62,25 +62,20 @@ The status is `active`, `paused`, `completed`, `failed` or `cancelled`. A token
|
|
|
62
62
|
|
|
63
63
|
### context
|
|
64
64
|
|
|
65
|
-
The business data of a token, for example the path of a checkout. A pydantic model gives its fields. A routine reads it as `ctx["key"]`, and can write it.
|
|
65
|
+
The business data of a token, for example the path of a checkout. A pydantic model gives its fields. A routine reads it as `ctx["key"]`, and can write it. It is the only data that a routine reads and writes. See [Where data goes](data.md).
|
|
66
66
|
|
|
67
67
|
### payload
|
|
68
68
|
|
|
69
|
-
The data of one event, for example the numbers of tests that passed and failed. A pydantic model gives its fields. An event without a payload model has no payload.
|
|
69
|
+
The data of one event, for example the numbers of tests that passed and failed. A pydantic model gives its fields. An event without a payload model has no payload. Guards and the history read the payload. To keep it for later states, the event declares `into="key"`, and the context keeps it as `ctx["key"]`.
|
|
70
70
|
|
|
71
71
|
### task
|
|
72
72
|
|
|
73
73
|
"Do state S for token T". The control plane queues one task each time a token enters a state. A supervisor claims the task and runs its routine.
|
|
74
74
|
|
|
75
|
-
|
|
76
75
|
### visit
|
|
77
76
|
|
|
78
77
|
One stay of a token in one state. The first time that a token enters a state is visit 1, the next time is visit 2. A routine reads it as `ctx.visit`. The history shows it, for example `entered coding (visit 2)`.
|
|
79
78
|
|
|
80
|
-
### claim
|
|
81
|
-
|
|
82
|
-
A supervisor's request for a task of the states that it serves. The control plane answers with a grant: one queued task, its token, its visit, its attempt and its context. The task is then claimed.
|
|
83
|
-
|
|
84
79
|
### routine
|
|
85
80
|
|
|
86
81
|
Your function that does the work of one state. It gets the token's context as `ctx`, and it returns an event. It is in the supervisor's folder, and it is marked with `@on_state(states.X)`.
|
|
@@ -97,45 +92,22 @@ The process that keeps every token, and chooses each next state. You start it wi
|
|
|
97
92
|
|
|
98
93
|
The compiled workflow, as JSON, for example `sdlc/build/sdlc.json`. `stateous compile` writes it, and `stateous serve` serves it.
|
|
99
94
|
|
|
100
|
-
|
|
101
|
-
### checksum
|
|
102
|
-
|
|
103
|
-
The hash of the whole graph file, for example `sha256:...`. Each change to the graph file changes it. A supervisor's `contract.py` is for one checksum.
|
|
104
|
-
|
|
105
|
-
### structure
|
|
106
|
-
|
|
107
|
-
The hash of the graph file without the `timeout=` and `retries=` of its states. A database serves one structure at a time. See [Change a workflow](../how-to/change-a-workflow.md).
|
|
108
|
-
|
|
109
95
|
### contract
|
|
110
96
|
|
|
111
97
|
The file `contract.py` in the supervisor's folder. `stateous init supervisor` writes it from the graph. It gives the states, the events that each state can emit, and the models. It is all that a supervisor knows of the workflow.
|
|
112
98
|
|
|
113
|
-
### ledger
|
|
114
|
-
|
|
115
|
-
The history of each token. Each change adds one row, and the rows are never changed. `stateous token show` prints the ledger of a token.
|
|
116
|
-
|
|
117
99
|
### guard
|
|
118
100
|
|
|
119
|
-
A condition on a transition, written in `when=`. It reads the context, the payload and counts of events. See [Guards](guards.md).
|
|
101
|
+
A condition on a transition, written in `when=`. It reads the context, the payload and counts of events. A guard only routes: a routine makes the decisions. See [Guards](guards.md).
|
|
120
102
|
|
|
121
103
|
### timer
|
|
122
104
|
|
|
123
105
|
An event that the clock fires later, if the token is still in the same state. A state's `timeout=` is a timer too. See [Timers and timeouts](timers.md).
|
|
124
106
|
|
|
125
|
-
### lease
|
|
126
|
-
|
|
127
|
-
The time for which a supervisor holds a claimed task. A heartbeat renews it. See [Tasks and routines](tasks-and-routines.md).
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
### heartbeat
|
|
131
|
-
|
|
132
|
-
The message that a supervisor sends every 30 seconds for all the tasks that it holds. It renews their leases. Its answer names each task that the supervisor does not hold now, for example because the token left the state.
|
|
133
|
-
|
|
134
107
|
### attempt
|
|
135
108
|
|
|
136
109
|
One try of a task. The first claim is attempt 1. When an attempt fails and the state has retries left, the next claim is attempt 2.
|
|
137
110
|
|
|
138
|
-
|
|
139
111
|
### retries
|
|
140
112
|
|
|
141
113
|
The number of more attempts that a state gives after a failed attempt: `retries=2` gives three attempts in all. After the last failed attempt, the token gets the event `error`.
|
|
@@ -156,24 +128,10 @@ A state whose work is other workflows, which run at the same time. It has no tas
|
|
|
156
128
|
|
|
157
129
|
A token that a parallel state starts, one for each workflow of the state. Its parent is the token in the parallel state.
|
|
158
130
|
|
|
159
|
-
|
|
160
131
|
### join
|
|
161
132
|
|
|
162
133
|
The rule that tells when a parallel state is done. `join="all"` waits for each child token to end. `join="any"` continues when the first child token ends. When the join is met, the control plane fires `joined` on the parent.
|
|
163
134
|
|
|
164
|
-
### outbox
|
|
165
|
-
|
|
166
|
-
The supervisor's local file of messages that the control plane did not answer yet: `.stateous/outbox.db`. See [Reliability](reliability.md).
|
|
167
|
-
|
|
168
|
-
### idempotency key
|
|
169
|
-
|
|
170
|
-
A key that you give with an event from outside. A second event with the same key applies nothing, and gets the answer "duplicate". See [Reliability](reliability.md).
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
### held event
|
|
174
|
-
|
|
175
|
-
An event that comes to a paused token. The control plane keeps it, and applies it on resume, in the order of arrival. The history shows `done held while paused`. See [Pause, resume and cancel](pause-resume-cancel.md).
|
|
176
|
-
|
|
177
135
|
## Example
|
|
178
136
|
|
|
179
137
|
The `sdlc` workflow has two states. In `coding`, an agent writes code. In `testing`, a routine runs the tests.
|
|
@@ -240,7 +198,7 @@ stateDiagram-v2
|
|
|
240
198
|
- A token is in one state at a time. Only an event moves it, and only along a transition of the graph.
|
|
241
199
|
- An event that the token's state cannot take is refused. The token stays where it is, and the ledger records the refusal.
|
|
242
200
|
- The ledger keeps each change. Stateous never changes or deletes a row of the ledger.
|
|
243
|
-
- Not guaranteed: that your routine does the right work. Stateous makes sure only that its
|
|
201
|
+
- Not guaranteed: that your routine does the right work. Stateous makes sure only that its event is one that the graph allows.
|
|
244
202
|
|
|
245
203
|
## See also
|
|
246
204
|
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Notices
|
|
2
|
+
|
|
3
|
+
## In one sentence
|
|
4
|
+
|
|
5
|
+
A notice tells your code that a token changed: an event was accepted, a token ended, or a task failed for the last time.
|
|
6
|
+
|
|
7
|
+
## Why it exists
|
|
8
|
+
|
|
9
|
+
Workflows know nothing about each other. Your code decides that the end of workflow A starts workflow B. Your code also updates a UI, or sends a message to a queue.
|
|
10
|
+
|
|
11
|
+
So your code must hear what each workflow does. Polling `stateous token show` is slow, and it can miss a change. A notice is kept in the database until your handler has it.
|
|
12
|
+
|
|
13
|
+
## How it works
|
|
14
|
+
|
|
15
|
+
Notices are a setting of the database. Turn them on with `stateous migrate --notices`, or with `ControlPlane.migrate(notices=True)`. Each control plane reads the setting when it opens.
|
|
16
|
+
|
|
17
|
+
When notices are on, each of these changes writes a notice in the same transaction as the change:
|
|
18
|
+
|
|
19
|
+
| Kind | When |
|
|
20
|
+
|---|---|
|
|
21
|
+
| `event` | An event was accepted. A held event counts when a resume applies it. A rejected event gives no notice. |
|
|
22
|
+
| `completed`, `failed`, `cancelled` | A token ended so. A child token of a parallel state gives one too, with its `parent`. |
|
|
23
|
+
| `task_failed` | A task failed for the last time. A failure that will retry gives no notice. |
|
|
24
|
+
|
|
25
|
+
`ControlPlane.deliver_notices(handler)` gives the waiting notices to your handler. It deletes each notice after the handler returns. `run_notices(handler)` does this in your event loop until `close()`.
|
|
26
|
+
|
|
27
|
+
Some facts:
|
|
28
|
+
|
|
29
|
+
- **At least once.** If the process stops before the delete is saved, the handler gets the notice again.
|
|
30
|
+
- **In order for each token family.** A family is a top token and its child tokens. Between families there is no order.
|
|
31
|
+
- **Labels.** `notice.labels` are the token's labels, so a handler can route a notice to its tenant.
|
|
32
|
+
- **The id is stable.** `notice.id` is the same at each delivery. Use it as an idempotency key.
|
|
33
|
+
- **A failing handler.** If the handler raises, its family's notices come again on the next call. The other families go on.
|
|
34
|
+
- **Keep the handler short.** It runs inside a database transaction. Hand slow work to your own queue.
|
|
35
|
+
- **On SQLite**, the handler must not call the same control plane. It can call another control plane.
|
|
36
|
+
|
|
37
|
+
## Example
|
|
38
|
+
|
|
39
|
+
When a token of `plan` ends, start a token of `tasks` for the same project:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from stateous import ControlPlane, Notice
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def connect(plan: ControlPlane, tasks: ControlPlane) -> None:
|
|
46
|
+
"""Start `tasks` for each `plan` token that completes."""
|
|
47
|
+
|
|
48
|
+
def handler(notice: Notice) -> None:
|
|
49
|
+
if notice.kind == "completed" and notice.parent is None:
|
|
50
|
+
tasks.start(f"tasks-of-{notice.token}", {"plan": notice.token})
|
|
51
|
+
|
|
52
|
+
plan.deliver_notices(handler)
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
To start a token that exists returns it, unchanged. So a notice that comes twice starts `tasks` once.
|
|
56
|
+
|
|
57
|
+
## Guarantees
|
|
58
|
+
|
|
59
|
+
- A change and its notice are saved in one transaction, or neither is.
|
|
60
|
+
- A notice is deleted only after the handler returned with no error.
|
|
61
|
+
- Two deliverers on one database never get the same family at the same time.
|
|
62
|
+
|
|
63
|
+
## See also
|
|
64
|
+
|
|
65
|
+
- [Embed a control plane](../how-to/embed-a-control-plane.md): a control plane in your own service.
|
|
66
|
+
- [Reliability](reliability.md): the ledger, and the other mechanisms.
|
|
67
|
+
- [The commands](../reference/cli.md): `stateous migrate --notices`.
|
|
68
|
+
- [The Python API](../reference/python.md): `Notice` and `ControlPlane.deliver_notices`.
|
|
@@ -47,9 +47,11 @@ When the join is met, the control plane fires the event `joined` on the parent.
|
|
|
47
47
|
- `token`: the child's id;
|
|
48
48
|
- `status`: `completed` or `failed`;
|
|
49
49
|
- `final`: the state that the child was in when it ended;
|
|
50
|
-
- `
|
|
50
|
+
- `context`: the child's context when it ended.
|
|
51
51
|
|
|
52
|
-
A guard on `joined` can use `branches.all(...)` and `branches.any(...)`. In the parentheses, use `workflow`, `token`, `status`, `final` and `
|
|
52
|
+
A guard on `joined` can use `branches.all(...)` and `branches.any(...)`. In the parentheses, use `workflow`, `token`, `status`, `final` and `context.field`. `stateous compile` checks that a child workflow of the state has the field. The guard can also use `ctx` and `count`.
|
|
53
|
+
|
|
54
|
+
To keep the results of the children for later states, give the parallel state `into="reviews"`. The parent's context then keeps the payload of `joined` as `ctx["reviews"]`. Its type in the context model is `Branches` (from `stateous`), or `Branches | None`. So data goes down to the children with `inputs=`, and comes back with `into=`, always through the context. See [Where data goes](data.md).
|
|
53
55
|
|
|
54
56
|
`stateous compile` cannot prove that two guards with `branches` never overlap. So give the guard to one transition, and make the other the fallback with `otherwise=True`. If no transition takes `joined`, the parent fails.
|
|
55
57
|
|
|
@@ -103,6 +103,10 @@ error: the control plane at http://127.0.0.1:8080 refused (409): token 'TICKET-3
|
|
|
103
103
|
|
|
104
104
|
```text
|
|
105
105
|
TICKET-3: testing, cancelled
|
|
106
|
+
context:
|
|
107
|
+
{
|
|
108
|
+
"repo": "acme/api"
|
|
109
|
+
}
|
|
106
110
|
22:39:47 #1 started
|
|
107
111
|
22:39:47 #2 __started__ in START
|
|
108
112
|
22:39:47 #3 entered coding
|
|
@@ -28,7 +28,9 @@ These are the seven mechanisms:
|
|
|
28
28
|
|
|
29
29
|
The control plane keeps all of its data in one database. Each change to a token is one transaction. The transaction changes the token, its tasks and its timers, and it adds rows to the ledger. Either all of it is saved, or none of it.
|
|
30
30
|
|
|
31
|
-
Each change locks the token, so one token moves one step at a time. One control plane serves one database. A second control plane on the same
|
|
31
|
+
Each change locks the token, so one token moves one step at a time. One control plane serves one namespace of a database. A second control plane on the same namespace does not start. On SQLite, a namespace is a database file. On Postgres, several replicas can serve one namespace together: see [Run replicas](../how-to/run-replicas.md).
|
|
32
|
+
|
|
33
|
+
With notices on, a change also writes its [notice](notices.md) in the same transaction. Your handler gets each notice at least once.
|
|
32
34
|
|
|
33
35
|
### Leases and attempts
|
|
34
36
|
|
|
@@ -130,7 +132,7 @@ build-box-2 took task 1 (attempt 2)
|
|
|
130
132
|
|
|
131
133
|
## See also
|
|
132
134
|
|
|
133
|
-
- [The
|
|
135
|
+
- [The words inside](../inside/words.md): [ledger](../inside/words.md#ledger), [lease](../inside/words.md#lease), [outbox](../inside/words.md#outbox) and [idempotency key](../inside/words.md#idempotency-key).
|
|
134
136
|
- [Tasks and routines](tasks-and-routines.md): claims, heartbeats and attempts.
|
|
135
137
|
- [Context, notes and memory](context-notes-memory.md): the routine's memory.
|
|
136
138
|
- [Pause, resume and cancel](pause-resume-cancel.md).
|
|
@@ -20,7 +20,7 @@ A task goes through these steps:
|
|
|
20
20
|
4. **Heartbeat.** While the routine runs, the supervisor sends a heartbeat every 30 seconds. One heartbeat names all of its running tasks, and it renews their leases.
|
|
21
21
|
5. **Report.** The routine returns, and the supervisor reports the outcome. An event moves the token, and the task is done.
|
|
22
22
|
|
|
23
|
-
The supervisor reports one of three kinds
|
|
23
|
+
The supervisor reports the **outcome** of the task. An outcome is one of three kinds:
|
|
24
24
|
|
|
25
25
|
| Outcome | When | What the control plane does |
|
|
26
26
|
|---|---|---|
|
|
@@ -128,9 +128,9 @@ build-box-2 took task 1 (attempt 2)
|
|
|
128
128
|
|
|
129
129
|
## See also
|
|
130
130
|
|
|
131
|
-
- [The model](model.md): the words [task](model.md#task), [routine](model.md#routine), [lease](
|
|
131
|
+
- [The model](model.md): the words [task](model.md#task), [routine](model.md#routine), [lease](../inside/words.md#lease) and [attempt](model.md#attempt).
|
|
132
132
|
- [The two sides](two-sides.md): what crosses the network.
|
|
133
133
|
- [Timers and timeouts](timers.md): a state's `timeout=` covers all attempts.
|
|
134
134
|
- [Context, notes and memory](context-notes-memory.md): every field of `ctx`.
|
|
135
135
|
- [Reliability](reliability.md): leases, the outbox, and what happens when a supervisor stops.
|
|
136
|
-
- [Write a routine](../how-to/write-a-routine.md): mark a routine, return an
|
|
136
|
+
- [Write a routine](../how-to/write-a-routine.md): mark a routine, return an event, and fail.
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Tenancy
|
|
2
|
+
|
|
3
|
+
## In one sentence
|
|
4
|
+
|
|
5
|
+
Labels scope tokens and tasks to your tenants, and your own authorizer decides who may do what with them.
|
|
6
|
+
|
|
7
|
+
## Why it exists
|
|
8
|
+
|
|
9
|
+
Stateous does not know what a user, a tenant or a plan is. Your product knows. One product keeps every tenant in one workflow. Another product runs a control plane for each tenant.
|
|
10
|
+
|
|
11
|
+
So Stateous gives two small tools, and no tenancy model. Your code decides how to use them.
|
|
12
|
+
|
|
13
|
+
## How it works
|
|
14
|
+
|
|
15
|
+
**Labels.** A token gets labels at start, and a routine reads them as `ctx.labels`, for example `{"user": "u42", "project": "p7"}`.
|
|
16
|
+
|
|
17
|
+
- A token has at most 16 labels. A key is a lower-case letter, then up to 63 lower-case letters, digits, `_`, `.` or `-`. A value is a string of 1 to 256 characters.
|
|
18
|
+
- Labels never change after the start. A child token of a parallel state gets its parent's labels.
|
|
19
|
+
- A claim with labels takes only a task whose token has each of them. A claim with no labels takes any task.
|
|
20
|
+
- A list of tokens can filter by labels. Notices and "task ready" carry the labels.
|
|
21
|
+
|
|
22
|
+
**The authorizer.** `ControlPlane(..., authorize=fn)` calls `fn(caller, action, labels)` for each call. It returns True to allow. A refusal raises `Forbidden`, with the code `forbidden`; over HTTP it is 403.
|
|
23
|
+
|
|
24
|
+
| Action | Labels that it gets |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `start` | The labels that the start gives. |
|
|
27
|
+
| `claim` | The labels that the claim asks for, `{}` for none. |
|
|
28
|
+
| `report`, `note`, `memory`, `heartbeat` | The labels of the task's token. A refused heartbeat task counts as lost. |
|
|
29
|
+
| `fire`, `pause`, `resume`, `cancel`, `read` | The labels of the token. A list keeps only the tokens that the caller may read. |
|
|
30
|
+
|
|
31
|
+
**Ids for each scope.** `ControlPlane(..., scope=["user"])` names the labels of a scope, at most 4. A token id is then unique only within those labels' values: user u1 and user u2 can both have `T-1`.
|
|
32
|
+
|
|
33
|
+
- A call names its scope with `scope=`, or your function `scope_of(caller)` gives it.
|
|
34
|
+
- A call never reaches another scope: such a token or task is not found (404). A list and a claim stay in the scope.
|
|
35
|
+
- A start takes its scope from its labels. A start whose labels name another scope than the caller's is `Forbidden`.
|
|
36
|
+
- `ALL_SCOPES` lets a trusted caller act across scopes, for example an admin view. An id that is in several scopes then needs `scope=`.
|
|
37
|
+
- The namespace keeps its scope. Another scope is refused with `ScopeConflict` while the namespace has any token.
|
|
38
|
+
- Inside, Stateous keeps a key made of a hash of the scope and the id. Every id that you see is the plain id.
|
|
39
|
+
|
|
40
|
+
**Ids that Stateous makes.** A start with no id gets a ULID: 26 characters, and ids made later sort later. With `key=`, an idempotency key, a retry in the same scope gets the same token.
|
|
41
|
+
|
|
42
|
+
**The caller.** Stateous never makes a caller. Each transport passes one through:
|
|
43
|
+
|
|
44
|
+
- HTTP: `create_app(plane, caller=fn)`, where `fn(request)` reads, for example, a user id that your gateway checked.
|
|
45
|
+
- In process: `InProcess(plane, caller=...)`.
|
|
46
|
+
- Your queue: `answer(plane, call, caller=...)`.
|
|
47
|
+
- Your own code: the keyword `caller` of each `ControlPlane` method.
|
|
48
|
+
|
|
49
|
+
**Entitlements.** `plane.count_claimed(labels)` counts the tasks claimed now for those labels. Your authorizer can use it, for example to allow about 3 tasks at a time on a plan. It is a soft limit: two claims at the same moment can both see 2, and both claim.
|
|
50
|
+
|
|
51
|
+
## Example
|
|
52
|
+
|
|
53
|
+
Each user may act only on the tokens of that user. The service itself calls with no caller:
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
from collections.abc import Mapping
|
|
57
|
+
|
|
58
|
+
from stateous.control.access import Action
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def only_own(caller: object, action: Action, labels: Mapping[str, str]) -> bool:
|
|
62
|
+
"""A user may act only on the tokens with the label `user` of that user."""
|
|
63
|
+
return caller is None or labels.get("user") == caller
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
A supervisor of user `u42` then claims with `labels={"user": "u42"}`, and its requests carry `u42` as the caller.
|
|
67
|
+
|
|
68
|
+
## Guarantees
|
|
69
|
+
|
|
70
|
+
- A refused call changes nothing.
|
|
71
|
+
- A claim with labels never takes a task of a token without those labels.
|
|
72
|
+
- A waiting claim with labels is not woken by a task of other labels.
|
|
73
|
+
|
|
74
|
+
## See also
|
|
75
|
+
|
|
76
|
+
- [Run replicas](../how-to/run-replicas.md): several control planes of one workflow.
|
|
77
|
+
- [Transports](transports.md): how the caller reaches the control plane.
|
|
78
|
+
- [Embed a control plane](../how-to/embed-a-control-plane.md): `ControlPlane` in your service.
|
|
79
|
+
- [The Python API](../reference/python.md): `Forbidden`, `Action` and `Authorize`.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Transports
|
|
2
|
+
|
|
3
|
+
## In one sentence
|
|
4
|
+
|
|
5
|
+
A transport carries the calls of a supervisor to a control plane: in one process, over HTTP, through a gateway, or over your own queue.
|
|
6
|
+
|
|
7
|
+
## Why it exists
|
|
8
|
+
|
|
9
|
+
Stateous must not decide how the parts of your product talk. One team runs everything on one computer. Another team puts a gateway in front of each service, or sends each message through a broker.
|
|
10
|
+
|
|
11
|
+
So Stateous keeps three things apart:
|
|
12
|
+
|
|
13
|
+
| Layer | What it is | Who owns it |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| The protocol | The six calls of a supervisor, and their rules: leases, attempts, request ids, refusal codes, the outbox. | Stateous. It does not change. |
|
|
16
|
+
| The transport | How one call reaches the control plane, and how its reply comes back. | You. Stateous ships two. |
|
|
17
|
+
| The policy | Who may claim which tasks: users, tenants, authentication. | You. |
|
|
18
|
+
|
|
19
|
+
## How it works
|
|
20
|
+
|
|
21
|
+
A supervisor makes six calls: `health`, `claim`, `report`, `heartbeat`, `note` and `set_memory`. A transport makes **one attempt** for each call. It returns the reply, or it raises one of two errors:
|
|
22
|
+
|
|
23
|
+
- `Refused`: the control plane answered no. It has a stable `code`, for example `task_not_held`. To try again does not help.
|
|
24
|
+
- `NotReached`: no answer came. The call may or may not have arrived.
|
|
25
|
+
|
|
26
|
+
The supervisor tries a call that is not reached again, after 1, 2, 4, 8, 16, then every 30 seconds. A claim sent again keeps its request id, so a lost reply never gives a task twice. A transport does not copy this logic.
|
|
27
|
+
|
|
28
|
+
Two codes mean "try again": `database_busy` and `not_serving`. A transport raises `NotReached` for them.
|
|
29
|
+
|
|
30
|
+
Stateous ships two transports:
|
|
31
|
+
|
|
32
|
+
- **HTTP**, the default of `stateous supervise`. It takes extra headers, for example a bearer token, and a URL with a path, for a gateway.
|
|
33
|
+
- **In process**, for a supervisor in the control plane's process. `serve --supervise` uses it.
|
|
34
|
+
|
|
35
|
+
For any other wire, `CallingTransport` needs one function: send a `Call`, give back its `Reply`. Both are plain JSON. On the control plane's side, `answer(plane, call)` gives the reply.
|
|
36
|
+
|
|
37
|
+
**Claims that wait.** A claim can wait up to 30 seconds at the control plane for a task. The control plane wakes it when a task is ready. So a supervisor does not have to poll. `ControlPlane.on_task_ready` tells your own code when a task is ready, with its state and its token's labels. Use it, for example, to publish to a queue for that tenant.
|
|
38
|
+
|
|
39
|
+
## Example
|
|
40
|
+
|
|
41
|
+
A transport over a queue, in a few lines. The `send` function is yours:
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
from collections.abc import Awaitable, Callable
|
|
45
|
+
|
|
46
|
+
from stateous.transport import Call, CallingTransport, Reply
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def queue_transport(send: Callable[[Call], Awaitable[Reply]]) -> CallingTransport:
|
|
50
|
+
"""A supervisor's transport over your own queue."""
|
|
51
|
+
return CallingTransport(send, where="the jobs queue")
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
[Write a transport](../how-to/write-a-transport.md) shows both sides, and the test kit.
|
|
55
|
+
|
|
56
|
+
## Guarantees
|
|
57
|
+
|
|
58
|
+
- A transport never decides who holds a task. The control plane's database decides, with leases and attempts.
|
|
59
|
+
- A claim sent again with the same request id gets the same task. A lost reply loses no task.
|
|
60
|
+
- `stateous.testing.check_transport` checks that a transport keeps these rules. It cannot see every fault, for example a reply that a broker loses only under load.
|
|
61
|
+
|
|
62
|
+
## See also
|
|
63
|
+
|
|
64
|
+
- [Write a transport](../how-to/write-a-transport.md): a queue transport, step by step.
|
|
65
|
+
- [Run supervisors](../how-to/run-supervisors.md): HTTP, gateways and headers.
|
|
66
|
+
- [Embed a control plane](../how-to/embed-a-control-plane.md): the control plane in your own service.
|
|
67
|
+
- [The HTTP API](../reference/http.md): the routes, and the codes of each refusal.
|
|
@@ -12,7 +12,7 @@ So Stateous has two sides. The control plane decides, and the supervisors do the
|
|
|
12
12
|
|
|
13
13
|
The supervisor never sees the graph, for two reasons:
|
|
14
14
|
|
|
15
|
-
- A routine cannot depend on the next state. It can only return an
|
|
15
|
+
- A routine cannot depend on the next state. It can only return an event, so you can change the graph without a change to the routines.
|
|
16
16
|
- A supervisor has only the information that its work needs. The rest of the process stays on the control plane.
|
|
17
17
|
|
|
18
18
|
## How it works
|
|
@@ -27,7 +27,7 @@ Each side is a folder of its own.
|
|
|
27
27
|
The graph file stays on the control plane's side. Two things cross to the supervisor's side:
|
|
28
28
|
|
|
29
29
|
- **The contract.** `stateous init supervisor` writes `contract.py`. It gets the graph from the control plane with `GET /workflow`, or it reads a local graph file or `flow.py`. The contract keeps only the states, the events that each state can emit, and the models.
|
|
30
|
-
- **
|
|
30
|
+
- **The calls.** The supervisor claims tasks, sends heartbeats, and reports outcomes. It also sends notes and memory writes. `stateous supervise` sends them over HTTP, to the control plane's URL in `stateous.yaml`. A program can send them over another wire: see [Transports](transports.md).
|
|
31
31
|
|
|
32
32
|
```mermaid
|
|
33
33
|
flowchart LR
|