stateous 0.1.0__py3-none-any.whl

stateous/__init__.py

@@ -0,0 +1,24 @@
+"""Stateous: a process as a graph of states.
+
+A control plane keeps every token of it durable and decides each next state. A
+supervisor, on any computer, does the work and reports what happened. Everything
+a user imports comes from here.
+"""
+
+from stateous.client import Client
+from stateous.model.context import Context
+from stateous.model.contract import OutcomeError, StateRef, on_state
+from stateous.model.events import Occurrence
+from stateous.model.workflow import END, START, Workflow
+
+__all__ = [
+    "END",
+    "START",
+    "Client",
+    "Context",
+    "Occurrence",
+    "OutcomeError",
+    "StateRef",
+    "Workflow",
+    "on_state",
+]

stateous/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m stateous`: the same as the `stateous` command."""
+
+from stateous.cli.main import main
+
+if __name__ == "__main__":
+    main()

stateous/cli/__init__.py

@@ -0,0 +1 @@
+"""The `stateous` command."""

stateous/cli/errors.py

@@ -0,0 +1,39 @@
+"""How a command fails: one plain sentence on stderr, and exit code 1. Never a
+traceback."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import NoReturn, ParamSpec, TypeVar
+
+import typer
+
+from stateous.client import ClientError
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class CommandError(Exception):
+    """A command cannot go on. The message is one plain sentence."""
+
+
+def exit_with(message: str) -> NoReturn:
+    """One plain sentence to stderr, then exit code 1. Never a traceback."""
+    typer.echo(f"error: {message}", err=True)
+    raise typer.Exit(1)
+
+
+def reported(command: Callable[P, R]) -> Callable[P, R]:
+    """Show an expected failure as `error: <sentence>` and exit 1."""
+
+    @functools.wraps(command)
+    def run(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return command(*args, **kwargs)
+        except (CommandError, ClientError) as error:
+            typer.echo(f"error: {error}", err=True)
+            raise typer.Exit(1) from None
+
+    return run

stateous/cli/main.py

@@ -0,0 +1,219 @@
+"""The `stateous` command: compile, serve, init, supervise and token.
+
+The commands import what they need when they run. `serve` and `supervise` import
+the server, the database and the supervisor (`stateous.cli.running`). So `--help`,
+`token ...`, `compile` and `init` start fast."""
+
+from __future__ import annotations
+
+import errno
+import os
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Annotated, Any, TextIO, cast
+
+import typer
+
+from stateous.cli.errors import exit_with
+from stateous.cli.tokens import token_app
+
+DEFAULT_DB = "sqlite:///stateous.db"
+DEFAULT_LISTEN = "127.0.0.1:8080"
+
+app = typer.Typer(
+    help="A process as a graph of states. A control plane keeps every token durable.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.callback()
+def _root() -> None:
+    """A process as a graph of states. A control plane keeps every token durable."""
+
+
+@app.command("compile")
+def compile_command(
+    flow: Annotated[Path, typer.Argument(help="The workflow's file, e.g. sdlc/flow.py.")],
+    out: Annotated[
+        Path | None,
+        typer.Option(
+            "--out", help="The graph file to write. Default: build/<workflow>.json next to FLOW."
+        ),
+    ] = None,
+) -> None:
+    """Check a workflow, and write its graph file."""
+    from stateous.compiler.codegen import CodegenError, generate_contract
+    from stateous.compiler.compile import compile_workflow
+    from stateous.compiler.load import LoadError, load_workflow
+    from stateous.model.graph_file import dump_graph
+    from stateous.model.workflow import DefinitionError
+
+    try:
+        workflow = load_workflow(flow)
+        document = compile_workflow(workflow)
+        generate_contract(document)  # a name that cannot be Python is found now, not at `init`
+    except (LoadError, DefinitionError, CodegenError) as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(1) from None
+    target = out if out is not None else flow.parent / "build" / f"{workflow.name}.json"
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(dump_graph(document), encoding="utf-8", newline="\n")
+    except OSError as error:
+        typer.echo(f"error: cannot write {target}: {error.strerror}", err=True)
+        raise typer.Exit(1) from None
+    typer.echo(f"wrote {target}")
+
+
+@app.command()
+def serve(
+    graph: Annotated[
+        Path,
+        typer.Argument(help="The graph file that `stateous compile` wrote.", show_default=False),
+    ],
+    db: Annotated[str, typer.Option("--db", help="The database URL.")] = DEFAULT_DB,
+    listen: Annotated[
+        str, typer.Option("--listen", help="HOST:PORT to listen on.")
+    ] = DEFAULT_LISTEN,
+    supervise_folder: Annotated[
+        Path | None,
+        typer.Option(
+            "--supervise",
+            help="Also run the supervisor of this folder, in this process (for development).",
+        ),
+    ] = None,
+) -> None:
+    """Run the control plane: the HTTP API and the clock, over one database."""
+    from stateous.cli import running
+
+    running.serve(graph, db, listen, supervise_folder)
+
+
+@app.command()
+def init(
+    url: Annotated[str, typer.Argument(help="The control plane, e.g. http://127.0.0.1:8080.")],
+    folder: Annotated[Path, typer.Argument(help="The supervisor's folder. Made if absent.")],
+    stateous_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--stateous-path",
+            help="A local Stateous checkout for the folder to depend on, to work on Stateous "
+            "itself.",
+        ),
+    ] = None,
+) -> None:
+    """Write a supervisor's folder: contract.py, a stub for each state with a routine
+    (of each workflow), stateous.yaml, pyproject.toml. Run it again to update
+    contract.py."""
+    from stateous.cli.errors import CommandError
+    from stateous.cli.project_file import checkout, write_pyproject
+    from stateous.client.client import Client, ClientError
+    from stateous.compiler.codegen import generate_contract, generate_stub, routine_states
+    from stateous.supervisor.folder import write_folder
+
+    source: str | None = None
+    if stateous_path is not None:
+        try:
+            source = checkout(stateous_path)
+        except CommandError as error:
+            exit_with(str(error))
+    try:
+        with Client(url) as client:
+            document = client.workflow()
+    except ClientError as error:
+        exit_with(f"cannot fetch the workflow from {url}: {error}")
+
+    def stub(state: str) -> str:
+        return generate_stub(document, state)
+
+    states = routine_states(document)
+    try:
+        lines = write_folder(
+            folder, url=url, contract=generate_contract(document), states=states, stub=stub
+        )
+        lines.append(write_pyproject(folder, stateous_path=source))
+    except OSError as error:
+        exit_with(f"cannot write {folder}: {error.strerror or error}")
+    for line in lines:
+        typer.echo(line)
+    typer.echo(f"\nWrite the routines, then run: stateous supervise {folder}")
+
+
+@app.command()
+def supervise(
+    folder: Annotated[Path, typer.Argument(help="The supervisor's folder.")],
+) -> None:
+    """Run the routines of a supervisor's folder. Ctrl-C once: take no new tasks and
+    wait for the running routines. Twice: cancel them and exit."""
+    from stateous.cli import running
+
+    running.supervise(folder)
+
+
+app.add_typer(token_app, name="token")
+
+
+def main() -> None:
+    """The `stateous` command. Output to a closed pipe (`stateous token show | head -1`)
+    ends the command quietly, with exit code 1: no traceback. Any other error shows as
+    usual, also an EINVAL that did not come from a write to stdout."""
+    stdout = _Stdout(sys.stdout)
+    sys.stdout = cast("TextIO", stdout)
+    try:
+        try:
+            app(prog_name="stateous")
+        finally:
+            sys.stdout.flush()
+    except OSError as error:
+        if not _closed_pipe(error, stdout.failure):
+            raise
+        # Python flushes stdout again at exit: send it to nothing, so that flush cannot fail.
+        nothing = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(nothing, sys.stdout.fileno())
+        sys.exit(1)
+    finally:
+        sys.stdout = stdout.stream
+
+
+class _Stdout:
+    """Stdout, which keeps the error of a write or a flush that failed. All else goes
+    to the stream."""
+
+    def __init__(self, stream: TextIO) -> None:
+        self.stream = stream
+        self.failure: OSError | None = None
+
+    def write(self, text: str) -> int:
+        try:
+            return self.stream.write(text)
+        except OSError as error:
+            self.failure = error
+            raise
+
+    def writelines(self, lines: Iterable[str]) -> None:
+        try:
+            self.stream.writelines(lines)
+        except OSError as error:
+            self.failure = error
+            raise
+
+    def flush(self) -> None:
+        try:
+            self.stream.flush()
+        except OSError as error:
+            self.failure = error
+            raise
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.stream, name)
+
+
+def _closed_pipe(error: OSError, stdout_failure: OSError | None) -> bool:
+    """True when `error` is a write to a pipe that the reader closed. On Windows, the
+    error is EINVAL, not EPIPE; but EINVAL also comes from other calls (for example
+    `open('a?b.py')`), so it counts only when a write or a flush of stdout raised it."""
+    if isinstance(error, BrokenPipeError) or error.errno == errno.EPIPE:
+        return True
+    return sys.platform == "win32" and error.errno == errno.EINVAL and error is stdout_failure

stateous/cli/project_file.py

@@ -0,0 +1,112 @@
+"""The pyproject.toml that `stateous init` writes (see the guide, "Set up a supervisor").
+
+The supervisor's folder is a Python project of its own. It depends on Stateous and
+on what its routines import, so `uv sync` makes its environment (`.venv`), and
+editors find `stateous` there. To work on Stateous itself, `--stateous-path`
+points the dependency at a local checkout, as an editable `[tool.uv.sources]` entry.
+
+The text is built in Python, as `stateous.compiler.codegen` builds `contract.py`."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import Any, cast
+
+from stateous.cli.errors import CommandError
+
+PACKAGE = "stateous"
+PYPROJECT = "pyproject.toml"
+DEFAULT_NAME = "supervisor"
+"""The project's name when nothing of the folder's name can be one."""
+
+_HEADER = """\
+# Written by `stateous init`. This folder is a Python project of its own:
+# `uv sync` makes its environment (.venv), and `uv run stateous ...` runs in it.
+# Add what your routines import to `dependencies`.
+"""
+
+_SOURCE_COMMENT = "# A local checkout of Stateous: delete this table to use Stateous from PyPI."
+
+
+def checkout(path: Path) -> str:
+    """`path` as a Stateous checkout: absolute, with forward slashes. Raises
+    `CommandError` when `path` is not a folder that holds a pyproject.toml with the
+    project name `stateous`."""
+    resolved = path.expanduser().resolve()
+    data: dict[str, Any]
+    try:
+        data = tomllib.loads((resolved / PYPROJECT).read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError):
+        data = {}
+    project: Any = data.get("project")
+    name: object = None
+    if isinstance(project, dict):
+        table = cast("dict[str, object]", project)
+        name = table.get("name")
+    if name != PACKAGE:
+        raise CommandError(
+            f"--stateous-path {path} is not a Stateous checkout: give the folder that holds "
+            f"its {PYPROJECT}"
+        )
+    return resolved.as_posix()
+
+
+def write_pyproject(folder: Path, *, stateous_path: str | None = None) -> str:
+    """Write `folder/pyproject.toml`, only when it is absent. `stateous_path` is a
+    checkout, as `checkout` returns it. Returns one line: `wrote    <path>` or
+    `kept     <path>`."""
+    target = folder / PYPROJECT
+    if target.exists():
+        return f"kept     {target}"
+    folder.mkdir(parents=True, exist_ok=True)
+    text = pyproject_text(project_name(folder.resolve().name), stateous_path)
+    target.write_text(text, encoding="utf-8", newline="\n")
+    return f"wrote    {target}"
+
+
+def pyproject_text(name: str, stateous_path: str | None) -> str:
+    """The text of the file: a `[project]`, and a `[tool.uv.sources]` table when a
+    checkout is given."""
+    lines = [
+        _HEADER,
+        "[project]",
+        f"name = {_toml_string(name)}",
+        'version = "0.1.0"',
+        'requires-python = ">=3.12"',
+        f"dependencies = [{_toml_string(requirement())}]",
+    ]
+    if stateous_path is not None:
+        lines += [
+            "",
+            _SOURCE_COMMENT,
+            "[tool.uv.sources]",
+            f"{PACKAGE} = {{ path = {_toml_string(stateous_path)}, editable = true }}",
+        ]
+    return "\n".join(lines) + "\n"
+
+
+def requirement() -> str:
+    """`stateous>=<the version that runs>`: `contract.py` is written by this version,
+    and an older Stateous may not read it. Only `stateous` when the version is not
+    known."""
+    try:
+        return f"{PACKAGE}>={version(PACKAGE)}"
+    except PackageNotFoundError:
+        return PACKAGE
+
+
+def project_name(folder_name: str) -> str:
+    """`folder_name` as a valid project name: letters, digits, `.`, `_` and `-`, with
+    a letter or a digit at the start and at the end."""
+    cleaned = re.sub(r"[^A-Za-z0-9._-]", "-", folder_name).strip("._-")
+    return cleaned or DEFAULT_NAME
+
+
+def _toml_string(text: str) -> str:
+    """`text` as a TOML basic string."""
+    escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+    escaped = re.sub(r"[\x00-\x1f\x7f]", lambda found: f"\\u{ord(found.group()):04x}", escaped)
+    return f'"{escaped}"'

stateous/cli/running.py

@@ -0,0 +1,276 @@
+"""The long commands: `stateous serve` and `stateous supervise`.
+
+This module imports the server, the database and the supervisor. `stateous.cli.main`
+imports it only in these two commands, so `--help`, `token ...`, `compile` and
+`init` start fast."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import sys
+import threading
+from collections.abc import Callable, Coroutine
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from types import FrameType
+from typing import Any, NoReturn
+
+import typer
+import uvicorn
+
+from stateous.cli.errors import exit_with
+from stateous.cli.serving import (
+    GracefulServer,
+    ServeRefused,
+    Serving,
+    configure_logging,
+    prepare_serve,
+)
+from stateous.supervisor.folder import Folder, FolderError, load_folder
+from stateous.supervisor.remote import ControlPlaneApi
+from stateous.supervisor.supervisor import (
+    Supervisor,
+    SupervisorError,
+    open_supervisor,
+    stop_on_signals,
+)
+
+log = logging.getLogger("stateous.cli")
+
+LEFTOVER_WAIT = 2.0
+"""After the supervisor stopped: seconds to wait for the tasks still on the loop
+(for example a routine that ignores its cancellation), and then for the threads of
+the loop (`asyncio.to_thread`). Then the command exits."""
+
+
+def serve(graph: Path, db: str, listen: str, supervise_folder: Path | None) -> None:
+    """The body of `stateous serve`."""
+    configure_logging()
+    folder: Folder | None = None
+    if supervise_folder is not None:
+        try:
+            folder = load_folder(supervise_folder)
+        except FolderError as error:
+            exit_with(str(error))
+    try:
+        serving = prepare_serve(graph, db, listen)
+    except ServeRefused as error:
+        exit_with(str(error))
+    typer.echo(f"serving on {serving.url} (Ctrl-C stops)", err=True)
+    code, clean = 0, True
+    try:
+        if folder is None:
+            server = GracefulServer(serving.config)
+
+            def stop() -> None:
+                server.should_exit = True
+
+            serving.on_lost(stop)
+            server.run(sockets=[serving.listener])
+        else:
+            log_to_stderr()
+            code, clean = serve_with_supervisor(serving, folder)
+    finally:
+        serving.close()
+    if serving.clock.lost:
+        typer.echo(
+            "error: another control plane took the database; this control plane stopped",
+            err=True,
+        )
+        code = 1
+    if code != 0 or not clean:
+        if folder is not None:
+            exit_now(code)
+        raise typer.Exit(code)
+    typer.echo("stopped", err=True)
+
+
+def supervise(folder: Path) -> None:
+    """The body of `stateous supervise`."""
+    log_to_stderr()
+    try:
+        loaded = load_folder(folder)
+        code, clean = run_bounded(supervise_folder(loaded))
+    except (FolderError, SupervisorError) as error:
+        exit_with(str(error))
+    except KeyboardInterrupt:  # Ctrl-C before the handlers were in place
+        code, clean = 1, True
+    if code != 0 or not clean:
+        exit_now(code)
+    raise typer.Exit(code)
+
+
+def log_to_stderr() -> None:
+    """The supervisor's log lines on stderr, at INFO. `configure_logging` adds a
+    handler only when there is none, so a second call adds no second handler. The
+    HTTP libraries log only warnings."""
+    configure_logging()
+    for name in ("httpx2", "httpcore"):
+        logging.getLogger(name).setLevel(logging.WARNING)
+
+
+def run_bounded(
+    main: Coroutine[Any, Any, int], *, leftover_wait: float = LEFTOVER_WAIT
+) -> tuple[int, bool]:
+    """Run `main` on a new event loop. Returns its exit code, and whether the end is
+    clean. As `asyncio.run`, but the end does not wait without limit: the tasks
+    left on the loop are cancelled, and the loop waits at most `leftover_wait`
+    seconds for them. So a routine that ignores its cancellation cannot stop the
+    command from exiting. Then it waits at most `leftover_wait` seconds for the
+    threads of the loop (`asyncio.to_thread`). When one still runs, the end is not
+    clean: a normal exit would wait for that thread, so only `exit_now` ends the
+    process."""
+    loop = asyncio.new_event_loop()
+    executor = ThreadPoolExecutor(thread_name_prefix="stateous-to-thread")
+    loop.set_default_executor(executor)
+    clean = False
+    try:
+        code = loop.run_until_complete(main)
+    finally:
+        try:
+            left = [task for task in asyncio.all_tasks(loop) if not task.done()]
+            for task in left:
+                task.cancel()
+            if left:
+                _, pending = loop.run_until_complete(asyncio.wait(left, timeout=leftover_wait))
+                if pending:
+                    log.warning("%d task(s) did not stop; exiting without them", len(pending))
+                    loop.set_exception_handler(_quiet_about(pending))
+            loop.run_until_complete(loop.shutdown_asyncgens())
+            clean = _threads_ended(executor, leftover_wait)
+        finally:
+            loop.close()
+    return code, clean
+
+
+def _threads_ended(executor: ThreadPoolExecutor, wait: float) -> bool:
+    """Shut down `executor`. True when its threads end within `wait` seconds."""
+    ended = threading.Event()
+
+    def shut_down() -> None:
+        executor.shutdown(wait=True, cancel_futures=True)
+        ended.set()
+
+    threading.Thread(target=shut_down, name="stateous-shutdown", daemon=True).start()
+    if ended.wait(wait):
+        return True
+    log.warning("a thread of a routine did not stop; exiting without it")
+    return False
+
+
+def exit_now(code: int) -> NoReturn:
+    """End the process with `code` at once, after the log and the output are
+    flushed. A routine's thread that still runs (`asyncio.to_thread`) cannot hold
+    the exit then. Use it after a forced stop, when the loop is closed."""
+    logging.shutdown()
+    for stream in (sys.stdout, sys.stderr):
+        with contextlib.suppress(Exception):
+            stream.flush()
+    os._exit(code)
+
+
+def _quiet_about(abandoned: set[asyncio.Task[Any]]) -> Callable[..., None]:
+    """An exception handler for the loop that says nothing more about the tasks that
+    were left behind (the line above names them already). Each other report goes to
+    the default handler."""
+
+    def handle(loop: asyncio.AbstractEventLoop, context: dict[str, Any]) -> None:
+        if context.get("task") in abandoned:
+            return
+        loop.default_exception_handler(context)
+
+    return handle
+
+
+async def supervise_folder(folder: Folder) -> int:
+    """Open and run the supervisor of `folder`. Returns its exit code."""
+    api = ControlPlaneApi(folder.config.url)
+    try:
+        supervisor = await open_supervisor(folder, api)
+        try:
+            with stop_on_signals(supervisor):
+                return await supervisor.run()
+        finally:
+            supervisor.close()
+    finally:
+        await api.aclose()
+
+
+class SupervisedServer(GracefulServer):
+    """Uvicorn's server, but a stop signal goes to the supervisor. The server serves
+    on while the supervisor waits for its routines, so they can still report. It
+    stops when the supervisor's `run` ends. The signal is not recorded, so uvicorn
+    does not raise it again at the end."""
+
+    def __init__(self, config: uvicorn.Config) -> None:
+        super().__init__(config)
+        self.supervisor: Supervisor | None = None
+
+    def handle_exit(self, sig: int, frame: FrameType | None) -> None:
+        if self.supervisor is None:  # not yet running, or `run` has returned
+            super().handle_exit(sig, frame)  # GracefulServer: graceful first, then at once
+        else:
+            self.supervisor.on_signal()
+
+    def stop_all(self) -> None:
+        """Stop the server, and stop the supervisor at once: its control plane does no
+        more work. It runs on the server's loop (`Serving.on_lost`): it does not block
+        and does not raise."""
+        self.should_exit = True
+        if self.supervisor is not None:
+            self.supervisor.stop_now()
+
+
+def serve_with_supervisor(serving: Serving, folder: Folder) -> tuple[int, bool]:
+    """Run `serve_and_supervise`. Returns the exit code, and whether the end is
+    clean (`run_bounded`)."""
+    try:
+        return run_bounded(serve_and_supervise(serving, folder))
+    except SupervisorError as error:
+        exit_with(str(error))
+    except KeyboardInterrupt:  # a signal before the server took the signals
+        return 1, True
+
+
+async def serve_and_supervise(serving: Serving, folder: Folder) -> int:
+    """The control plane and the supervisor of `folder` in one loop. The supervisor
+    speaks HTTP to the server's own address. Returns the supervisor's exit code:
+    1 also when the server stopped before the supervisor ran (a lost hold, or a
+    signal at the start)."""
+    server = SupervisedServer(serving.config)
+    serving.on_lost(server.stop_all)
+    serving_task = asyncio.create_task(server.serve(sockets=[serving.listener]))
+    api = ControlPlaneApi(serving.url)
+    supervising = asyncio.create_task(supervise_beside(server, folder, api))
+    try:
+        await asyncio.wait({serving_task, supervising}, return_when=asyncio.FIRST_COMPLETED)
+        if not supervising.done():  # the server stopped first
+            if server.supervisor is None:
+                supervising.cancel()
+            else:
+                server.stop_all()
+        await asyncio.wait({supervising})
+        code = 1 if supervising.cancelled() else supervising.result()
+        if code != 0:
+            server.force_exit = True
+        return code
+    finally:
+        await api.aclose()
+        server.should_exit = True
+        await serving_task
+
+
+async def supervise_beside(server: SupervisedServer, folder: Folder, api: ControlPlaneApi) -> int:
+    """Wait until the server serves, then open and run the supervisor of `folder`."""
+    while not server.started:
+        await asyncio.sleep(0.05)
+    supervisor = await open_supervisor(folder, api)
+    server.supervisor = supervisor
+    try:
+        return await supervisor.run()
+    finally:
+        server.supervisor = None  # later signals stop the server: a hung request can be forced
+        supervisor.close()