From 095c165a34e0b4125e0656197d7f218b7a1bb258 Mon Sep 17 00:00:00 2001 From: goodboy Date: Thu, 2 Jul 2026 12:32:49 -0400 Subject: [PATCH] Expand caps-based-msging docs w/ #365, #376 + tests The "Toward capability-based msging" section only pointed at the `#196`/`#36` epics. Fold in the concrete recent state, - `#365` as the most recent step: driving the whole `pld_spec` off plain type-annotations (e.g. annotating a context's `open_stream()` with `msgspec.Struct` subtypes) rather than explicit `pld_spec=` kwargs. - clarify that the decorator-level `@tractor.context(pld_spec=...)` is already the higher-level path (vs the lower-level `tractor.msg._ops.limit_plds()` escape hatch), pointing at `tests/msg/test_pldrx_limiting.py` + `test_ext_types_msgspec.py` which exercise both. - `#376` (from @guilledk, `auto_codecs` branch) as the drafted public factory API for the `enc_hook`/`dec_hook` pair (today only reachable via `tractor.msg._ops`). Addresses the caps-based-msging bullet in #472. (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code --- docs/guide/msging.rst | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/docs/guide/msging.rst b/docs/guide/msging.rst index 5c5a4d12..eb5f8b8d 100644 --- a/docs/guide/msging.rst +++ b/docs/guide/msging.rst @@ -238,9 +238,31 @@ Toward capability-based msging The ``pld_spec`` + codec-hook layer is the foundation for the long-game: **capability-based msging** where each dialog's type contract doubles as a capability grant, negotiated as part -of the protocol itself. That work is tracked in `#196`_ (with the -original typed-proto epic in `#36`_); if strongly-typed -distributed systems get you going, we'd love your input. +of the protocol itself. The epic is tracked in `#196`_ (evolving +the original typed-proto work in `#36`_), and the most recent +concrete step is `#365`_ — driving the whole ``pld_spec`` off +plain type-annotations (e.g. annotating a context's +``open_stream()`` with ``msgspec.Struct`` subtypes) instead of +explicit ``pld_spec=`` kwargs. + +You don't have to wait for that, though: the decorator-level +``@tractor.context(pld_spec=...)`` shown above is already the +*higher-level* way to pin a dialog's payload contract, while +``tractor.msg._ops.limit_plds()`` is the lower-level, per-block +escape hatch. Both are exercised end-to-end in +``tests/msg/test_pldrx_limiting.py`` and +``tests/msg/test_ext_types_msgspec.py``. + +On the codec-hook side, the ``enc_hook``/``dec_hook`` pair is +today only reachable via ``tractor.msg._ops``; a public *factory* +API for them is drafted in `#376`_ (from +`@guilledk `_, on the +`auto_codecs `_ +branch) — the likely long-term home for custom-type +(de)serialization. + +If strongly-typed distributed systems get you going, we'd love +your input on any of the above. Where to next? -------------- @@ -258,3 +280,5 @@ Where to next? .. _(un)protocol: https://zguide.zeromq.org/docs/chapter7/#Unprotocols .. _#196: https://github.com/goodboy/tractor/issues/196 .. _#36: https://github.com/goodboy/tractor/issues/36 +.. _#365: https://github.com/goodboy/tractor/issues/365 +.. _#376: https://github.com/goodboy/tractor/pull/376