Metadata-Version: 2.4
Name: mmo-runtime
Version: 0.1.3
Summary: Runtime library for MMO gRPC tools
Author-email: tool-mmo <tranduythuc2003@gmail.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/tool-mmo3/base/toolkit-mmo
Project-URL: Repository, https://gitlab.com/tool-mmo3/base/toolkit-mmo
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: import-linter>=2.4; extra == "dev"

# mmo-runtime

Runtime library for MMO gRPC tools.

## Worker execution

`stream_in_worker(workflow, request, ctx, *, pool=None, timeout=None)` yields
`ProgressEvent` objects in order, then one `ResultEnvelope` or `ErrorEnvelope`.
Even without a supplied pool the workflow runs on a worker thread, so progress
is available before completion. Progress is buffered up to 64 events; slow
consumers apply backpressure rather than dropping events or growing memory
without bound. Close abandoned iterators to release blocked producers.

Timeout is measured from the first iterator advance and includes queue time.
`None` disables the deadline; zero (or a negative value) expires immediately.
Cancellation, timeout, and iterator closure signal `ctx.cancel` and cancel jobs
which have not started. Running workflows must cooperatively check the token
and bound their own blocking I/O. Python threads are **not** forcibly terminated;
an uncooperative job can retain its worker slot and delay process exit.

`run_in_worker` retains its legacy `(terminal, progress_list)` API, including
inline execution without a pool and pooled cancellation/admission exceptions.
Its accumulated progress list is intentionally not memory-bounded; use the
streaming API for long-running jobs. `WorkerPool.shutdown(cancel_futures=True)`
cancels waiting jobs; it does not interrupt running jobs.

## Transport and lifecycle

`ToolClient.channel` is public for constructing service stubs. Unary and stream
calls accept `deadline` (including zero) and keyword-only `metadata`, a sequence
of `(key, value)` pairs. Unknown error-envelope codes normalize to `INTERNAL`.
Unavailable transports map to retryable `PROVIDER_ERROR`; resource exhaustion,
invalid requests, cancellation, and expired deadlines retain their error codes.
Health polling limits each probe and sleep to the remaining polling budget.

Plain Unix socket paths, explicit `unix://` targets, TCP `host:port` (including
IPv6), and resolver targets are normalized without duplicate Unix prefixes.
The default on Windows is `127.0.0.1:50051`; choose explicit per-tool ports to
avoid collisions. Unix keeps `/tmp/tool.sock` as its default.

The server tracks the full handler lifetime of unary and streaming application
RPCs. Health probes do not keep an otherwise idle server alive. The idle period
restarts after the last active handler exits. Shutdown is one-shot, marks
health not-serving, signals the server cancellation token, waits for gRPC's
graceful stop, then cleans up transport resources and invokes `on_stop` once.
Signal handlers are installed only on the Unix main thread and restored on exit.
An instance is single-use; create a new instance to restart.

The server cancellation token is available for embedded workflows; generated
servicers use their own per-RPC token and gRPC cancellation callback. Graceful
shutdown therefore lets existing generated RPCs finish until grace expires.
Neither `job_timeout_sec` nor the server token is automatically injected into
arbitrary registered handlers: pass explicit worker deadlines and cancellation
tokens when implementing custom handlers.
