Add `debug_mode: bool` control to task mngr

Allows dynamically importing `pdbp` when enabled and a way for
eventually linking with `tractor`'s own debug mode flag.

tests/test_caps_based_msging.py

@@ -0,0 +1,917 @@
+'''
+Low-level functional audits for our
+"capability based messaging"-spec feats.
+
+B~)
+
+'''
+import typing
+from typing import (
+    Any,
+    Type,
+    Union,
+)
+
+from msgspec import (
+    structs,
+    msgpack,
+    Struct,
+    ValidationError,
+)
+import pytest
+
+import tractor
+from tractor import (
+    _state,
+    MsgTypeError,
+    Context,
+)
+from tractor.msg import (
+    _codec,
+    _ctxvar_MsgCodec,
+
+    NamespacePath,
+    MsgCodec,
+    mk_codec,
+    apply_codec,
+    current_codec,
+)
+from tractor.msg.types import (
+    _payload_msgs,
+    log,
+    PayloadMsg,
+    Started,
+    mk_msg_spec,
+)
+import trio
+
+
+def mk_custom_codec(
+    pld_spec: Union[Type]|Any,
+    add_hooks: bool,
+
+) -> MsgCodec:
+    '''
+    Create custom `msgpack` enc/dec-hooks and set a `Decoder`
+    which only loads `pld_spec` (like `NamespacePath`) types.
+
+    '''
+    uid: tuple[str, str] = tractor.current_actor().uid
+
+    # XXX NOTE XXX: despite defining `NamespacePath` as a type
+    # field on our `PayloadMsg.pld`, we still need a enc/dec_hook() pair
+    # to cast to/from that type on the wire. See the docs:
+    # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
+
+    def enc_nsp(obj: Any) -> Any:
+        print(f'{uid} ENC HOOK')
+        match obj:
+            case NamespacePath():
+                print(
+                    f'{uid}: `NamespacePath`-Only ENCODE?\n'
+                    f'obj-> `{obj}`: {type(obj)}\n'
+                )
+                # if type(obj) != NamespacePath:
+                #     breakpoint()
+                return str(obj)
+
+        print(
+            f'{uid}\n'
+            'CUSTOM ENCODE\n'
+            f'obj-arg-> `{obj}`: {type(obj)}\n'
+        )
+        logmsg: str = (
+            f'{uid}\n'
+            'FAILED ENCODE\n'
+            f'obj-> `{obj}: {type(obj)}`\n'
+        )
+        raise NotImplementedError(logmsg)
+
+    def dec_nsp(
+        obj_type: Type,
+        obj: Any,
+
+    ) -> Any:
+        print(
+            f'{uid}\n'
+            'CUSTOM DECODE\n'
+            f'type-arg-> {obj_type}\n'
+            f'obj-arg-> `{obj}`: {type(obj)}\n'
+        )
+        nsp = None
+
+        if (
+            obj_type is NamespacePath
+            and isinstance(obj, str)
+            and ':' in obj
+        ):
+            nsp = NamespacePath(obj)
+            # TODO: we could built a generic handler using
+            # JUST matching the obj_type part?
+            # nsp = obj_type(obj)
+
+        if nsp:
+            print(f'Returning NSP instance: {nsp}')
+            return nsp
+
+        logmsg: str = (
+            f'{uid}\n'
+            'FAILED DECODE\n'
+            f'type-> {obj_type}\n'
+            f'obj-arg-> `{obj}`: {type(obj)}\n\n'
+            f'current codec:\n'
+            f'{current_codec()}\n'
+        )
+        # TODO: figure out the ignore subsys for this!
+        # -[ ] option whether to defense-relay backc the msg
+        #   inside an `Invalid`/`Ignore`
+        # -[ ] how to make this handling pluggable such that a
+        #   `Channel`/`MsgTransport` can intercept and process
+        #   back msgs either via exception handling or some other
+        #   signal?
+        log.warning(logmsg)
+        # NOTE: this delivers the invalid
+        # value up to `msgspec`'s decoding
+        # machinery for error raising.
+        return obj
+        # raise NotImplementedError(logmsg)
+
+    nsp_codec: MsgCodec = mk_codec(
+        ipc_pld_spec=pld_spec,
+
+        # NOTE XXX: the encode hook MUST be used no matter what since
+        # our `NamespacePath` is not any of a `Any` native type nor
+        # a `msgspec.Struct` subtype - so `msgspec` has no way to know
+        # how to encode it unless we provide the custom hook.
+        #
+        # AGAIN that is, regardless of whether we spec an
+        # `Any`-decoded-pld the enc has no knowledge (by default)
+        # how to enc `NamespacePath` (nsp), so we add a custom
+        # hook to do that ALWAYS.
+        enc_hook=enc_nsp if add_hooks else None,
+
+        # XXX NOTE: pretty sure this is mutex with the `type=` to
+        # `Decoder`? so it won't work in tandem with the
+        # `ipc_pld_spec` passed above?
+        dec_hook=dec_nsp if add_hooks else None,
+    )
+    return nsp_codec
+
+
+def chk_codec_applied(
+    expect_codec: MsgCodec,
+    enter_value: MsgCodec|None = None,
+
+) -> MsgCodec:
+    '''
+    buncha sanity checks ensuring that the IPC channel's
+    context-vars are set to the expected codec and that are
+    ctx-var wrapper APIs match the same.
+
+    '''
+    # TODO: play with tricyle again, bc this is supposed to work
+    # the way we want?
+    #
+    # TreeVar
+    # task: trio.Task = trio.lowlevel.current_task()
+    # curr_codec = _ctxvar_MsgCodec.get_in(task)
+
+    # ContextVar
+    # task_ctx: Context = task.context
+    # assert _ctxvar_MsgCodec in task_ctx
+    # curr_codec: MsgCodec = task.context[_ctxvar_MsgCodec]
+
+    # NOTE: currently we use this!
+    # RunVar
+    curr_codec: MsgCodec = current_codec()
+    last_read_codec = _ctxvar_MsgCodec.get()
+    # assert curr_codec is last_read_codec
+
+    assert (
+        (same_codec := expect_codec) is
+        # returned from `mk_codec()`
+
+        # yielded value from `apply_codec()`
+
+        # read from current task's `contextvars.Context`
+        curr_codec is
+        last_read_codec
+
+        # the default `msgspec` settings
+        is not _codec._def_msgspec_codec
+        is not _codec._def_tractor_codec
+    )
+
+    if enter_value:
+        enter_value is same_codec
+
+
+def iter_maybe_sends(
+    send_items: dict[Union[Type], Any] | list[tuple],
+    ipc_pld_spec: Union[Type] | Any,
+    add_codec_hooks: bool,
+
+    codec: MsgCodec|None = None,
+
+) -> tuple[Any, bool]:
+
+    if isinstance(send_items, dict):
+        send_items = send_items.items()
+
+    for (
+        send_type_spec,
+        send_value,
+    ) in send_items:
+
+        expect_roundtrip: bool = False
+
+        # values-to-typespec santiy
+        send_type = type(send_value)
+        assert send_type == send_type_spec or (
+            (subtypes := getattr(send_type_spec, '__args__', None))
+            and send_type in subtypes
+        )
+
+        spec_subtypes: set[Union[Type]] = (
+             getattr(
+                 ipc_pld_spec,
+                 '__args__',
+                 {ipc_pld_spec,},
+             )
+        )
+        send_in_spec: bool = (
+            send_type == ipc_pld_spec
+            or (
+                ipc_pld_spec != Any
+                and  # presume `Union` of types
+                send_type in spec_subtypes
+            )
+            or (
+                ipc_pld_spec == Any
+                and
+                send_type != NamespacePath
+            )
+        )
+        expect_roundtrip = (
+            send_in_spec
+            # any spec should support all other
+            # builtin py values that we send
+            # except our custom nsp type which
+            # we should be able to send as long
+            # as we provide the custom codec hooks.
+            or (
+                ipc_pld_spec == Any
+                and
+                send_type == NamespacePath
+                and
+                add_codec_hooks
+            )
+        )
+
+        if codec is not None:
+            # XXX FIRST XXX ensure roundtripping works
+            # before touching any IPC primitives/APIs.
+            wire_bytes: bytes = codec.encode(
+                Started(
+                    cid='blahblah',
+                    pld=send_value,
+                )
+            )
+            # NOTE: demonstrates the decoder loading
+            # to via our native SCIPP msg-spec
+            # (structurred-conc-inter-proc-protocol)
+            # implemented as per,
+            try:
+                msg: Started = codec.decode(wire_bytes)
+                if not expect_roundtrip:
+                    pytest.fail(
+                        f'NOT-EXPECTED able to roundtrip value given spec:\n'
+                        f'ipc_pld_spec -> {ipc_pld_spec}\n'
+                        f'value -> {send_value}: {send_type}\n'
+                    )
+
+                pld = msg.pld
+                assert pld == send_value
+
+            except ValidationError:
+                if expect_roundtrip:
+                    pytest.fail(
+                        f'EXPECTED to roundtrip value given spec:\n'
+                        f'ipc_pld_spec -> {ipc_pld_spec}\n'
+                        f'value -> {send_value}: {send_type}\n'
+                    )
+
+        yield (
+            str(send_type),
+            send_value,
+            expect_roundtrip,
+        )
+
+
+def dec_type_union(
+    type_names: list[str],
+) -> Type:
+    '''
+    Look up types by name, compile into a list and then create and
+    return a `typing.Union` from the full set.
+
+    '''
+    import importlib
+    types: list[Type] = []
+    for type_name in type_names:
+        for mod in [
+            typing,
+            importlib.import_module(__name__),
+        ]:
+            if type_ref := getattr(
+                mod,
+                type_name,
+                False,
+            ):
+                types.append(type_ref)
+
+    # special case handling only..
+    # ipc_pld_spec: Union[Type] = eval(
+    #     pld_spec_str,
+    #     {},  # globals
+    #     {'typing': typing},  # locals
+    # )
+
+    return Union[*types]
+
+
+def enc_type_union(
+    union_or_type: Union[Type]|Type,
+) -> list[str]:
+    '''
+    Encode a type-union or single type to a list of type-name-strings
+    ready for IPC interchange.
+
+    '''
+    type_strs: list[str] = []
+    for typ in getattr(
+        union_or_type,
+        '__args__',
+        {union_or_type,},
+    ):
+        type_strs.append(typ.__qualname__)
+
+    return type_strs
+
+
+@tractor.context
+async def send_back_values(
+    ctx: Context,
+    expect_debug: bool,
+    pld_spec_type_strs: list[str],
+    add_hooks: bool,
+    started_msg_bytes: bytes,
+    expect_ipc_send: dict[str, tuple[Any, bool]],
+
+) -> None:
+    '''
+    Setup up a custom codec to load instances of `NamespacePath`
+    and ensure we can round trip a func ref with our parent.
+
+    '''
+    uid: tuple = tractor.current_actor().uid
+
+    # debug mode sanity check (prolly superfluous but, meh)
+    assert expect_debug == _state.debug_mode()
+
+    # init state in sub-actor should be default
+    chk_codec_applied(
+        expect_codec=_codec._def_tractor_codec,
+    )
+
+    # load pld spec from input str
+    ipc_pld_spec = dec_type_union(
+        pld_spec_type_strs,
+    )
+    pld_spec_str = str(ipc_pld_spec)
+
+    # same as on parent side config.
+    nsp_codec: MsgCodec = mk_custom_codec(
+        pld_spec=ipc_pld_spec,
+        add_hooks=add_hooks,
+    )
+    with (
+        apply_codec(nsp_codec) as codec,
+    ):
+        chk_codec_applied(
+            expect_codec=nsp_codec,
+            enter_value=codec,
+        )
+
+        print(
+            f'{uid}: attempting `Started`-bytes DECODE..\n'
+        )
+        try:
+            msg: Started = nsp_codec.decode(started_msg_bytes)
+            expected_pld_spec_str: str = msg.pld
+            assert pld_spec_str == expected_pld_spec_str
+
+        # TODO: maybe we should add our own wrapper error so as to
+        # be interchange-lib agnostic?
+        # -[ ] the error type is wtv is raised from the hook so we
+        #   could also require a type-class of errors for
+        #   indicating whether the hook-failure can be handled by
+        #   a nasty-dialog-unprot sub-sys?
+        except ValidationError:
+
+            # NOTE: only in the `Any` spec case do we expect this to
+            # work since otherwise no spec covers a plain-ol'
+            # `.pld: str`
+            if pld_spec_str == 'Any':
+                raise
+            else:
+                print(
+                    f'{uid}: (correctly) unable to DECODE `Started`-bytes\n'
+                    f'{started_msg_bytes}\n'
+                )
+
+        iter_send_val_items = iter(expect_ipc_send.values())
+        sent: list[Any] = []
+        for send_value, expect_send in iter_send_val_items:
+            try:
+                print(
+                    f'{uid}: attempting to `.started({send_value})`\n'
+                    f'=> expect_send: {expect_send}\n'
+                    f'SINCE, ipc_pld_spec: {ipc_pld_spec}\n'
+                    f'AND, codec: {codec}\n'
+                )
+                await ctx.started(send_value)
+                sent.append(send_value)
+                if not expect_send:
+
+                    # XXX NOTE XXX THIS WON'T WORK WITHOUT SPECIAL
+                    # `str` handling! or special debug mode IPC
+                    # msgs!
+                    await tractor.pause()
+
+                    raise RuntimeError(
+                        f'NOT-EXPECTED able to roundtrip value given spec:\n'
+                        f'ipc_pld_spec -> {ipc_pld_spec}\n'
+                        f'value -> {send_value}: {type(send_value)}\n'
+                    )
+
+                break  # move on to streaming block..
+
+            except tractor.MsgTypeError:
+                await tractor.pause()
+
+                if expect_send:
+                    raise RuntimeError(
+                        f'EXPECTED to `.started()` value given spec:\n'
+                        f'ipc_pld_spec -> {ipc_pld_spec}\n'
+                        f'value -> {send_value}: {type(send_value)}\n'
+                    )
+
+        async with ctx.open_stream() as ipc:
+            print(
+                f'{uid}: Entering streaming block to send remaining values..'
+            )
+
+            for send_value, expect_send in iter_send_val_items:
+                send_type: Type = type(send_value)
+                print(
+                    '------ - ------\n'
+                    f'{uid}: SENDING NEXT VALUE\n'
+                    f'ipc_pld_spec: {ipc_pld_spec}\n'
+                    f'expect_send: {expect_send}\n'
+                    f'val: {send_value}\n'
+                    '------ - ------\n'
+                )
+                try:
+                    await ipc.send(send_value)
+                    print(f'***\n{uid}-CHILD sent {send_value!r}\n***\n')
+                    sent.append(send_value)
+
+                    # NOTE: should only raise above on
+                    # `.started()` or a `Return`
+                    # if not expect_send:
+                    #     raise RuntimeError(
+                    #         f'NOT-EXPECTED able to roundtrip value given spec:\n'
+                    #         f'ipc_pld_spec -> {ipc_pld_spec}\n'
+                    #         f'value -> {send_value}: {send_type}\n'
+                    #     )
+
+                except ValidationError:
+                    print(f'{uid} FAILED TO SEND {send_value}!')
+
+                    # await tractor.pause()
+                    if expect_send:
+                        raise RuntimeError(
+                            f'EXPECTED to roundtrip value given spec:\n'
+                            f'ipc_pld_spec -> {ipc_pld_spec}\n'
+                            f'value -> {send_value}: {send_type}\n'
+                        )
+                    # continue
+
+            else:
+                print(
+                    f'{uid}: finished sending all values\n'
+                    'Should be exiting stream block!\n'
+                )
+
+        print(f'{uid}: exited streaming block!')
+
+        # TODO: this won't be true bc in streaming phase we DO NOT
+        # msgspec check outbound msgs!
+        # -[ ] once we implement the receiver side `InvalidMsg`
+        #   then we can expect it here?
+        # assert (
+        #     len(sent)
+        #     ==
+        #     len([val
+        #          for val, expect in
+        #          expect_ipc_send.values()
+        #          if expect is True])
+        # )
+
+
+def ex_func(*args):
+    print(f'ex_func({args})')
+
+
+@pytest.mark.parametrize(
+    'ipc_pld_spec',
+    [
+        Any,
+        NamespacePath,
+        NamespacePath|None,  # the "maybe" spec Bo
+    ],
+    ids=[
+        'any_type',
+        'nsp_type',
+        'maybe_nsp_type',
+    ]
+)
+@pytest.mark.parametrize(
+    'add_codec_hooks',
+    [
+        True,
+        False,
+    ],
+    ids=['use_codec_hooks', 'no_codec_hooks'],
+)
+def test_codec_hooks_mod(
+    debug_mode: bool,
+    ipc_pld_spec: Union[Type]|Any,
+    # send_value: None|str|NamespacePath,
+    add_codec_hooks: bool,
+):
+    '''
+    Audit the `.msg.MsgCodec` override apis details given our impl
+    uses `contextvars` to accomplish per `trio` task codec
+    application around an inter-proc-task-comms context.
+
+    '''
+    async def main():
+        nsp = NamespacePath.from_ref(ex_func)
+        send_items: dict[Union, Any] = {
+            Union[None]: None,
+            Union[NamespacePath]: nsp,
+            Union[str]: str(nsp),
+        }
+
+        # init default state for actor
+        chk_codec_applied(
+            expect_codec=_codec._def_tractor_codec,
+        )
+
+        async with tractor.open_nursery(
+            debug_mode=debug_mode,
+        ) as an:
+            p: tractor.Portal = await an.start_actor(
+                'sub',
+                enable_modules=[__name__],
+            )
+
+            # TODO: 2 cases:
+            # - codec not modified -> decode nsp as `str`
+            # - codec modified with hooks -> decode nsp as
+            #   `NamespacePath`
+            nsp_codec: MsgCodec = mk_custom_codec(
+                pld_spec=ipc_pld_spec,
+                add_hooks=add_codec_hooks,
+            )
+            with apply_codec(nsp_codec) as codec:
+                chk_codec_applied(
+                    expect_codec=nsp_codec,
+                    enter_value=codec,
+                )
+
+                expect_ipc_send: dict[str, tuple[Any, bool]] = {}
+
+                report: str = (
+                    'Parent report on send values with\n'
+                    f'ipc_pld_spec: {ipc_pld_spec}\n'
+                    '       ------ - ------\n'
+                )
+                for val_type_str, val, expect_send in iter_maybe_sends(
+                    send_items,
+                    ipc_pld_spec,
+                    add_codec_hooks=add_codec_hooks,
+                ):
+                    report += (
+                        f'send_value: {val}: {type(val)} '
+                        f'=> expect_send: {expect_send}\n'
+                    )
+                    expect_ipc_send[val_type_str] = (val, expect_send)
+
+                print(
+                    report +
+                    '       ------ - ------\n'
+                )
+                assert len(expect_ipc_send) == len(send_items)
+                # now try over real IPC with a the subactor
+                # expect_ipc_rountrip: bool = True
+                expected_started = Started(
+                    cid='cid',
+                    pld=str(ipc_pld_spec),
+                )
+                # build list of values we expect to receive from
+                # the subactor.
+                expect_to_send: list[Any] = [
+                    val
+                    for val, expect_send in expect_ipc_send.values()
+                    if expect_send
+                ]
+
+                pld_spec_type_strs: list[str] = enc_type_union(ipc_pld_spec)
+
+                # XXX should raise an mte (`MsgTypeError`)
+                # when `add_codec_hooks == False` bc the input
+                # `expect_ipc_send` kwarg has a nsp which can't be
+                # serialized!
+                #
+                # TODO:can we ensure this happens from the
+                # `Return`-side (aka the sub) as well?
+                if not add_codec_hooks:
+                    try:
+                        async with p.open_context(
+                            send_back_values,
+                            expect_debug=debug_mode,
+                            pld_spec_type_strs=pld_spec_type_strs,
+                            add_hooks=add_codec_hooks,
+                            started_msg_bytes=nsp_codec.encode(expected_started),
+
+                            # XXX NOTE bc we send a `NamespacePath` in this kwarg
+                            expect_ipc_send=expect_ipc_send,
+
+                        ) as (ctx, first):
+                            pytest.fail('ctx should fail to open without custom enc_hook!?')
+
+                    # this test passes bc we can go no further!
+                    except MsgTypeError:
+                        # teardown nursery
+                        await p.cancel_actor()
+                        return
+
+                # TODO: send the original nsp here and
+                # test with `limit_msg_spec()` above?
+                # await tractor.pause()
+                print('PARENT opening IPC ctx!\n')
+                async with (
+
+                    # XXX should raise an mte (`MsgTypeError`)
+                    # when `add_codec_hooks == False`..
+                    p.open_context(
+                        send_back_values,
+                        expect_debug=debug_mode,
+                        pld_spec_type_strs=pld_spec_type_strs,
+                        add_hooks=add_codec_hooks,
+                        started_msg_bytes=nsp_codec.encode(expected_started),
+                        expect_ipc_send=expect_ipc_send,
+                    ) as (ctx, first),
+
+                    ctx.open_stream() as ipc,
+                ):
+                    # ensure codec is still applied across
+                    # `tractor.Context` + its embedded nursery.
+                    chk_codec_applied(
+                        expect_codec=nsp_codec,
+                        enter_value=codec,
+                    )
+                    print(
+                        'root: ENTERING CONTEXT BLOCK\n'
+                        f'type(first): {type(first)}\n'
+                        f'first: {first}\n'
+                    )
+                    expect_to_send.remove(first)
+
+                    # TODO: explicit values we expect depending on
+                    # codec config!
+                    # assert first == first_val
+                    # assert first == f'{__name__}:ex_func'
+
+                    async for next_sent in ipc:
+                        print(
+                            'Parent: child sent next value\n'
+                            f'{next_sent}: {type(next_sent)}\n'
+                        )
+                        if expect_to_send:
+                            expect_to_send.remove(next_sent)
+                        else:
+                            print('PARENT should terminate stream loop + block!')
+
+                    # all sent values should have arrived!
+                    assert not expect_to_send
+
+            await p.cancel_actor()
+
+    trio.run(main)
+
+
+def chk_pld_type(
+    payload_spec: Type[Struct]|Any,
+    pld: Any,
+
+    expect_roundtrip: bool|None = None,
+
+) -> bool:
+
+    pld_val_type: Type = type(pld)
+
+    # TODO: verify that the overridden subtypes
+    # DO NOT have modified type-annots from original!
+    # 'Start',  .pld: FuncSpec
+    # 'StartAck',  .pld: IpcCtxSpec
+    # 'Stop',  .pld: UNSEt
+    # 'Error',  .pld: ErrorData
+
+    codec: MsgCodec = mk_codec(
+        # NOTE: this ONLY accepts `PayloadMsg.pld` fields of a specified
+        # type union.
+        ipc_pld_spec=payload_spec,
+    )
+
+    # make a one-off dec to compare with our `MsgCodec` instance
+    # which does the below `mk_msg_spec()` call internally
+    ipc_msg_spec: Union[Type[Struct]]
+    msg_types: list[PayloadMsg[payload_spec]]
+    (
+        ipc_msg_spec,
+        msg_types,
+    ) = mk_msg_spec(
+        payload_type_union=payload_spec,
+    )
+    _enc = msgpack.Encoder()
+    _dec = msgpack.Decoder(
+        type=ipc_msg_spec or Any,  # like `PayloadMsg[Any]`
+    )
+
+    assert (
+        payload_spec
+        ==
+        codec.pld_spec
+    )
+
+    # assert codec.dec == dec
+    #
+    # ^-XXX-^ not sure why these aren't "equal" but when cast
+    # to `str` they seem to match ?? .. kk
+
+    assert (
+        str(ipc_msg_spec)
+        ==
+        str(codec.msg_spec)
+        ==
+        str(_dec.type)
+        ==
+        str(codec.dec.type)
+    )
+
+    # verify the boxed-type for all variable payload-type msgs.
+    if not msg_types:
+        breakpoint()
+
+    roundtrip: bool|None = None
+    pld_spec_msg_names: list[str] = [
+        td.__name__ for td in _payload_msgs
+    ]
+    for typedef in msg_types:
+
+        skip_runtime_msg: bool = typedef.__name__ not in pld_spec_msg_names
+        if skip_runtime_msg:
+            continue
+
+        pld_field = structs.fields(typedef)[1]
+        assert pld_field.type is payload_spec # TODO-^ does this need to work to get all subtypes to adhere?
+
+        kwargs: dict[str, Any] = {
+            'cid': '666',
+            'pld': pld,
+        }
+        enc_msg: PayloadMsg = typedef(**kwargs)
+
+        _wire_bytes: bytes = _enc.encode(enc_msg)
+        wire_bytes: bytes = codec.enc.encode(enc_msg)
+        assert _wire_bytes == wire_bytes
+
+        ve: ValidationError|None = None
+        try:
+            dec_msg = codec.dec.decode(wire_bytes)
+            _dec_msg = _dec.decode(wire_bytes)
+
+            # decoded msg and thus payload should be exactly same!
+            assert (roundtrip := (
+                _dec_msg
+                ==
+                dec_msg
+                ==
+                enc_msg
+            ))
+
+            if (
+                expect_roundtrip is not None
+                and expect_roundtrip != roundtrip
+            ):
+                breakpoint()
+
+            assert (
+                pld
+                ==
+                dec_msg.pld
+                ==
+                enc_msg.pld
+            )
+            # assert (roundtrip := (_dec_msg == enc_msg))
+
+        except ValidationError as _ve:
+            ve = _ve
+            roundtrip: bool = False
+            if pld_val_type is payload_spec:
+                raise ValueError(
+                   'Got `ValidationError` despite type-var match!?\n'
+                    f'pld_val_type: {pld_val_type}\n'
+                    f'payload_type: {payload_spec}\n'
+                ) from ve
+
+            else:
+                # ow we good cuz the pld spec mismatched.
+                print(
+                    'Got expected `ValidationError` since,\n'
+                    f'{pld_val_type} is not {payload_spec}\n'
+                )
+        else:
+            if (
+                payload_spec is not Any
+                and
+                pld_val_type is not payload_spec
+            ):
+                raise ValueError(
+                   'DID NOT `ValidationError` despite expected type match!?\n'
+                    f'pld_val_type: {pld_val_type}\n'
+                    f'payload_type: {payload_spec}\n'
+                )
+
+    # full code decode should always be attempted!
+    if roundtrip is None:
+        breakpoint()
+
+    return roundtrip
+
+
+def test_limit_msgspec(
+    debug_mode: bool,
+):
+    async def main():
+        async with tractor.open_root_actor(
+            debug_mode=debug_mode,
+        ):
+            # ensure we can round-trip a boxing `PayloadMsg`
+            assert chk_pld_type(
+                payload_spec=Any,
+                pld=None,
+                expect_roundtrip=True,
+            )
+
+            # verify that a mis-typed payload value won't decode
+            assert not chk_pld_type(
+                payload_spec=int,
+                pld='doggy',
+            )
+
+            # parametrize the boxed `.pld` type as a custom-struct
+            # and ensure that parametrization propagates
+            # to all payload-msg-spec-able subtypes!
+            class CustomPayload(Struct):
+                name: str
+                value: Any
+
+            assert not chk_pld_type(
+                payload_spec=CustomPayload,
+                pld='doggy',
+            )
+
+            assert chk_pld_type(
+                payload_spec=CustomPayload,
+                pld=CustomPayload(name='doggy', value='urmom')
+            )
+
+            # yah, we can `.pause_from_sync()` now!
+            # breakpoint()
+
+    trio.run(main)

tests/test_context_stream_semantics.py

@@ -38,9 +38,9 @@ from tractor._testing import (
 # - standard setup/teardown:
 #   ``Portal.open_context()`` starts a new
 #   remote task context in another actor. The target actor's task must
-#   call ``Context.started()`` to unblock this entry on the parent side.
-#   the child task executes until complete and returns a final value
-#   which is delivered to the parent side and retreived via
+#   call ``Context.started()`` to unblock this entry on the caller side.
+#   the callee task executes until complete and returns a final value
+#   which is delivered to the caller side and retreived via
 #   ``Context.result()``.
 
 # - cancel termination:
@@ -170,9 +170,9 @@ async def assert_state(value: bool):
     [False, ValueError, KeyboardInterrupt],
 )
 @pytest.mark.parametrize(
-    'child_blocks_forever',
+    'callee_blocks_forever',
     [False, True],
-    ids=lambda item: f'child_blocks_forever={item}'
+    ids=lambda item: f'callee_blocks_forever={item}'
 )
 @pytest.mark.parametrize(
     'pointlessly_open_stream',
@@ -181,7 +181,7 @@ async def assert_state(value: bool):
 )
 def test_simple_context(
     error_parent,
-    child_blocks_forever,
+    callee_blocks_forever,
     pointlessly_open_stream,
     debug_mode: bool,
 ):
@@ -204,13 +204,13 @@ def test_simple_context(
                         portal.open_context(
                             simple_setup_teardown,
                             data=10,
-                            block_forever=child_blocks_forever,
+                            block_forever=callee_blocks_forever,
                         ) as (ctx, sent),
                     ):
                         assert current_ipc_ctx() is ctx
                         assert sent == 11
 
-                        if child_blocks_forever:
+                        if callee_blocks_forever:
                             await portal.run(assert_state, value=True)
                         else:
                             assert await ctx.result() == 'yo'
@@ -220,7 +220,7 @@ def test_simple_context(
                                 if error_parent:
                                     raise error_parent
 
-                                if child_blocks_forever:
+                                if callee_blocks_forever:
                                     await ctx.cancel()
                                 else:
                                     # in this case the stream will send a
@@ -259,9 +259,9 @@ def test_simple_context(
 
 
 @pytest.mark.parametrize(
-    'child_returns_early',
+    'callee_returns_early',
     [True, False],
-    ids=lambda item: f'child_returns_early={item}'
+    ids=lambda item: f'callee_returns_early={item}'
 )
 @pytest.mark.parametrize(
     'cancel_method',
@@ -273,14 +273,14 @@ def test_simple_context(
     [True, False],
     ids=lambda item: f'chk_ctx_result_before_exit={item}'
 )
-def test_parent_cancels(
+def test_caller_cancels(
     cancel_method: str,
     chk_ctx_result_before_exit: bool,
-    child_returns_early: bool,
+    callee_returns_early: bool,
     debug_mode: bool,
 ):
     '''
-    Verify that when the opening side of a context (aka the parent)
+    Verify that when the opening side of a context (aka the caller)
     cancels that context, the ctx does not raise a cancelled when
     either calling `.result()` or on context exit.
 
@@ -294,7 +294,7 @@ def test_parent_cancels(
 
         if (
             cancel_method == 'portal'
-            and not child_returns_early
+            and not callee_returns_early
         ):
             try:
                 res = await ctx.result()
@@ -318,7 +318,7 @@ def test_parent_cancels(
                 pytest.fail(f'should not have raised ctxc\n{ctxc}')
 
         # we actually get a result
-        if child_returns_early:
+        if callee_returns_early:
             assert res == 'yo'
             assert ctx.outcome is res
             assert ctx.maybe_error is None
@@ -362,14 +362,14 @@ def test_parent_cancels(
             )
             timeout: float = (
                 0.5
-                if not child_returns_early
+                if not callee_returns_early
                 else 2
             )
             with trio.fail_after(timeout):
                 async with (
                     expect_ctxc(
                         yay=(
-                            not child_returns_early
+                            not callee_returns_early
                             and cancel_method == 'portal'
                         )
                     ),
@@ -377,13 +377,13 @@ def test_parent_cancels(
                     portal.open_context(
                         simple_setup_teardown,
                         data=10,
-                        block_forever=not child_returns_early,
+                        block_forever=not callee_returns_early,
                     ) as (ctx, sent),
                 ):
 
-                    if child_returns_early:
+                    if callee_returns_early:
                         # ensure we block long enough before sending
-                        # a cancel such that the child has already
+                        # a cancel such that the callee has already
                         # returned it's result.
                         await trio.sleep(0.5)
 
@@ -421,7 +421,7 @@ def test_parent_cancels(
             #   which should in turn cause `ctx._scope` to
             # catch any cancellation?
             if (
-                not child_returns_early
+                not callee_returns_early
                 and cancel_method != 'portal'
             ):
                 assert not ctx._scope.cancelled_caught
@@ -430,11 +430,11 @@ def test_parent_cancels(
 
 
 # basic stream terminations:
-# - child context closes without using stream
-# - parent context closes without using stream
-# - parent context calls `Context.cancel()` while streaming
-#   is ongoing resulting in child being cancelled
-# - child calls `Context.cancel()` while streaming and parent
+# - callee context closes without using stream
+# - caller context closes without using stream
+# - caller context calls `Context.cancel()` while streaming
+#   is ongoing resulting in callee being cancelled
+# - callee calls `Context.cancel()` while streaming and caller
 #   sees stream terminated in `RemoteActorError`
 
 # TODO: future possible features
@@ -443,6 +443,7 @@ def test_parent_cancels(
 
 @tractor.context
 async def close_ctx_immediately(
+
     ctx: Context,
 
 ) -> None:
@@ -453,24 +454,13 @@ async def close_ctx_immediately(
     async with ctx.open_stream():
         pass
 
-    print('child returning!')
 
-
-@pytest.mark.parametrize(
-    'parent_send_before_receive',
-    [
-        False,
-        True,
-    ],
-    ids=lambda item: f'child_send_before_receive={item}'
-)
 @tractor_test
-async def test_child_exits_ctx_after_stream_open(
+async def test_callee_closes_ctx_after_stream_open(
     debug_mode: bool,
-    parent_send_before_receive: bool,
 ):
     '''
-    child context closes without using stream.
+    callee context closes without using stream.
 
     This should result in a msg sequence
     |_<root>_
@@ -484,9 +474,6 @@ async def test_child_exits_ctx_after_stream_open(
     => {'stop': True, 'cid': <str>}
 
     '''
-    timeout: float = (
-        0.5 if not debug_mode else 999
-    )
     async with tractor.open_nursery(
         debug_mode=debug_mode,
     ) as an:
@@ -495,7 +482,7 @@ async def test_child_exits_ctx_after_stream_open(
             enable_modules=[__name__],
         )
 
-        with trio.fail_after(timeout):
+        with trio.fail_after(0.5):
             async with portal.open_context(
                 close_ctx_immediately,
 
@@ -507,56 +494,41 @@ async def test_child_exits_ctx_after_stream_open(
 
                 with trio.fail_after(0.4):
                     async with ctx.open_stream() as stream:
-                        if parent_send_before_receive:
-                            print('sending first msg from parent!')
-                            await stream.send('yo')
 
                         # should fall through since ``StopAsyncIteration``
                         # should be raised through translation of
                         # a ``trio.EndOfChannel`` by
                         # ``trio.abc.ReceiveChannel.__anext__()``
-                        msg = 10
-                        async for msg in stream:
+                        async for _ in stream:
                             # trigger failure if we DO NOT
                             # get an EOC!
                             assert 0
                         else:
-                            # never should get anythinig new from
-                            # the underlying stream
-                            assert msg == 10
 
                             # verify stream is now closed
                             try:
                                 with trio.fail_after(0.3):
-                                    print('parent trying to `.receive()` on EoC stream!')
                                     await stream.receive()
-                                    assert 0, 'should have raised eoc!?'
                             except trio.EndOfChannel:
-                                print('parent got EoC as expected!')
                                 pass
-                                # raise
 
                 # TODO: should be just raise the closed resource err
                 # directly here to enforce not allowing a re-open
                 # of a stream to the context (at least until a time of
                 # if/when we decide that's a good idea?)
                 try:
-                    with trio.fail_after(timeout):
+                    with trio.fail_after(0.5):
                         async with ctx.open_stream() as stream:
                             pass
                 except trio.ClosedResourceError:
                     pass
 
-                # if ctx._rx_chan._state.data:
-                #     await tractor.pause()
-
         await portal.cancel_actor()
 
 
 @tractor.context
 async def expect_cancelled(
     ctx: Context,
-    send_before_receive: bool = False,
 
 ) -> None:
     global _state
@@ -566,10 +538,6 @@ async def expect_cancelled(
 
     try:
         async with ctx.open_stream() as stream:
-
-            if send_before_receive:
-                await stream.send('yo')
-
             async for msg in stream:
                 await stream.send(msg)  # echo server
 
@@ -596,49 +564,26 @@ async def expect_cancelled(
         raise
 
     else:
-        assert 0, "child wasn't cancelled !?"
+        assert 0, "callee wasn't cancelled !?"
 
 
-@pytest.mark.parametrize(
-    'child_send_before_receive',
-    [
-        False,
-        True,
-    ],
-    ids=lambda item: f'child_send_before_receive={item}'
-)
-@pytest.mark.parametrize(
-    'rent_wait_for_msg',
-    [
-        False,
-        True,
-    ],
-    ids=lambda item: f'rent_wait_for_msg={item}'
-)
 @pytest.mark.parametrize(
     'use_ctx_cancel_method',
-    [
-        False,
-        'pre_stream',
-        'post_stream_open',
-        'post_stream_close',
-    ],
-    ids=lambda item: f'use_ctx_cancel_method={item}'
+    [False, True],
 )
 @tractor_test
-async def test_parent_exits_ctx_after_child_enters_stream(
-    use_ctx_cancel_method: bool|str,
+async def test_caller_closes_ctx_after_callee_opens_stream(
+    use_ctx_cancel_method: bool,
     debug_mode: bool,
-    rent_wait_for_msg: bool,
-    child_send_before_receive: bool,
 ):
     '''
-    Parent-side of IPC context closes without sending on `MsgStream`.
+    caller context closes without using/opening stream
 
     '''
     async with tractor.open_nursery(
         debug_mode=debug_mode,
     ) as an:
+
         root: Actor = current_actor()
         portal = await an.start_actor(
             'ctx_cancelled',
@@ -647,52 +592,41 @@ async def test_parent_exits_ctx_after_child_enters_stream(
 
         async with portal.open_context(
             expect_cancelled,
-            send_before_receive=child_send_before_receive,
         ) as (ctx, sent):
             assert sent is None
 
             await portal.run(assert_state, value=True)
 
             # call `ctx.cancel()` explicitly
-            if use_ctx_cancel_method == 'pre_stream':
+            if use_ctx_cancel_method:
                 await ctx.cancel()
 
                 # NOTE: means the local side `ctx._scope` will
                 # have been cancelled by an ctxc ack and thus
                 # `._scope.cancelled_caught` should be set.
-                async with (
-                    expect_ctxc(
-                        # XXX: the cause is US since we call
-                        # `Context.cancel()` just above!
-                        yay=True,
-
-                        # XXX: must be propagated to __aexit__
-                        # and should be silently absorbed there
-                        # since we called `.cancel()` just above ;)
-                        reraise=True,
-                    ) as maybe_ctxc,
-                ):
+                try:
                     async with ctx.open_stream() as stream:
+                        async for msg in stream:
+                            pass
 
-                        if rent_wait_for_msg:
-                            async for msg in stream:
-                                print(f'PARENT rx: {msg!r}\n')
-                                break
+                except tractor.ContextCancelled as ctxc:
+                    # XXX: the cause is US since we call
+                    # `Context.cancel()` just above!
+                    assert (
+                        ctxc.canceller
+                        ==
+                        current_actor().uid
+                        ==
+                        root.uid
+                    )
 
-                        if use_ctx_cancel_method == 'post_stream_open':
-                            await ctx.cancel()
+                    # XXX: must be propagated to __aexit__
+                    # and should be silently absorbed there
+                    # since we called `.cancel()` just above ;)
+                    raise
 
-                    if use_ctx_cancel_method == 'post_stream_close':
-                        await ctx.cancel()
-
-                ctxc: tractor.ContextCancelled = maybe_ctxc.value
-                assert (
-                    ctxc.canceller
-                    ==
-                    current_actor().uid
-                    ==
-                    root.uid
-                )
+                else:
+                    assert 0, "Should have context cancelled?"
 
                 # channel should still be up
                 assert portal.channel.connected()
@@ -703,20 +637,13 @@ async def test_parent_exits_ctx_after_child_enters_stream(
                     value=False,
                 )
 
-            # XXX CHILD-BLOCKS case, we SHOULD NOT exit from the
-            # `.open_context()` before the child has returned,
-            # errored or been cancelled!
             else:
                 try:
-                    with trio.fail_after(
-                        0.5  # if not debug_mode else 999
-                    ):
-                        res = await ctx.wait_for_result()
-                        assert res is not tractor._context.Unresolved
+                    with trio.fail_after(0.2):
+                        await ctx.result()
                         assert 0, "Callee should have blocked!?"
                 except trio.TooSlowError:
-                    # NO-OP -> since already triggered by
-                    # `trio.fail_after()` above!
+                    # NO-OP -> since already called above
                     await ctx.cancel()
 
         # NOTE: local scope should have absorbed the cancellation since
@@ -756,7 +683,7 @@ async def test_parent_exits_ctx_after_child_enters_stream(
 
 
 @tractor_test
-async def test_multitask_parent_cancels_from_nonroot_task(
+async def test_multitask_caller_cancels_from_nonroot_task(
     debug_mode: bool,
 ):
     async with tractor.open_nursery(
@@ -808,6 +735,7 @@ async def test_multitask_parent_cancels_from_nonroot_task(
 
 @tractor.context
 async def cancel_self(
+
     ctx: Context,
 
 ) -> None:
@@ -847,11 +775,11 @@ async def cancel_self(
 
 
 @tractor_test
-async def test_child_cancels_before_started(
+async def test_callee_cancels_before_started(
     debug_mode: bool,
 ):
     '''
-    Callee calls `Context.cancel()` while streaming and parent
+    Callee calls `Context.cancel()` while streaming and caller
     sees stream terminated in `ContextCancelled`.
 
     '''
@@ -898,13 +826,14 @@ async def never_open_stream(
 
 
 @tractor.context
-async def keep_sending_from_child(
+async def keep_sending_from_callee(
+
     ctx:  Context,
     msg_buffer_size: int|None = None,
 
 ) -> None:
     '''
-    Send endlessly on the child stream.
+    Send endlessly on the calleee stream.
 
     '''
     await ctx.started()
@@ -912,7 +841,7 @@ async def keep_sending_from_child(
         msg_buffer_size=msg_buffer_size,
     ) as stream:
         for msg in count():
-            print(f'child sending {msg}')
+            print(f'callee sending {msg}')
             await stream.send(msg)
             await trio.sleep(0.01)
 
@@ -920,12 +849,12 @@ async def keep_sending_from_child(
 @pytest.mark.parametrize(
     'overrun_by',
     [
-        ('parent', 1, never_open_stream),
-        ('child', 0, keep_sending_from_child),
+        ('caller', 1, never_open_stream),
+        ('callee', 0, keep_sending_from_callee),
     ],
     ids=[
-         ('parent_1buf_never_open_stream'),
-         ('child_0buf_keep_sending_from_child'),
+         ('caller_1buf_never_open_stream'),
+         ('callee_0buf_keep_sending_from_callee'),
     ]
 )
 def test_one_end_stream_not_opened(
@@ -956,7 +885,8 @@ def test_one_end_stream_not_opened(
                 ) as (ctx, sent):
                     assert sent is None
 
-                    if 'parent' in overrunner:
+                    if 'caller' in overrunner:
+
                         async with ctx.open_stream() as stream:
 
                             # itersend +1 msg more then the buffer size
@@ -971,7 +901,7 @@ def test_one_end_stream_not_opened(
                                 await trio.sleep_forever()
 
                     else:
-                        # child overruns parent case so we do nothing here
+                        # callee overruns caller case so we do nothing here
                         await trio.sleep_forever()
 
             await portal.cancel_actor()
@@ -979,19 +909,19 @@ def test_one_end_stream_not_opened(
     # 2 overrun cases and the no overrun case (which pushes right up to
     # the msg limit)
     if (
-        overrunner == 'parent'
+        overrunner == 'caller'
     ):
         with pytest.raises(tractor.RemoteActorError) as excinfo:
             trio.run(main)
 
         assert excinfo.value.boxed_type == StreamOverrun
 
-    elif overrunner == 'child':
+    elif overrunner == 'callee':
         with pytest.raises(tractor.RemoteActorError) as excinfo:
             trio.run(main)
 
         # TODO: embedded remote errors so that we can verify the source
-        # error? the child delivers an error which is an overrun
+        # error? the callee delivers an error which is an overrun
         # wrapped in a remote actor error.
         assert excinfo.value.boxed_type == tractor.RemoteActorError
 
@@ -1001,7 +931,8 @@ def test_one_end_stream_not_opened(
 
 @tractor.context
 async def echo_back_sequence(
-    ctx: Context,
+
+    ctx:  Context,
     seq: list[int],
     wait_for_cancel: bool,
     allow_overruns_side: str,
@@ -1010,12 +941,12 @@ async def echo_back_sequence(
 
 ) -> None:
     '''
-    Send endlessly on the child stream using a small buffer size
+    Send endlessly on the calleee stream using a small buffer size
     setting on the contex to simulate backlogging that would normally
     cause overruns.
 
     '''
-    # NOTE: ensure that if the parent is expecting to cancel this task
+    # NOTE: ensure that if the caller is expecting to cancel this task
     # that we stay echoing much longer then they are so we don't
     # return early instead of receive the cancel msg.
     total_batches: int = (
@@ -1065,18 +996,18 @@ async def echo_back_sequence(
                 if be_slow:
                     await trio.sleep(0.05)
 
-                print('child waiting on next')
+                print('callee waiting on next')
 
-            print(f'child echoing back latest batch\n{batch}')
+            print(f'callee echoing back latest batch\n{batch}')
             for msg in batch:
-                print(f'child sending msg\n{msg}')
+                print(f'callee sending msg\n{msg}')
                 await stream.send(msg)
 
     try:
         return 'yo'
     finally:
         print(
-            'exiting child with context:\n'
+            'exiting callee with context:\n'
             f'{pformat(ctx)}\n'
         )
 
@@ -1130,7 +1061,7 @@ def test_maybe_allow_overruns_stream(
             debug_mode=debug_mode,
         ) as an:
             portal = await an.start_actor(
-                'child_sends_forever',
+                'callee_sends_forever',
                 enable_modules=[__name__],
                 loglevel=loglevel,
                 debug_mode=debug_mode,

tests/test_ext_types_msgspec.py

@@ -1,946 +0,0 @@
-'''
-Low-level functional audits for our
-"capability based messaging"-spec feats.
-
-B~)
-
-'''
-from contextlib import (
-    contextmanager as cm,
-    # nullcontext,
-)
-import importlib
-from typing import (
-    Any,
-    Type,
-    Union,
-)
-
-from msgspec import (
-    # structs,
-    # msgpack,
-    Raw,
-    # Struct,
-    ValidationError,
-)
-import pytest
-import trio
-
-import tractor
-from tractor import (
-    Actor,
-    # _state,
-    MsgTypeError,
-    Context,
-)
-from tractor.msg import (
-    _codec,
-    _ctxvar_MsgCodec,
-    _exts,
-
-    NamespacePath,
-    MsgCodec,
-    MsgDec,
-    mk_codec,
-    mk_dec,
-    apply_codec,
-    current_codec,
-)
-from tractor.msg.types import (
-    log,
-    Started,
-    # _payload_msgs,
-    # PayloadMsg,
-    # mk_msg_spec,
-)
-from tractor.msg._ops import (
-    limit_plds,
-)
-
-def enc_nsp(obj: Any) -> Any:
-    actor: Actor = tractor.current_actor(
-        err_on_no_runtime=False,
-    )
-    uid: tuple[str, str]|None = None if not actor else actor.uid
-    print(f'{uid} ENC HOOK')
-
-    match obj:
-        # case NamespacePath()|str():
-        case NamespacePath():
-            encoded: str = str(obj)
-            print(
-                f'----- ENCODING `NamespacePath` as `str` ------\n'
-                f'|_obj:{type(obj)!r} = {obj!r}\n'
-                f'|_encoded: str = {encoded!r}\n'
-            )
-            # if type(obj) != NamespacePath:
-            #     breakpoint()
-            return encoded
-        case _:
-            logmsg: str = (
-                f'{uid}\n'
-                'FAILED ENCODE\n'
-                f'obj-> `{obj}: {type(obj)}`\n'
-            )
-            raise NotImplementedError(logmsg)
-
-
-def dec_nsp(
-    obj_type: Type,
-    obj: Any,
-
-) -> Any:
-    # breakpoint()
-    actor: Actor = tractor.current_actor(
-        err_on_no_runtime=False,
-    )
-    uid: tuple[str, str]|None = None if not actor else actor.uid
-    print(
-        f'{uid}\n'
-        'CUSTOM DECODE\n'
-        f'type-arg-> {obj_type}\n'
-        f'obj-arg-> `{obj}`: {type(obj)}\n'
-    )
-    nsp = None
-    # XXX, never happens right?
-    if obj_type is Raw:
-        breakpoint()
-
-    if (
-        obj_type is NamespacePath
-        and isinstance(obj, str)
-        and ':' in obj
-    ):
-        nsp = NamespacePath(obj)
-        # TODO: we could built a generic handler using
-        # JUST matching the obj_type part?
-        # nsp = obj_type(obj)
-
-    if nsp:
-        print(f'Returning NSP instance: {nsp}')
-        return nsp
-
-    logmsg: str = (
-        f'{uid}\n'
-        'FAILED DECODE\n'
-        f'type-> {obj_type}\n'
-        f'obj-arg-> `{obj}`: {type(obj)}\n\n'
-        f'current codec:\n'
-        f'{current_codec()}\n'
-    )
-    # TODO: figure out the ignore subsys for this!
-    # -[ ] option whether to defense-relay backc the msg
-    #   inside an `Invalid`/`Ignore`
-    # -[ ] how to make this handling pluggable such that a
-    #   `Channel`/`MsgTransport` can intercept and process
-    #   back msgs either via exception handling or some other
-    #   signal?
-    log.warning(logmsg)
-    # NOTE: this delivers the invalid
-    # value up to `msgspec`'s decoding
-    # machinery for error raising.
-    return obj
-    # raise NotImplementedError(logmsg)
-
-
-def ex_func(*args):
-    '''
-    A mod level func we can ref and load via our `NamespacePath`
-    python-object pointer `str` subtype.
-
-    '''
-    print(f'ex_func({args})')
-
-
-@pytest.mark.parametrize(
-    'add_codec_hooks',
-    [
-        True,
-        False,
-    ],
-    ids=['use_codec_hooks', 'no_codec_hooks'],
-)
-def test_custom_extension_types(
-    debug_mode: bool,
-    add_codec_hooks: bool
-):
-    '''
-    Verify that a `MsgCodec` (used for encoding all outbound IPC msgs
-    and decoding all inbound `PayloadMsg`s) and a paired `MsgDec`
-    (used for decoding the `PayloadMsg.pld: Raw` received within a given
-    task's ipc `Context` scope) can both send and receive "extension types"
-    as supported via custom converter hooks passed to `msgspec`.
-
-    '''
-    nsp_pld_dec: MsgDec = mk_dec(
-        spec=None,  # ONLY support the ext type
-        dec_hook=dec_nsp if add_codec_hooks else None,
-        ext_types=[NamespacePath],
-    )
-    nsp_codec: MsgCodec = mk_codec(
-        # ipc_pld_spec=Raw,  # default!
-
-        # NOTE XXX: the encode hook MUST be used no matter what since
-        # our `NamespacePath` is not any of a `Any` native type nor
-        # a `msgspec.Struct` subtype - so `msgspec` has no way to know
-        # how to encode it unless we provide the custom hook.
-        #
-        # AGAIN that is, regardless of whether we spec an
-        # `Any`-decoded-pld the enc has no knowledge (by default)
-        # how to enc `NamespacePath` (nsp), so we add a custom
-        # hook to do that ALWAYS.
-        enc_hook=enc_nsp if add_codec_hooks else None,
-
-        # XXX NOTE: pretty sure this is mutex with the `type=` to
-        # `Decoder`? so it won't work in tandem with the
-        # `ipc_pld_spec` passed above?
-        ext_types=[NamespacePath],
-
-        # TODO? is it useful to have the `.pld` decoded *prior* to
-        # the `PldRx`?? like perf or mem related?
-        # ext_dec=nsp_pld_dec,
-    )
-    if add_codec_hooks:
-        assert nsp_codec.dec.dec_hook is None
-
-        # TODO? if we pass `ext_dec` above?
-        # assert nsp_codec.dec.dec_hook is dec_nsp
-
-        assert nsp_codec.enc.enc_hook is enc_nsp
-
-    nsp = NamespacePath.from_ref(ex_func)
-
-    try:
-        nsp_bytes: bytes = nsp_codec.encode(nsp)
-        nsp_rt_sin_msg = nsp_pld_dec.decode(nsp_bytes)
-        nsp_rt_sin_msg.load_ref() is ex_func
-    except TypeError:
-        if not add_codec_hooks:
-            pass
-
-    try:
-        msg_bytes: bytes = nsp_codec.encode(
-            Started(
-                cid='cid',
-                pld=nsp,
-            )
-        )
-        # since the ext-type obj should also be set as the msg.pld
-        assert nsp_bytes in msg_bytes
-        started_rt: Started = nsp_codec.decode(msg_bytes)
-        pld: Raw = started_rt.pld
-        assert isinstance(pld, Raw)
-        nsp_rt: NamespacePath = nsp_pld_dec.decode(pld)
-        assert isinstance(nsp_rt, NamespacePath)
-        # in obj comparison terms they should be the same
-        assert nsp_rt == nsp
-        # ensure we've decoded to ext type!
-        assert nsp_rt.load_ref() is ex_func
-
-    except TypeError:
-        if not add_codec_hooks:
-            pass
-
-@tractor.context
-async def sleep_forever_in_sub(
-    ctx: Context,
-) -> None:
-    await trio.sleep_forever()
-
-
-def mk_custom_codec(
-    add_hooks: bool,
-
-) -> tuple[
-    MsgCodec,  # encode to send
-    MsgDec,  # pld receive-n-decode
-]:
-    '''
-    Create custom `msgpack` enc/dec-hooks and set a `Decoder`
-    which only loads `pld_spec` (like `NamespacePath`) types.
-
-    '''
-
-    # XXX NOTE XXX: despite defining `NamespacePath` as a type
-    # field on our `PayloadMsg.pld`, we still need a enc/dec_hook() pair
-    # to cast to/from that type on the wire. See the docs:
-    # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
-
-    # if pld_spec is Any:
-    #     pld_spec = Raw
-
-    nsp_codec: MsgCodec = mk_codec(
-        # ipc_pld_spec=Raw,  # default!
-
-        # NOTE XXX: the encode hook MUST be used no matter what since
-        # our `NamespacePath` is not any of a `Any` native type nor
-        # a `msgspec.Struct` subtype - so `msgspec` has no way to know
-        # how to encode it unless we provide the custom hook.
-        #
-        # AGAIN that is, regardless of whether we spec an
-        # `Any`-decoded-pld the enc has no knowledge (by default)
-        # how to enc `NamespacePath` (nsp), so we add a custom
-        # hook to do that ALWAYS.
-        enc_hook=enc_nsp if add_hooks else None,
-
-        # XXX NOTE: pretty sure this is mutex with the `type=` to
-        # `Decoder`? so it won't work in tandem with the
-        # `ipc_pld_spec` passed above?
-        ext_types=[NamespacePath],
-    )
-    # dec_hook=dec_nsp if add_hooks else None,
-    return nsp_codec
-
-
-@pytest.mark.parametrize(
-    'limit_plds_args',
-    [
-        (
-            {'dec_hook': None, 'ext_types': None},
-            None,
-        ),
-        (
-            {'dec_hook': dec_nsp, 'ext_types': None},
-            TypeError,
-        ),
-        (
-            {'dec_hook': dec_nsp, 'ext_types': [NamespacePath]},
-            None,
-        ),
-        (
-            {'dec_hook': dec_nsp, 'ext_types': [NamespacePath|None]},
-            None,
-        ),
-    ],
-    ids=[
-        'no_hook_no_ext_types',
-        'only_hook',
-        'hook_and_ext_types',
-        'hook_and_ext_types_w_null',
-    ]
-)
-def test_pld_limiting_usage(
-    limit_plds_args: tuple[dict, Exception|None],
-):
-    '''
-    Verify `dec_hook()` and `ext_types` need to either both be
-    provided or we raise a explanator type-error.
-
-    '''
-    kwargs, maybe_err = limit_plds_args
-    async def main():
-        async with tractor.open_nursery() as an:  # just to open runtime
-
-            # XXX SHOULD NEVER WORK outside an ipc ctx scope!
-            try:
-                with limit_plds(**kwargs):
-                    pass
-            except RuntimeError:
-                pass
-
-            p: tractor.Portal = await an.start_actor(
-                'sub',
-                enable_modules=[__name__],
-            )
-            async with (
-                p.open_context(
-                    sleep_forever_in_sub
-                ) as (ctx, first),
-            ):
-                try:
-                    with limit_plds(**kwargs):
-                        pass
-                except maybe_err as exc:
-                    assert type(exc) is maybe_err
-                    pass
-
-
-def chk_codec_applied(
-    expect_codec: MsgCodec|None,
-    enter_value: MsgCodec|None = None,
-
-) -> MsgCodec:
-    '''
-    buncha sanity checks ensuring that the IPC channel's
-    context-vars are set to the expected codec and that are
-    ctx-var wrapper APIs match the same.
-
-    '''
-    # TODO: play with tricyle again, bc this is supposed to work
-    # the way we want?
-    #
-    # TreeVar
-    # task: trio.Task = trio.lowlevel.current_task()
-    # curr_codec = _ctxvar_MsgCodec.get_in(task)
-
-    # ContextVar
-    # task_ctx: Context = task.context
-    # assert _ctxvar_MsgCodec in task_ctx
-    # curr_codec: MsgCodec = task.context[_ctxvar_MsgCodec]
-    if expect_codec is None:
-        assert enter_value is None
-        return
-
-    # NOTE: currently we use this!
-    # RunVar
-    curr_codec: MsgCodec = current_codec()
-    last_read_codec = _ctxvar_MsgCodec.get()
-    # assert curr_codec is last_read_codec
-
-    assert (
-        (same_codec := expect_codec) is
-        # returned from `mk_codec()`
-
-        # yielded value from `apply_codec()`
-
-        # read from current task's `contextvars.Context`
-        curr_codec is
-        last_read_codec
-
-        # the default `msgspec` settings
-        is not _codec._def_msgspec_codec
-        is not _codec._def_tractor_codec
-    )
-
-    if enter_value:
-        assert enter_value is same_codec
-
-
-@tractor.context
-async def send_back_values(
-    ctx: Context,
-    rent_pld_spec_type_strs: list[str],
-    add_hooks: bool,
-
-) -> None:
-    '''
-    Setup up a custom codec to load instances of `NamespacePath`
-    and ensure we can round trip a func ref with our parent.
-
-    '''
-    uid: tuple = tractor.current_actor().uid
-
-    # init state in sub-actor should be default
-    chk_codec_applied(
-        expect_codec=_codec._def_tractor_codec,
-    )
-
-    # load pld spec from input str
-    rent_pld_spec = _exts.dec_type_union(
-        rent_pld_spec_type_strs,
-        mods=[
-            importlib.import_module(__name__),
-        ],
-    )
-    rent_pld_spec_types: set[Type] = _codec.unpack_spec_types(
-        rent_pld_spec,
-    )
-
-    # ONLY add ext-hooks if the rent specified a non-std type!
-    add_hooks: bool = (
-        NamespacePath in rent_pld_spec_types
-        and
-        add_hooks
-    )
-
-    # same as on parent side config.
-    nsp_codec: MsgCodec|None = None
-    if add_hooks:
-        nsp_codec = mk_codec(
-            enc_hook=enc_nsp,
-            ext_types=[NamespacePath],
-        )
-
-    with (
-        maybe_apply_codec(nsp_codec) as codec,
-        limit_plds(
-            rent_pld_spec,
-            dec_hook=dec_nsp if add_hooks else None,
-            ext_types=[NamespacePath]  if add_hooks else None,
-        ) as pld_dec,
-    ):
-        # ?XXX? SHOULD WE NOT be swapping the global codec since it
-        # breaks `Context.started()` roundtripping checks??
-        chk_codec_applied(
-            expect_codec=nsp_codec,
-            enter_value=codec,
-        )
-
-        # ?TODO, mismatch case(s)?
-        #
-        # ensure pld spec matches on both sides
-        ctx_pld_dec: MsgDec = ctx._pld_rx._pld_dec
-        assert pld_dec is ctx_pld_dec
-        child_pld_spec: Type = pld_dec.spec
-        child_pld_spec_types: set[Type] = _codec.unpack_spec_types(
-            child_pld_spec,
-        )
-        assert (
-            child_pld_spec_types.issuperset(
-                rent_pld_spec_types
-            )
-        )
-
-        # ?TODO, try loop for each of the types in pld-superset?
-        #
-        # for send_value in [
-        #     nsp,
-        #     str(nsp),
-        #     None,
-        # ]:
-        nsp = NamespacePath.from_ref(ex_func)
-        try:
-            print(
-                f'{uid}: attempting to `.started({nsp})`\n'
-                f'\n'
-                f'rent_pld_spec: {rent_pld_spec}\n'
-                f'child_pld_spec: {child_pld_spec}\n'
-                f'codec: {codec}\n'
-            )
-            # await tractor.pause()
-            await ctx.started(nsp)
-
-        except tractor.MsgTypeError as _mte:
-            mte = _mte
-
-            # false -ve case
-            if add_hooks:
-                raise RuntimeError(
-                    f'EXPECTED to `.started()` value given spec ??\n\n'
-                    f'child_pld_spec -> {child_pld_spec}\n'
-                    f'value = {nsp}: {type(nsp)}\n'
-                )
-
-            # true -ve case
-            raise mte
-
-        # TODO: maybe we should add our own wrapper error so as to
-        # be interchange-lib agnostic?
-        # -[ ] the error type is wtv is raised from the hook so we
-        #   could also require a type-class of errors for
-        #   indicating whether the hook-failure can be handled by
-        #   a nasty-dialog-unprot sub-sys?
-        except TypeError as typerr:
-            # false -ve
-            if add_hooks:
-                raise RuntimeError('Should have been able to send `nsp`??')
-
-            # true -ve
-            print('Failed to send `nsp` due to no ext hooks set!')
-            raise typerr
-
-        # now try sending a set of valid and invalid plds to ensure
-        # the pld spec is respected.
-        sent: list[Any] = []
-        async with ctx.open_stream() as ipc:
-            print(
-                f'{uid}: streaming all pld types to rent..'
-            )
-
-            # for send_value, expect_send in iter_send_val_items:
-            for send_value in [
-                nsp,
-                str(nsp),
-                None,
-            ]:
-                send_type: Type = type(send_value)
-                print(
-                    f'{uid}: SENDING NEXT pld\n'
-                    f'send_type: {send_type}\n'
-                    f'send_value: {send_value}\n'
-                )
-                try:
-                    await ipc.send(send_value)
-                    sent.append(send_value)
-
-                except ValidationError as valerr:
-                    print(f'{uid} FAILED TO SEND {send_value}!')
-
-                    # false -ve
-                    if add_hooks:
-                        raise RuntimeError(
-                            f'EXPECTED to roundtrip value given spec:\n'
-                            f'rent_pld_spec -> {rent_pld_spec}\n'
-                            f'child_pld_spec -> {child_pld_spec}\n'
-                            f'value = {send_value}: {send_type}\n'
-                        )
-
-                    # true -ve
-                    raise valerr
-                    # continue
-
-            else:
-                print(
-                    f'{uid}: finished sending all values\n'
-                    'Should be exiting stream block!\n'
-                )
-
-        print(f'{uid}: exited streaming block!')
-
-
-
-@cm
-def maybe_apply_codec(codec: MsgCodec|None) -> MsgCodec|None:
-    if codec is None:
-        yield None
-        return
-
-    with apply_codec(codec) as codec:
-        yield codec
-
-
-@pytest.mark.parametrize(
-    'pld_spec',
-    [
-        Any,
-        NamespacePath,
-        NamespacePath|None,  # the "maybe" spec Bo
-    ],
-    ids=[
-        'any_type',
-        'only_nsp_ext',
-        'maybe_nsp_ext',
-    ]
-)
-@pytest.mark.parametrize(
-    'add_hooks',
-    [
-        True,
-        False,
-    ],
-    ids=[
-        'use_codec_hooks',
-        'no_codec_hooks',
-    ],
-)
-def test_ext_types_over_ipc(
-    debug_mode: bool,
-    pld_spec: Union[Type],
-    add_hooks: bool,
-):
-    '''
-    Ensure we can support extension types coverted using
-    `enc/dec_hook()`s passed to the `.msg.limit_plds()` API
-    and that sane errors happen when we try do the same without
-    the codec hooks.
-
-    '''
-    pld_types: set[Type] = _codec.unpack_spec_types(pld_spec)
-
-    async def main():
-
-        # sanity check the default pld-spec beforehand
-        chk_codec_applied(
-            expect_codec=_codec._def_tractor_codec,
-        )
-
-        # extension type we want to send as msg payload
-        nsp = NamespacePath.from_ref(ex_func)
-
-        # ^NOTE, 2 cases:
-        # - codec hooks noto added -> decode nsp as `str`
-        # - codec with hooks -> decode nsp as `NamespacePath`
-        nsp_codec: MsgCodec|None = None
-        if (
-            NamespacePath in pld_types
-            and
-            add_hooks
-        ):
-            nsp_codec = mk_codec(
-                enc_hook=enc_nsp,
-                ext_types=[NamespacePath],
-            )
-
-        async with tractor.open_nursery(
-            debug_mode=debug_mode,
-        ) as an:
-            p: tractor.Portal = await an.start_actor(
-                'sub',
-                enable_modules=[__name__],
-            )
-            with (
-                maybe_apply_codec(nsp_codec) as codec,
-            ):
-                chk_codec_applied(
-                    expect_codec=nsp_codec,
-                    enter_value=codec,
-                )
-                rent_pld_spec_type_strs: list[str] = _exts.enc_type_union(pld_spec)
-
-                # XXX should raise an mte (`MsgTypeError`)
-                # when `add_hooks == False` bc the input
-                # `expect_ipc_send` kwarg has a nsp which can't be
-                # serialized!
-                #
-                # TODO:can we ensure this happens from the
-                # `Return`-side (aka the sub) as well?
-                try:
-                    ctx: tractor.Context
-                    ipc: tractor.MsgStream
-                    async with (
-
-                        # XXX should raise an mte (`MsgTypeError`)
-                        # when `add_hooks == False`..
-                        p.open_context(
-                            send_back_values,
-                            # expect_debug=debug_mode,
-                            rent_pld_spec_type_strs=rent_pld_spec_type_strs,
-                            add_hooks=add_hooks,
-                            # expect_ipc_send=expect_ipc_send,
-                        ) as (ctx, first),
-
-                        ctx.open_stream() as ipc,
-                    ):
-                        with (
-                            limit_plds(
-                                pld_spec,
-                                dec_hook=dec_nsp if add_hooks else None,
-                                ext_types=[NamespacePath]  if add_hooks else None,
-                            ) as pld_dec,
-                        ):
-                            ctx_pld_dec: MsgDec = ctx._pld_rx._pld_dec
-                            assert pld_dec is ctx_pld_dec
-
-                            # if (
-                            #     not add_hooks
-                            #     and
-                            #     NamespacePath in 
-                            # ):
-                            #     pytest.fail('ctx should fail to open without custom enc_hook!?')
-
-                            await ipc.send(nsp)
-                            nsp_rt = await ipc.receive()
-
-                            assert nsp_rt == nsp
-                            assert nsp_rt.load_ref() is ex_func
-
-                # this test passes bc we can go no further!
-                except MsgTypeError as mte:
-                    # if not add_hooks:
-                    #     # teardown nursery
-                    #     await p.cancel_actor()
-                        # return
-
-                    raise mte
-
-            await p.cancel_actor()
-
-    if (
-        NamespacePath in pld_types
-        and
-        add_hooks
-    ):
-        trio.run(main)
-
-    else:
-        with pytest.raises(
-            expected_exception=tractor.RemoteActorError,
-        ) as excinfo:
-            trio.run(main)
-
-        exc = excinfo.value
-        # bc `.started(nsp: NamespacePath)` will raise
-        assert exc.boxed_type is TypeError
-
-
-# def chk_pld_type(
-#     payload_spec: Type[Struct]|Any,
-#     pld: Any,
-
-#     expect_roundtrip: bool|None = None,
-
-# ) -> bool:
-
-#     pld_val_type: Type = type(pld)
-
-#     # TODO: verify that the overridden subtypes
-#     # DO NOT have modified type-annots from original!
-#     # 'Start',  .pld: FuncSpec
-#     # 'StartAck',  .pld: IpcCtxSpec
-#     # 'Stop',  .pld: UNSEt
-#     # 'Error',  .pld: ErrorData
-
-#     codec: MsgCodec = mk_codec(
-#         # NOTE: this ONLY accepts `PayloadMsg.pld` fields of a specified
-#         # type union.
-#         ipc_pld_spec=payload_spec,
-#     )
-
-#     # make a one-off dec to compare with our `MsgCodec` instance
-#     # which does the below `mk_msg_spec()` call internally
-#     ipc_msg_spec: Union[Type[Struct]]
-#     msg_types: list[PayloadMsg[payload_spec]]
-#     (
-#         ipc_msg_spec,
-#         msg_types,
-#     ) = mk_msg_spec(
-#         payload_type_union=payload_spec,
-#     )
-#     _enc = msgpack.Encoder()
-#     _dec = msgpack.Decoder(
-#         type=ipc_msg_spec or Any,  # like `PayloadMsg[Any]`
-#     )
-
-#     assert (
-#         payload_spec
-#         ==
-#         codec.pld_spec
-#     )
-
-#     # assert codec.dec == dec
-#     #
-#     # ^-XXX-^ not sure why these aren't "equal" but when cast
-#     # to `str` they seem to match ?? .. kk
-
-#     assert (
-#         str(ipc_msg_spec)
-#         ==
-#         str(codec.msg_spec)
-#         ==
-#         str(_dec.type)
-#         ==
-#         str(codec.dec.type)
-#     )
-
-#     # verify the boxed-type for all variable payload-type msgs.
-#     if not msg_types:
-#         breakpoint()
-
-#     roundtrip: bool|None = None
-#     pld_spec_msg_names: list[str] = [
-#         td.__name__ for td in _payload_msgs
-#     ]
-#     for typedef in msg_types:
-
-#         skip_runtime_msg: bool = typedef.__name__ not in pld_spec_msg_names
-#         if skip_runtime_msg:
-#             continue
-
-#         pld_field = structs.fields(typedef)[1]
-#         assert pld_field.type is payload_spec # TODO-^ does this need to work to get all subtypes to adhere?
-
-#         kwargs: dict[str, Any] = {
-#             'cid': '666',
-#             'pld': pld,
-#         }
-#         enc_msg: PayloadMsg = typedef(**kwargs)
-
-#         _wire_bytes: bytes = _enc.encode(enc_msg)
-#         wire_bytes: bytes = codec.enc.encode(enc_msg)
-#         assert _wire_bytes == wire_bytes
-
-#         ve: ValidationError|None = None
-#         try:
-#             dec_msg = codec.dec.decode(wire_bytes)
-#             _dec_msg = _dec.decode(wire_bytes)
-
-#             # decoded msg and thus payload should be exactly same!
-#             assert (roundtrip := (
-#                 _dec_msg
-#                 ==
-#                 dec_msg
-#                 ==
-#                 enc_msg
-#             ))
-
-#             if (
-#                 expect_roundtrip is not None
-#                 and expect_roundtrip != roundtrip
-#             ):
-#                 breakpoint()
-
-#             assert (
-#                 pld
-#                 ==
-#                 dec_msg.pld
-#                 ==
-#                 enc_msg.pld
-#             )
-#             # assert (roundtrip := (_dec_msg == enc_msg))
-
-#         except ValidationError as _ve:
-#             ve = _ve
-#             roundtrip: bool = False
-#             if pld_val_type is payload_spec:
-#                 raise ValueError(
-#                    'Got `ValidationError` despite type-var match!?\n'
-#                     f'pld_val_type: {pld_val_type}\n'
-#                     f'payload_type: {payload_spec}\n'
-#                 ) from ve
-
-#             else:
-#                 # ow we good cuz the pld spec mismatched.
-#                 print(
-#                     'Got expected `ValidationError` since,\n'
-#                     f'{pld_val_type} is not {payload_spec}\n'
-#                 )
-#         else:
-#             if (
-#                 payload_spec is not Any
-#                 and
-#                 pld_val_type is not payload_spec
-#             ):
-#                 raise ValueError(
-#                    'DID NOT `ValidationError` despite expected type match!?\n'
-#                     f'pld_val_type: {pld_val_type}\n'
-#                     f'payload_type: {payload_spec}\n'
-#                 )
-
-#     # full code decode should always be attempted!
-#     if roundtrip is None:
-#         breakpoint()
-
-#     return roundtrip
-
-
-# ?TODO? maybe remove since covered in the newer `test_pldrx_limiting`
-# via end-2-end testing of all this?
-# -[ ] IOW do we really NEED this lowlevel unit testing?
-#
-# def test_limit_msgspec(
-#     debug_mode: bool,
-# ):
-#     '''
-#     Internals unit testing to verify that type-limiting an IPC ctx's
-#     msg spec with `Pldrx.limit_plds()` results in various
-#     encapsulated `msgspec` object settings and state.
-
-#     '''
-#     async def main():
-#         async with tractor.open_root_actor(
-#             debug_mode=debug_mode,
-#         ):
-#             # ensure we can round-trip a boxing `PayloadMsg`
-#             assert chk_pld_type(
-#                 payload_spec=Any,
-#                 pld=None,
-#                 expect_roundtrip=True,
-#             )
-
-#             # verify that a mis-typed payload value won't decode
-#             assert not chk_pld_type(
-#                 payload_spec=int,
-#                 pld='doggy',
-#             )
-
-#             # parametrize the boxed `.pld` type as a custom-struct
-#             # and ensure that parametrization propagates
-#             # to all payload-msg-spec-able subtypes!
-#             class CustomPayload(Struct):
-#                 name: str
-#                 value: Any
-
-#             assert not chk_pld_type(
-#                 payload_spec=CustomPayload,
-#                 pld='doggy',
-#             )
-
-#             assert chk_pld_type(
-#                 payload_spec=CustomPayload,
-#                 pld=CustomPayload(name='doggy', value='urmom')
-#             )
-
-#             # yah, we can `.pause_from_sync()` now!
-#             # breakpoint()
-
-#     trio.run(main)

tractor/__init__.py

@@ -67,4 +67,4 @@ from ._root import (
 from ._ipc import Channel as Channel
 from ._portal import Portal as Portal
 from ._runtime import Actor as Actor
-# from . import hilevel as hilevel
+from . import hilevel as hilevel

tractor/_context.py

@@ -47,9 +47,6 @@ from functools import partial
 import inspect
 from pprint import pformat
 import textwrap
-from types import (
-    UnionType,
-)
 from typing import (
     Any,
     AsyncGenerator,
@@ -82,7 +79,6 @@ from .msg import (
     MsgType,
     NamespacePath,
     PayloadT,
-    Return,
     Started,
     Stop,
     Yield,
@@ -246,13 +242,11 @@ class Context:
     # a drain loop?
     # _res_scope: trio.CancelScope|None = None
 
-    _outcome_msg: Return|Error|ContextCancelled = Unresolved
-
     # on a clean exit there should be a final value
     # delivered from the far end "callee" task, so
     # this value is only set on one side.
     # _result: Any | int = None
-    _result: PayloadT|Unresolved = Unresolved
+    _result: Any|Unresolved = Unresolved
 
     # if the local "caller"  task errors this value is always set
     # to the error that was captured in the
@@ -1202,11 +1196,9 @@ class Context:
 
         '''
         __tracebackhide__: bool = hide_tb
-        if not self._portal:
-            raise RuntimeError(
-                'Invalid usage of `Context.wait_for_result()`!\n'
-                'Not valid on child-side IPC ctx!\n'
-            )
+        assert self._portal, (
+            '`Context.wait_for_result()` can not be called from callee side!'
+        )
         if self._final_result_is_set():
             return self._result
 
@@ -1227,8 +1219,6 @@ class Context:
             # since every message should be delivered via the normal
             # `._deliver_msg()` route which will appropriately set
             # any `.maybe_error`.
-            outcome_msg: Return|Error|ContextCancelled
-            drained_msgs: list[MsgType]
             (
                 outcome_msg,
                 drained_msgs,
@@ -1236,19 +1226,11 @@ class Context:
                 ctx=self,
                 hide_tb=hide_tb,
             )
+
             drained_status: str = (
                 'Ctx drained to final outcome msg\n\n'
                 f'{outcome_msg}\n'
             )
-
-            # ?XXX, should already be set in `._deliver_msg()` right?
-            if self._outcome_msg is not Unresolved:
-                # from .devx import _debug
-                # await _debug.pause()
-                assert self._outcome_msg is outcome_msg
-            else:
-                self._outcome_msg = outcome_msg
-
             if drained_msgs:
                 drained_status += (
                     '\n'
@@ -1756,6 +1738,7 @@ class Context:
 
                 f'{structfmt(msg)}\n'
             )
+
             # NOTE: if an error is deteced we should always still
             # send it through the feeder-mem-chan and expect
             # it to be raised by any context (stream) consumer
@@ -1767,21 +1750,6 @@ class Context:
             # normally the task that should get cancelled/error
             # from some remote fault!
             send_chan.send_nowait(msg)
-            match msg:
-                case Stop():
-                    if (stream := self._stream):
-                        stream._stop_msg = msg
-
-                case Return():
-                    if not self._outcome_msg:
-                        log.warning(
-                            f'Setting final outcome msg AFTER '
-                            f'`._rx_chan.send()`??\n'
-                            f'\n'
-                            f'{msg}'
-                        )
-                        self._outcome_msg = msg
-
             return True
 
         except trio.BrokenResourceError:
@@ -2038,7 +2006,7 @@ async def open_context_from_portal(
             # the dialog, the `Error` msg should be raised from the `msg`
             # handling block below.
             try:
-                started_msg, first = await ctx._pld_rx.recv_msg(
+                started_msg, first = await ctx._pld_rx.recv_msg_w_pld(
                     ipc=ctx,
                     expect_msg=Started,
                     passthrough_non_pld_msgs=False,
@@ -2403,8 +2371,7 @@ async def open_context_from_portal(
             # displaying `ContextCancelled` traces where the
             # cause of crash/exit IS due to something in
             # user/app code on either end of the context.
-            and
-            not rxchan._closed
+            and not rxchan._closed
         ):
             # XXX NOTE XXX: and again as per above, we mask any
             # `trio.Cancelled` raised here so as to NOT mask
@@ -2463,7 +2430,6 @@ async def open_context_from_portal(
         # FINALLY, remove the context from runtime tracking and
         # exit!
         log.runtime(
-        # log.cancel(
             f'De-allocating IPC ctx opened with {ctx.side!r} peer \n'
             f'uid: {uid}\n'
             f'cid: {ctx.cid}\n'
@@ -2519,6 +2485,7 @@ def mk_context(
         _caller_info=caller_info,
         **kwargs,
     )
+    pld_rx._ctx = ctx
     ctx._result = Unresolved
     return ctx
 
@@ -2581,14 +2548,7 @@ def context(
     name: str
     param: Type
     for name, param in annots.items():
-        if (
-            param is Context
-            or (
-                isinstance(param, UnionType)
-                and
-                Context in param.__args__
-            )
-        ):
+        if param is Context:
             ctx_var_name: str = name
             break
     else:

tractor/_exceptions.py

@@ -432,13 +432,9 @@ class RemoteActorError(Exception):
         Error type boxed by last actor IPC hop.
 
         '''
-        if (
-            self._boxed_type is None
-            and
-            (ipc_msg := self._ipc_msg)
-        ):
+        if self._boxed_type is None:
             self._boxed_type = get_err_type(
-                ipc_msg.boxed_type_str
+                self._ipc_msg.boxed_type_str
             )
 
         return self._boxed_type
@@ -1147,8 +1143,6 @@ def unpack_error(
     which is the responsibilitiy of the caller.
 
     '''
-    # XXX, apparently we pass all sorts of msgs here?
-    # kinda odd but seems like maybe they shouldn't be?
     if not isinstance(msg, Error):
         return None
 

tractor/_portal.py

@@ -184,7 +184,7 @@ class Portal:
                 (
                     self._final_result_msg,
                     self._final_result_pld,
-                ) = await self._expect_result_ctx._pld_rx.recv_msg(
+                ) = await self._expect_result_ctx._pld_rx.recv_msg_w_pld(
                     ipc=self._expect_result_ctx,
                     expect_msg=Return,
                 )

tractor/_rpc.py

@@ -649,10 +649,6 @@ async def _invoke(
                 )
                 # set and shuttle final result to "parent"-side task.
                 ctx._result = res
-                log.runtime(
-                    f'Sending result msg and exiting {ctx.side!r}\n'
-                    f'{return_msg}\n'
-                )
                 await chan.send(return_msg)
 
             # NOTE: this happens IFF `ctx._scope.cancel()` is

tractor/_runtime.py

@@ -836,10 +836,8 @@ class Actor:
             )]
         except KeyError:
             report: str = (
-                'Ignoring invalid IPC msg!?\n'
-                f'Ctx seems to not/no-longer exist??\n'
-                f'\n'
-                f'<=? {uid}\n'
+                'Ignoring invalid IPC ctx msg!\n\n'
+                f'<=? {uid}\n\n'
                 f'  |_{pretty_struct.pformat(msg)}\n'
             )
             match msg:

tractor/_streaming.py

@@ -45,11 +45,9 @@ from .trionics import (
     BroadcastReceiver,
 )
 from tractor.msg import (
-    Error,
-    Return,
-    Stop,
+    # Return,
+    # Stop,
     MsgType,
-    PayloadT,
     Yield,
 )
 
@@ -72,7 +70,8 @@ class MsgStream(trio.abc.Channel):
     A bidirectional message stream for receiving logically sequenced
     values over an inter-actor IPC `Channel`.
 
-
+    This is the type returned to a local task which entered either
+    `Portal.open_stream_from()` or `Context.open_stream()`.
 
     Termination rules:
 
@@ -95,9 +94,6 @@ class MsgStream(trio.abc.Channel):
         self._rx_chan = rx_chan
         self._broadcaster = _broadcaster
 
-        # any actual IPC msg which is effectively an `EndOfStream`
-        self._stop_msg: bool|Stop = False
-
         # flag to denote end of stream
         self._eoc: bool|trio.EndOfChannel = False
         self._closed: bool|trio.ClosedResourceError = False
@@ -129,67 +125,16 @@ class MsgStream(trio.abc.Channel):
     def receive_nowait(
         self,
         expect_msg: MsgType = Yield,
-    ) -> PayloadT:
+    ):
         ctx: Context = self._ctx
-        (
-            msg,
-            pld,
-        ) = ctx._pld_rx.recv_msg_nowait(
+        return ctx._pld_rx.recv_pld_nowait(
             ipc=self,
             expect_msg=expect_msg,
         )
 
-        # ?TODO, maybe factor this into a hyper-common `unwrap_pld()`
-        #
-        match msg:
-
-            # XXX, these never seems to ever hit? cool?
-            case Stop():
-                log.cancel(
-                    f'Msg-stream was ended via stop msg\n'
-                    f'{msg}'
-                )
-            case Error():
-                log.error(
-                    f'Msg-stream was ended via error msg\n'
-                    f'{msg}'
-                )
-
-            # XXX NOTE, always set any final result on the ctx to
-            # avoid teardown race conditions where previously this msg
-            # would be consumed silently (by `.aclose()` doing its
-            # own "msg drain loop" but WITHOUT those `drained: lists[MsgType]`
-            # being post-close-processed!
-            #
-            # !!TODO, see the equiv todo-comment in `.receive()`
-            # around the `if drained:` where we should prolly
-            # ACTUALLY be doing this post-close processing??
-            #
-            case Return(pld=pld):
-                log.warning(
-                    f'Msg-stream final result msg for IPC ctx?\n'
-                    f'{msg}'
-                )
-                # XXX TODO, this **should be covered** by higher
-                # scoped runtime-side method calls such as
-                # `Context._deliver_msg()`, so you should never
-                # really see the warning above or else something
-                # racy/out-of-order is likely going on between
-                # actor-runtime-side push tasks and the user-app-side
-                # consume tasks!
-                # -[ ] figure out that set of race cases and fix!
-                # -[ ] possibly return the `msg` given an input
-                #     arg-flag is set so we can process the `Return`
-                #     from the `.aclose()` caller?
-                #
-                # breakpoint()  # to debug this RACE CASE!
-                ctx._result = pld
-                ctx._outcome_msg = msg
-
-        return pld
-
     async def receive(
         self,
+
         hide_tb: bool = False,
     ):
         '''
@@ -209,7 +154,7 @@ class MsgStream(trio.abc.Channel):
         #     except trio.EndOfChannel:
         #         raise StopAsyncIteration
         #
-        # see `.aclose()` for notes on the old behaviour prior to
+        # see ``.aclose()`` for notes on the old behaviour prior to
         # introducing this
         if self._eoc:
             raise self._eoc
@@ -220,11 +165,7 @@ class MsgStream(trio.abc.Channel):
         src_err: Exception|None = None  # orig tb
         try:
             ctx: Context = self._ctx
-            pld = await ctx._pld_rx.recv_pld(
-                ipc=self,
-                expect_msg=Yield,
-            )
-            return pld
+            return await ctx._pld_rx.recv_pld(ipc=self)
 
         # XXX: the stream terminates on either of:
         # - `self._rx_chan.receive()` raising  after manual closure
@@ -233,7 +174,7 @@ class MsgStream(trio.abc.Channel):
         # - via a `Stop`-msg received from remote peer task.
         #   NOTE
         #   |_ previously this was triggered by calling
-        #   `._rx_chan.aclose()` on the send side of the channel
+        #   ``._rx_chan.aclose()`` on the send side of the channel
         #   inside `Actor._deliver_ctx_payload()`, but now the 'stop'
         #   message handling gets delegated to `PldRFx.recv_pld()`
         #   internals.
@@ -257,14 +198,11 @@ class MsgStream(trio.abc.Channel):
         # terminated and signal this local iterator to stop
         drained: list[Exception|dict] = await self.aclose()
         if drained:
-        #  ^^^^^^^^TODO? pass these to the `._ctx._drained_msgs:
-        #  deque` and then iterate them as part of any
-        #  `.wait_for_result()` call?
-        #
-        # -[ ] move the match-case processing from
-        #     `.receive_nowait()` instead to right here, use it from
-        #     a for msg in drained:` post-proc loop?
-        #
+            # ?TODO? pass these to the `._ctx._drained_msgs: deque`
+            # and then iterate them as part of any `.wait_for_result()` call?
+            #
+            # from .devx import pause
+            # await pause()
             log.warning(
                 'Drained context msgs during closure\n\n'
                 f'{drained}'
@@ -327,6 +265,9 @@ class MsgStream(trio.abc.Channel):
          - more or less we try to maintain adherance to trio's `.aclose()` semantics:
            https://trio.readthedocs.io/en/stable/reference-io.html#trio.abc.AsyncResource.aclose
         '''
+
+        # rx_chan = self._rx_chan
+
         # XXX NOTE XXX
         # it's SUPER IMPORTANT that we ensure we don't DOUBLE
         # DRAIN msgs on closure so avoid getting stuck handing on
@@ -338,16 +279,15 @@ class MsgStream(trio.abc.Channel):
             # this stream has already been closed so silently succeed as
             # per ``trio.AsyncResource`` semantics.
             # https://trio.readthedocs.io/en/stable/reference-io.html#trio.abc.AsyncResource.aclose
-            # import tractor
-            # await tractor.pause()
             return []
 
         ctx: Context = self._ctx
         drained: list[Exception|dict] = []
         while not drained:
             try:
-                maybe_final_msg: Yield|Return = self.receive_nowait(
-                    expect_msg=Yield|Return,
+                maybe_final_msg = self.receive_nowait(
+                    # allow_msgs=[Yield, Return],
+                    expect_msg=Yield,
                 )
                 if maybe_final_msg:
                     log.debug(
@@ -432,10 +372,8 @@ class MsgStream(trio.abc.Channel):
         #         await rx_chan.aclose()
 
         if not self._eoc:
-            this_side: str = self._ctx.side
-            peer_side: str = self._ctx.peer_side
             message: str = (
-                f'Stream self-closed by {this_side!r}-side before EoC from {peer_side!r}\n'
+                f'Stream self-closed by {self._ctx.side!r}-side before EoC\n'
                 # } bc a stream is a "scope"/msging-phase inside an IPC
                 f'x}}>\n'
                 f'  |_{self}\n'
@@ -443,19 +381,9 @@ class MsgStream(trio.abc.Channel):
             log.cancel(message)
             self._eoc = trio.EndOfChannel(message)
 
-            if (
-                (rx_chan := self._rx_chan)
-                and
-                (stats := rx_chan.statistics()).tasks_waiting_receive
-            ):
-                log.cancel(
-                    f'Msg-stream is closing but there is still reader tasks,\n'
-                    f'{stats}\n'
-                )
-
         # ?XXX WAIT, why do we not close the local mem chan `._rx_chan` XXX?
         # => NO, DEFINITELY NOT! <=
-        # if we're a bi-dir `MsgStream` BECAUSE this same
+        # if we're a bi-dir ``MsgStream`` BECAUSE this same
         # core-msg-loop mem recv-chan is used to deliver the
         # potential final result from the surrounding inter-actor
         # `Context` so we don't want to close it until that

tractor/_testing/__init__.py

@@ -26,9 +26,6 @@ import os
 import pathlib
 
 import tractor
-from tractor.devx._debug import (
-    BoxedMaybeException,
-)
 from .pytest import (
     tractor_test as tractor_test
 )
@@ -101,13 +98,12 @@ async def expect_ctxc(
     '''
     if yay:
         try:
-            yield (maybe_exc := BoxedMaybeException())
+            yield
             raise RuntimeError('Never raised ctxc?')
-        except tractor.ContextCancelled as ctxc:
-            maybe_exc.value = ctxc
+        except tractor.ContextCancelled:
             if reraise:
                 raise
             else:
                 return
     else:
-        yield (maybe_exc := BoxedMaybeException())
+        yield

tractor/hilevel/__init__.py

@@ -0,0 +1,26 @@
+# tractor: structured concurrent "actors".
+# Copyright 2024-eternity Tyler Goodlet.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+'''
+High level design patterns, APIs and runtime extensions built on top
+of the `tractor` runtime core.
+
+'''
+from ._service import (
+    open_service_mngr as open_service_mngr,
+    get_service_mngr as get_service_mngr,
+    ServiceMngr as ServiceMngr,
+)

tractor/hilevel/_service.py

@@ -0,0 +1,592 @@
+# tractor: structured concurrent "actors".
+# Copyright 2024-eternity Tyler Goodlet.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+'''
+Daemon subactor as service(s) management and supervision primitives
+and API.
+
+'''
+from __future__ import annotations
+from contextlib import (
+    asynccontextmanager as acm,
+    # contextmanager as cm,
+)
+from collections import defaultdict
+from dataclasses import (
+    dataclass,
+    field,
+)
+import functools
+import inspect
+from typing import (
+    Callable,
+    Any,
+)
+
+import tractor
+import trio
+from trio import TaskStatus
+from tractor import (
+    log,
+    ActorNursery,
+    current_actor,
+    ContextCancelled,
+    Context,
+    Portal,
+)
+
+log = log.get_logger('tractor')
+
+
+# TODO: implement a `@singleton` deco-API for wrapping the below
+# factory's impl for general actor-singleton use?
+#
+# -[ ] go through the options peeps on SO did?
+#  * https://stackoverflow.com/questions/6760685/what-is-the-best-way-of-implementing-singleton-in-python
+#  * including @mikenerone's answer
+#   |_https://stackoverflow.com/questions/6760685/what-is-the-best-way-of-implementing-singleton-in-python/39186313#39186313
+#
+# -[ ] put it in `tractor.lowlevel._globals` ?
+#  * fits with our oustanding actor-local/global feat req?
+#   |_ https://github.com/goodboy/tractor/issues/55
+#  * how can it relate to the `Actor.lifetime_stack` that was
+#    silently patched in?
+#   |_ we could implicitly call both of these in the same
+#     spot in the runtime using the lifetime stack?
+#    - `open_singleton_cm().__exit__()`
+#    -`del_singleton()`
+#   |_ gives SC fixtue semantics to sync code oriented around
+#     sub-process lifetime?
+#  * what about with `trio.RunVar`?
+#   |_https://trio.readthedocs.io/en/stable/reference-lowlevel.html#trio.lowlevel.RunVar
+#    - which we'll need for no-GIL cpython (right?) presuming
+#      multiple `trio.run()` calls in process?
+#
+#
+# @singleton
+# async def open_service_mngr(
+#     **init_kwargs,
+# ) -> ServiceMngr:
+#     '''
+#     Note this function body is invoke IFF no existing singleton instance already
+#     exists in this proc's memory.
+
+#     '''
+#     # setup
+#     yield ServiceMngr(**init_kwargs)
+#     # teardown
+
+
+# a deletion API for explicit instance de-allocation?
+# @open_service_mngr.deleter
+# def del_service_mngr() -> None:
+#     mngr = open_service_mngr._singleton[0]
+#     open_service_mngr._singleton[0] = None
+#     del mngr
+
+
+
+# TODO: implement a singleton deco-API for wrapping the below
+# factory's impl for general actor-singleton use?
+#
+# @singleton
+# async def open_service_mngr(
+#     **init_kwargs,
+# ) -> ServiceMngr:
+#     '''
+#     Note this function body is invoke IFF no existing singleton instance already
+#     exists in this proc's memory.
+
+#     '''
+#     # setup
+#     yield ServiceMngr(**init_kwargs)
+#     # teardown
+
+
+
+# TODO: singleton factory API instead of a class API
+@acm
+async def open_service_mngr(
+    *,
+    debug_mode: bool = False,
+
+    # NOTE; since default values for keyword-args are effectively
+    # module-vars/globals as per the note from,
+    # https://docs.python.org/3/tutorial/controlflow.html#default-argument-values
+    #
+    # > "The default value is evaluated only once. This makes
+    #   a difference when the default is a mutable object such as
+    #   a list, dictionary, or instances of most classes"
+    #
+    _singleton: list[ServiceMngr|None] = [None],
+    **init_kwargs,
+
+) -> ServiceMngr:
+    '''
+    Open an actor-global "service-manager" for supervising a tree
+    of subactors and/or actor-global tasks.
+
+    The delivered `ServiceMngr` is singleton instance for each
+    actor-process, that is, allocated on first open and never
+    de-allocated unless explicitly deleted by al call to
+    `del_service_mngr()`.
+
+    '''
+    # TODO: factor this an allocation into
+    # a `._mngr.open_service_mngr()` and put in the
+    # once-n-only-once setup/`.__aenter__()` part!
+    # -[ ] how to make this only happen on the `mngr == None` case?
+    #  |_ use `.trionics.maybe_open_context()` (for generic
+    #     async-with-style-only-once of the factory impl, though
+    #     what do we do for the allocation case?
+    #    / `.maybe_open_nursery()` (since for this specific case
+    #    it's simpler?) to activate
+    async with (
+        tractor.open_nursery() as an,
+        trio.open_nursery() as tn,
+    ):
+        # impl specific obvi..
+        init_kwargs.update({
+            'an': an,
+            'tn': tn,
+        })
+
+        mngr: ServiceMngr|None
+        if (mngr := _singleton[0]) is None:
+
+            log.info('Allocating a new service mngr!')
+            mngr = _singleton[0] = ServiceMngr(**init_kwargs)
+
+            # TODO: put into `.__aenter__()` section of
+            # eventual `@singleton_acm` API wrapper.
+            #
+            # assign globally for future daemon/task creation
+            mngr.an = an
+            mngr.tn = tn
+
+        else:
+            assert (mngr.an and mngr.tn)
+            log.info(
+                'Using extant service mngr!\n\n'
+                f'{mngr!r}\n'  # it has a nice `.__repr__()` of services state
+            )
+
+        try:
+            # NOTE: this is a singleton factory impl specific detail
+            # which should be supported in the condensed
+            # `@singleton_acm` API?
+            mngr.debug_mode = debug_mode
+
+            yield mngr
+        finally:
+            # TODO: is this more clever/efficient?
+            # if 'samplerd' in mngr.service_ctxs:
+            #     await mngr.cancel_service('samplerd')
+            tn.cancel_scope.cancel()
+
+
+
+def get_service_mngr() -> ServiceMngr:
+    '''
+    Try to get the singleton service-mngr for this actor presuming it
+    has already been allocated using,
+
+    .. code:: python
+
+        async with open_<@singleton_acm(func)>() as mngr`
+            ... this block kept open ...
+
+    If not yet allocated raise a `ServiceError`.
+
+    '''
+    # https://stackoverflow.com/a/12627202
+    # https://docs.python.org/3/library/inspect.html#inspect.Signature
+    maybe_mngr: ServiceMngr|None = inspect.signature(
+        open_service_mngr
+    ).parameters['_singleton'].default[0]
+
+    if maybe_mngr is None:
+        raise RuntimeError(
+            'Someone must allocate a `ServiceMngr` using\n\n'
+            '`async with open_service_mngr()` beforehand!!\n'
+        )
+
+    return maybe_mngr
+
+
+async def _open_and_supervise_service_ctx(
+    serman: ServiceMngr,
+    name: str,
+    ctx_fn: Callable,  # TODO, type for `@tractor.context` requirement
+    portal: Portal,
+
+    allow_overruns: bool = False,
+    task_status: TaskStatus[
+        tuple[
+            trio.CancelScope,
+            Context,
+            trio.Event,
+            Any,
+        ]
+    ] = trio.TASK_STATUS_IGNORED,
+    **ctx_kwargs,
+
+) -> Any:
+    '''
+    Open a remote IPC-context defined by `ctx_fn` in the
+    (service) actor accessed via `portal` and supervise the
+    (local) parent task to termination at which point the remote
+    actor runtime is cancelled alongside it.
+
+    The main application is for allocating long-running
+    "sub-services" in a main daemon and explicitly controlling
+    their lifetimes from an actor-global singleton.
+
+    '''
+    # TODO: use the ctx._scope directly here instead?
+    # -[ ] actually what semantics do we expect for this
+    #   usage!?
+    with trio.CancelScope() as cs:
+        try:
+            async with portal.open_context(
+                ctx_fn,
+                allow_overruns=allow_overruns,
+                **ctx_kwargs,
+
+            ) as (ctx, started):
+
+                # unblock once the remote context has started
+                complete = trio.Event()
+                task_status.started((
+                    cs,
+                    ctx,
+                    complete,
+                    started,
+                ))
+                log.info(
+                    f'`pikerd` service {name} started with value {started}'
+                )
+                # wait on any context's return value
+                # and any final portal result from the
+                # sub-actor.
+                ctx_res: Any = await ctx.wait_for_result()
+
+                # NOTE: blocks indefinitely until cancelled
+                # either by error from the target context
+                # function or by being cancelled here by the
+                # surrounding cancel scope.
+                return (
+                    await portal.wait_for_result(),
+                    ctx_res,
+                )
+
+        except ContextCancelled as ctxe:
+            canceller: tuple[str, str] = ctxe.canceller
+            our_uid: tuple[str, str] = current_actor().uid
+            if (
+                canceller != portal.chan.uid
+                and
+                canceller != our_uid
+            ):
+                log.cancel(
+                    f'Actor-service `{name}` was remotely cancelled by a peer?\n'
+
+                    # TODO: this would be a good spot to use
+                    # a respawn feature Bo
+                    f'-> Keeping `pikerd` service manager alive despite this inter-peer cancel\n\n'
+
+                    f'cancellee: {portal.chan.uid}\n'
+                    f'canceller: {canceller}\n'
+                )
+            else:
+                raise
+
+        finally:
+            # NOTE: the ctx MUST be cancelled first if we
+            # don't want the above `ctx.wait_for_result()` to
+            # raise a self-ctxc. WHY, well since from the ctx's
+            # perspective the cancel request will have
+            # arrived out-out-of-band at the `Actor.cancel()`
+            # level, thus `Context.cancel_called == False`,
+            # meaning `ctx._is_self_cancelled() == False`.
+            # with trio.CancelScope(shield=True):
+            # await ctx.cancel()
+            await portal.cancel_actor()  # terminate (remote) sub-actor
+            complete.set()  # signal caller this task is done
+            serman.service_ctxs.pop(name)  # remove mngr entry
+
+
+# TODO: we need remote wrapping and a general soln:
+# - factor this into a ``tractor.highlevel`` extension # pack for the
+#   library.
+# - wrap a "remote api" wherein you can get a method proxy
+#   to the pikerd actor for starting services remotely!
+# - prolly rename this to ActorServicesNursery since it spawns
+#   new actors and supervises them to completion?
+@dataclass
+class ServiceMngr:
+    '''
+    A multi-subactor-as-service manager.
+
+    Spawn, supervise and monitor service/daemon subactors in a SC
+    process tree.
+
+    '''
+    an: ActorNursery
+    tn: trio.Nursery
+    debug_mode: bool = False # tractor sub-actor debug mode flag
+
+    service_tasks: dict[
+        str,
+        tuple[
+            trio.CancelScope,
+            trio.Event,
+        ]
+    ] = field(default_factory=dict)
+
+    service_ctxs: dict[
+        str,
+        tuple[
+            trio.CancelScope,
+            Context,
+            Portal,
+            trio.Event,
+        ]
+    ] = field(default_factory=dict)
+
+    # internal per-service task mutexs
+    _locks = defaultdict(trio.Lock)
+
+    # TODO, unify this interface with our `TaskManager` PR!
+    #
+    #
+    async def start_service_task(
+        self,
+        name: str,
+        # TODO: typevar for the return type of the target and then
+        # use it below for `ctx_res`?
+        fn: Callable,
+
+        allow_overruns: bool = False,
+        **ctx_kwargs,
+
+    ) -> tuple[
+        trio.CancelScope,
+        Any,
+        trio.Event,
+    ]:
+        async def _task_manager_start(
+            task_status: TaskStatus[
+                tuple[
+                    trio.CancelScope,
+                    trio.Event,
+                ]
+            ] = trio.TASK_STATUS_IGNORED,
+        ) -> Any:
+
+            task_cs = trio.CancelScope()
+            task_complete = trio.Event()
+
+            with task_cs as cs:
+                task_status.started((
+                    cs,
+                    task_complete,
+                ))
+                try:
+                    await fn()
+                except trio.Cancelled as taskc:
+                    log.cancel(
+                        f'Service task for `{name}` was cancelled!\n'
+                        # TODO: this would be a good spot to use
+                        # a respawn feature Bo
+                    )
+                    raise taskc
+                finally:
+                    task_complete.set()
+        (
+            cs,
+            complete,
+        ) = await self.tn.start(_task_manager_start)
+
+        # store the cancel scope and portal for later cancellation or
+        # retstart if needed.
+        self.service_tasks[name] = (
+            cs,
+            complete,
+        )
+        return (
+            cs,
+            complete,
+        )
+
+    async def cancel_service_task(
+        self,
+        name: str,
+
+    ) -> Any:
+        log.info(f'Cancelling `pikerd` service {name}')
+        cs, complete = self.service_tasks[name]
+
+        cs.cancel()
+        await complete.wait()
+        # TODO, if we use the `TaskMngr` from #346
+        # we can also get the return value from the task!
+
+        if name in self.service_tasks:
+            # TODO: custom err?
+            # raise ServiceError(
+            raise RuntimeError(
+                f'Service task {name!r} not terminated!?\n'
+            )
+
+    async def start_service_ctx(
+        self,
+        name: str,
+        portal: Portal,
+        # TODO: typevar for the return type of the target and then
+        # use it below for `ctx_res`?
+        ctx_fn: Callable,
+        **ctx_kwargs,
+
+    ) -> tuple[
+        trio.CancelScope,
+        Context,
+        Any,
+    ]:
+        '''
+        Start a remote IPC-context defined by `ctx_fn` in a background
+        task and immediately return supervision primitives to manage it:
+
+        - a `cs: CancelScope` for the newly allocated bg task
+        - the `ipc_ctx: Context` to manage the remotely scheduled
+          `trio.Task`.
+        - the `started: Any` value returned by the remote endpoint
+          task's `Context.started(<value>)` call.
+
+        The bg task supervises the ctx such that when it terminates the supporting
+        actor runtime is also cancelled, see `_open_and_supervise_service_ctx()`
+        for details.
+
+        '''
+        cs, ipc_ctx, complete, started = await self.tn.start(
+            functools.partial(
+                _open_and_supervise_service_ctx,
+                serman=self,
+                name=name,
+                ctx_fn=ctx_fn,
+                portal=portal,
+                **ctx_kwargs,
+            )
+        )
+
+        # store the cancel scope and portal for later cancellation or
+        # retstart if needed.
+        self.service_ctxs[name] = (cs, ipc_ctx, portal, complete)
+        return (
+            cs,
+            ipc_ctx,
+            started,
+        )
+
+    async def start_service(
+        self,
+        daemon_name: str,
+        ctx_ep: Callable,  # kwargs must `partial`-ed in!
+        # ^TODO, type for `@tractor.context` deco-ed funcs!
+
+        debug_mode: bool = False,
+        **start_actor_kwargs,
+
+    ) -> Context:
+        '''
+        Start new subactor and schedule a supervising "service task"
+        in it which explicitly defines the sub's lifetime.
+
+        "Service daemon subactors" are cancelled (and thus
+        terminated) using the paired `.cancel_service()`.
+
+        Effectively this API can be used to manage "service daemons"
+        spawned under a single parent actor with supervision
+        semantics equivalent to a one-cancels-one style actor-nursery
+        or "(subactor) task manager" where each subprocess's (and
+        thus its embedded actor runtime) lifetime is synced to that
+        of the remotely spawned task defined by `ctx_ep`.
+
+        The funcionality can be likened to a "daemonized" version of
+        `.hilevel.worker.run_in_actor()` but with supervision
+        controls offered by `tractor.Context` where the main/root
+        remotely scheduled `trio.Task` invoking `ctx_ep` determines
+        the underlying subactor's lifetime.
+
+        '''
+        entry: tuple|None = self.service_ctxs.get(daemon_name)
+        if entry:
+            (cs, sub_ctx, portal, complete) = entry
+            return sub_ctx
+
+        if daemon_name not in self.service_ctxs:
+            portal: Portal = await self.an.start_actor(
+                daemon_name,
+                debug_mode=(  # maybe set globally during allocate
+                    debug_mode
+                    or
+                    self.debug_mode
+                ),
+                **start_actor_kwargs,
+            )
+            ctx_kwargs: dict[str, Any] = {}
+            if isinstance(ctx_ep, functools.partial):
+                ctx_kwargs: dict[str, Any] = ctx_ep.keywords
+                ctx_ep: Callable = ctx_ep.func
+
+            (
+                cs,
+                sub_ctx,
+                started,
+            ) = await self.start_service_ctx(
+                name=daemon_name,
+                portal=portal,
+                ctx_fn=ctx_ep,
+                **ctx_kwargs,
+            )
+
+            return sub_ctx
+
+    async def cancel_service(
+        self,
+        name: str,
+
+    ) -> Any:
+        '''
+        Cancel the service task and actor for the given ``name``.
+
+        '''
+        log.info(f'Cancelling `pikerd` service {name}')
+        cs, sub_ctx, portal, complete = self.service_ctxs[name]
+
+        # cs.cancel()
+        await sub_ctx.cancel()
+        await complete.wait()
+
+        if name in self.service_ctxs:
+            # TODO: custom err?
+            # raise ServiceError(
+            raise RuntimeError(
+                f'Service actor for {name} not terminated and/or unknown?'
+            )
+
+        # assert name not in self.service_ctxs, \
+        #     f'Serice task for {name} not terminated?'

tractor/msg/__init__.py

@@ -33,7 +33,6 @@ from ._codec import (
 
     apply_codec as apply_codec,
     mk_codec as mk_codec,
-    mk_dec as mk_dec,
     MsgCodec as MsgCodec,
     MsgDec as MsgDec,
     current_codec as current_codec,

tractor/msg/_codec.py

@@ -61,7 +61,6 @@ from tractor.msg.pretty_struct import Struct
 from tractor.msg.types import (
     mk_msg_spec,
     MsgType,
-    PayloadMsg,
 )
 from tractor.log import get_logger
 
@@ -81,7 +80,6 @@ class MsgDec(Struct):
 
     '''
     _dec: msgpack.Decoder
-    # _ext_types_box: Struct|None = None
 
     @property
     def dec(self) -> msgpack.Decoder:
@@ -181,126 +179,23 @@ class MsgDec(Struct):
 
 
 def mk_dec(
-    spec: Union[Type[Struct]]|Type|None,
-
-    # NOTE, required for ad-hoc type extensions to the underlying
-    # serialization proto (which is default `msgpack`),
-    # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
+    spec: Union[Type[Struct]]|Any = Any,
     dec_hook: Callable|None = None,
-    ext_types: list[Type]|None = None,
 
 ) -> MsgDec:
     '''
-    Create an IPC msg decoder, a slightly higher level wrapper around
-    a `msgspec.msgpack.Decoder` which provides,
-
-    - easier introspection of the underlying type spec via
-      the `.spec` and `.spec_str` attrs,
-    - `.hook` access to the `Decoder.dec_hook()`,
-    - automatic custom extension-types decode support when
-      `dec_hook()` is provided such that any `PayloadMsg.pld` tagged
-      as a type from from `ext_types` (presuming the `MsgCodec.encode()` also used
-      a `.enc_hook()`) is processed and constructed by a `PldRx` implicitily.
-
-    NOTE, as mentioned a `MsgDec` is normally used for `PayloadMsg.pld: PayloadT` field
-    decoding inside an IPC-ctx-oriented `PldRx`.
+    Create an IPC msg decoder, normally used as the
+    `PayloadMsg.pld: PayloadT` field decoder inside a `PldRx`.
 
     '''
-    if (
-        spec is None
-        and
-        ext_types is None
-    ):
-        raise TypeError(
-            f'MIssing type-`spec` for msg decoder!\n'
-            f'\n'
-            f'`spec=None` is **only** permitted is if custom extension types '
-            f'are provided via `ext_types`, meaning it must be non-`None`.\n'
-            f'\n'
-            f'In this case it is presumed that only the `ext_types`, '
-            f'which much be handled by a paired `dec_hook()`, '
-            f'will be permitted within the payload type-`spec`!\n'
-            f'\n'
-            f'spec = {spec!r}\n'
-            f'dec_hook = {dec_hook!r}\n'
-            f'ext_types = {ext_types!r}\n'
-        )
-
-    if dec_hook:
-        if ext_types is None:
-            raise TypeError(
-                f'If extending the serializable types with a custom decode hook (`dec_hook()`), '
-                f'you must also provide the expected type set that the hook will handle '
-                f'via a `ext_types: Union[Type]|None = None` argument!\n'
-                f'\n'
-                f'dec_hook = {dec_hook!r}\n'
-                f'ext_types = {ext_types!r}\n'
-            )
-
-        # XXX, i *thought* we would require a boxing struct as per docs,
-        # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
-        # |_ see comment,
-        #  > Note that typed deserialization is required for
-        #  > successful roundtripping here, so we pass `MyMessage` to
-        #  > `Decoder`.
-        #
-        # BUT, turns out as long as you spec a union with `Raw` it
-        # will work? kk B)
-        #
-        # maybe_box_struct = mk_boxed_ext_struct(ext_types)
-        spec = Raw | Union[*ext_types]
-
     return MsgDec(
         _dec=msgpack.Decoder(
             type=spec,  # like `MsgType[Any]`
             dec_hook=dec_hook,
-        ),
+        )
     )
 
 
-# TODO? remove since didn't end up needing this?
-def mk_boxed_ext_struct(
-    ext_types: list[Type],
-) -> Struct:
-    # NOTE, originally was to wrap non-msgpack-supported "extension
-    # types" in a field-typed boxing struct, see notes around the
-    # `dec_hook()` branch in `mk_dec()`.
-    ext_types_union = Union[*ext_types]
-    repr_ext_types_union: str = (
-        str(ext_types_union)
-        or
-        "|".join(ext_types)
-    )
-    BoxedExtType = msgspec.defstruct(
-        f'BoxedExts[{repr_ext_types_union}]',
-        fields=[
-            ('boxed', ext_types_union),
-        ],
-    )
-    return BoxedExtType
-
-
-def unpack_spec_types(
-    spec: Union[Type]|Type,
-) -> set[Type]:
-    '''
-    Given an input type-`spec`, either a lone type
-    or a `Union` of types (like `str|int|MyThing`),
-    return a set of individual types.
-
-    When `spec` is not a type-union returns `{spec,}`.
-
-    '''
-    spec_subtypes: set[Union[Type]] = set(
-         getattr(
-             spec,
-             '__args__',
-             {spec,},
-         )
-    )
-    return spec_subtypes
-
-
 def mk_msgspec_table(
     dec: msgpack.Decoder,
     msg: MsgType|None = None,
@@ -378,8 +273,6 @@ class MsgCodec(Struct):
     _dec: msgpack.Decoder
     _pld_spec: Type[Struct]|Raw|Any
 
-    # _ext_types_box: Struct|None = None
-
     def __repr__(self) -> str:
         speclines: str = textwrap.indent(
             pformat_msgspec(codec=self),
@@ -446,15 +339,12 @@ class MsgCodec(Struct):
 
     def encode(
         self,
-        py_obj: Any|PayloadMsg,
+        py_obj: Any,
 
         use_buf: bool = False,
         # ^-XXX-^ uhh why am i getting this?
         # |_BufferError: Existing exports of data: object cannot be re-sized
 
-        as_ext_type: bool = False,
-        hide_tb: bool = True,
-
     ) -> bytes:
         '''
         Encode input python objects to `msgpack` bytes for
@@ -464,46 +354,11 @@ class MsgCodec(Struct):
         https://jcristharif.com/msgspec/perf-tips.html#reusing-an-output-buffer
 
         '''
-        __tracebackhide__: bool = hide_tb
         if use_buf:
             self._enc.encode_into(py_obj, self._buf)
             return self._buf
-
-        return self._enc.encode(py_obj)
-        # try:
-        #     return self._enc.encode(py_obj)
-        # except TypeError as typerr:
-        #     typerr.add_note(
-        #         '|_src error from `msgspec`'
-        #         # f'|_{self._enc.encode!r}'
-        #     )
-        #     raise typerr
-
-        # TODO! REMOVE once i'm confident we won't ever need it!
-        #
-        # box: Struct = self._ext_types_box
-        # if (
-        #     as_ext_type
-        #     or
-        #     (
-        #         # XXX NOTE, auto-detect if the input type
-        #         box
-        #         and
-        #         (ext_types := unpack_spec_types(
-        #             spec=box.__annotations__['boxed'])
-        #         )
-        #     )
-        # ):
-        #     match py_obj:
-        #         # case PayloadMsg(pld=pld) if (
-        #         #     type(pld) in ext_types
-        #         # ):
-        #         #     py_obj.pld = box(boxed=py_obj)
-        #         #     breakpoint()
-        #         case _ if (
-        #             type(py_obj) in ext_types
-        #         ):
-        #             py_obj = box(boxed=py_obj)
+        else:
+            return self._enc.encode(py_obj)
 
     @property
     def dec(self) -> msgpack.Decoder:
@@ -523,30 +378,21 @@ class MsgCodec(Struct):
         return self._dec.decode(msg)
 
 
-# ?TODO? time to remove this finally?
-#
-# -[x] TODO: a sub-decoder system as well?
-# => No! already re-architected to include a "payload-receiver"
-#   now found in `._ops`.
+# [x] TODO: a sub-decoder system as well? => No!
 #
 # -[x] do we still want to try and support the sub-decoder with
 # `.Raw` technique in the case that the `Generic` approach gives
 # future grief?
-# => well YES but NO, since we went with the `PldRx` approach
-#   instead!
+# => NO, since we went with the `PldRx` approach instead B)
 #
 # IF however you want to see the code that was staged for this
 # from wayyy back, see the pure removal commit.
 
 
 def mk_codec(
-    ipc_pld_spec: Union[Type[Struct]]|Any|Raw = Raw,
-    # tagged-struct-types-union set for `Decoder`ing of payloads, as
-    # per https://jcristharif.com/msgspec/structs.html#tagged-unions.
-    # NOTE that the default `Raw` here **is very intentional** since
-    # the `PldRx._pld_dec: MsgDec` is responsible for per ipc-ctx-task
-    # decoding of msg-specs defined by the user as part of **their**
-    # `tractor` "app's" type-limited IPC msg-spec.
+    # struct type unions set for `Decoder`
+    # https://jcristharif.com/msgspec/structs.html#tagged-unions
+    ipc_pld_spec: Union[Type[Struct]]|Any = Any,
 
     # TODO: offering a per-msg(-field) type-spec such that
     # the fields can be dynamically NOT decoded and left as `Raw`
@@ -559,18 +405,13 @@ def mk_codec(
 
     libname: str = 'msgspec',
 
-    # settings for encoding-to-send extension-types,
+    # proxy as `Struct(**kwargs)` for ad-hoc type extensions
     # https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
-    # dec_hook: Callable|None = None,
+    # ------ - ------
+    dec_hook: Callable|None = None,
     enc_hook: Callable|None = None,
-    ext_types: list[Type]|None = None,
-
-    # optionally provided msg-decoder from which we pull its,
-    # |_.dec_hook()
-    # |_.type
-    ext_dec: MsgDec|None = None
+    # ------ - ------
     #
-    # ?TODO? other params we might want to support
     # Encoder:
     # write_buffer_size=write_buffer_size,
     #
@@ -584,44 +425,26 @@ def mk_codec(
     `msgspec` ;).
 
     '''
-    pld_spec = ipc_pld_spec
-    if enc_hook:
-        if not ext_types:
-            raise TypeError(
-                f'If extending the serializable types with a custom encode hook (`enc_hook()`), '
-                f'you must also provide the expected type set that the hook will handle '
-                f'via a `ext_types: Union[Type]|None = None` argument!\n'
-                f'\n'
-                f'enc_hook = {enc_hook!r}\n'
-                f'ext_types = {ext_types!r}\n'
-            )
-
-    dec_hook: Callable|None = None
-    if ext_dec:
-        dec: msgspec.Decoder = ext_dec.dec
-        dec_hook = dec.dec_hook
-        pld_spec |= dec.type
-        if ext_types:
-            pld_spec |= Union[*ext_types]
-
-    # (manually) generate a msg-spec (how appropes) for all relevant
-    # payload-boxing-struct-msg-types, parameterizing the
-    # `PayloadMsg.pld: PayloadT` for the decoder such that all msgs
-    # in our SC-RPC-protocol will automatically decode to
-    # a type-"limited" payload (`Struct`) object (set).
+    # (manually) generate a msg-payload-spec for all relevant
+    # god-boxing-msg subtypes, parameterizing the `PayloadMsg.pld: PayloadT`
+    # for the decoder such that all sub-type msgs in our SCIPP
+    # will automatically decode to a type-"limited" payload (`Struct`)
+    # object (set).
     (
         ipc_msg_spec,
         msg_types,
     ) = mk_msg_spec(
-        payload_type_union=pld_spec,
+        payload_type_union=ipc_pld_spec,
     )
+    assert len(ipc_msg_spec.__args__) == len(msg_types)
+    assert ipc_msg_spec
 
-    msg_spec_types: set[Type] = unpack_spec_types(ipc_msg_spec)
-    assert (
-        len(ipc_msg_spec.__args__) == len(msg_types)
-        and
-        len(msg_spec_types) == len(msg_types)
-    )
+    # TODO: use this shim instead?
+    # bc.. unification, err somethin?
+    # dec: MsgDec = mk_dec(
+    #     spec=ipc_msg_spec,
+    #     dec_hook=dec_hook,
+    # )
 
     dec = msgpack.Decoder(
         type=ipc_msg_spec,
@@ -630,29 +453,22 @@ def mk_codec(
     enc = msgpack.Encoder(
        enc_hook=enc_hook,
     )
+
     codec = MsgCodec(
         _enc=enc,
         _dec=dec,
-        _pld_spec=pld_spec,
+        _pld_spec=ipc_pld_spec,
     )
+
     # sanity on expected backend support
     assert codec.lib.__name__ == libname
+
     return codec
 
 
 # instance of the default `msgspec.msgpack` codec settings, i.e.
 # no custom structs, hooks or other special types.
-#
-# XXX NOTE XXX, this will break our `Context.start()` call!
-#
-# * by default we roundtrip the started pld-`value` and if you apply
-#   this codec (globally anyway with `apply_codec()`) then the
-#   `roundtripped` value will include a non-`.pld: Raw` which will
-#   then type-error on the consequent `._ops.validte_payload_msg()`..
-#
-_def_msgspec_codec: MsgCodec = mk_codec(
-    ipc_pld_spec=Any,
-)
+_def_msgspec_codec: MsgCodec = mk_codec(ipc_pld_spec=Any)
 
 # The built-in IPC `Msg` spec.
 # Our composing "shuttle" protocol which allows `tractor`-app code
@@ -660,13 +476,13 @@ _def_msgspec_codec: MsgCodec = mk_codec(
 # https://jcristharif.com/msgspec/supported-types.html
 #
 _def_tractor_codec: MsgCodec = mk_codec(
-    ipc_pld_spec=Raw,  # XXX should be default righ!?
+    # TODO: use this for debug mode locking prot?
+    # ipc_pld_spec=Any,
+    ipc_pld_spec=Raw,
 )
-
-# -[x] TODO, IDEALLY provides for per-`trio.Task` specificity of the
+# TODO: IDEALLY provides for per-`trio.Task` specificity of the
 # IPC msging codec used by the transport layer when doing
 # `Channel.send()/.recv()` of wire data.
-# => impled as our `PldRx` which is `Context` scoped B)
 
 # ContextVar-TODO: DIDN'T WORK, kept resetting in every new task to default!?
 # _ctxvar_MsgCodec: ContextVar[MsgCodec] = ContextVar(
@@ -743,6 +559,17 @@ def apply_codec(
     )
     token: Token = var.set(codec)
 
+    # ?TODO? for TreeVar approach which copies from the
+    # cancel-scope of the prior value, NOT the prior task
+    # See the docs:
+    # - https://tricycle.readthedocs.io/en/latest/reference.html#tree-variables
+    # - https://github.com/oremanj/tricycle/blob/master/tricycle/_tests/test_tree_var.py
+    #   ^- see docs for @cm `.being()` API
+    # with _ctxvar_MsgCodec.being(codec):
+    #     new = _ctxvar_MsgCodec.get()
+    #     assert new is codec
+    #     yield codec
+
     try:
         yield var.get()
     finally:
@@ -753,19 +580,6 @@ def apply_codec(
         )
         assert var.get() is orig
 
-    # ?TODO? for TreeVar approach which copies from the
-    # cancel-scope of the prior value, NOT the prior task
-    #
-    # See the docs:
-    # - https://tricycle.readthedocs.io/en/latest/reference.html#tree-variables
-    # - https://github.com/oremanj/tricycle/blob/master/tricycle/_tests/test_tree_var.py
-    #   ^- see docs for @cm `.being()` API
-    #
-    # with _ctxvar_MsgCodec.being(codec):
-    #     new = _ctxvar_MsgCodec.get()
-    #     assert new is codec
-    #     yield codec
-
 
 def current_codec() -> MsgCodec:
     '''
@@ -785,7 +599,6 @@ def limit_msg_spec(
     # -> related to the `MsgCodec._payload_decs` stuff above..
     # tagged_structs: list[Struct]|None = None,
 
-    hide_tb: bool = True,
     **codec_kwargs,
 
 ) -> MsgCodec:
@@ -796,7 +609,7 @@ def limit_msg_spec(
     for all IPC contexts in use by the current `trio.Task`.
 
     '''
-    __tracebackhide__: bool = hide_tb
+    __tracebackhide__: bool = True
     curr_codec: MsgCodec = current_codec()
     msgspec_codec: MsgCodec = mk_codec(
         ipc_pld_spec=payload_spec,

tractor/msg/_exts.py

@@ -1,94 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-'''
-Type-extension-utils for codec-ing (python) objects not
-covered by the `msgspec.msgpack` protocol.
-
-See the various API docs from `msgspec`.
-
-extending from native types,
-- https://jcristharif.com/msgspec/extending.html#mapping-to-from-native-types
-
-converters,
-- https://jcristharif.com/msgspec/converters.html
-- https://jcristharif.com/msgspec/api.html#msgspec.convert
-
-`Raw` fields,
-- https://jcristharif.com/msgspec/api.html#raw
-- support for `.convert()` and `Raw`,
-  |_ https://jcristharif.com/msgspec/changelog.html
-
-'''
-from types import (
-    ModuleType,
-)
-import typing
-from typing import (
-    Type,
-    Union,
-)
-
-def dec_type_union(
-    type_names: list[str],
-    mods: list[ModuleType] = []
-) -> Type|Union[Type]:
-    '''
-    Look up types by name, compile into a list and then create and
-    return a `typing.Union` from the full set.
-
-    '''
-    # import importlib
-    types: list[Type] = []
-    for type_name in type_names:
-        for mod in [
-            typing,
-            # importlib.import_module(__name__),
-        ] + mods:
-            if type_ref := getattr(
-                mod,
-                type_name,
-                False,
-            ):
-                types.append(type_ref)
-
-    # special case handling only..
-    # ipc_pld_spec: Union[Type] = eval(
-    #     pld_spec_str,
-    #     {},  # globals
-    #     {'typing': typing},  # locals
-    # )
-
-    return Union[*types]
-
-
-def enc_type_union(
-    union_or_type: Union[Type]|Type,
-) -> list[str]:
-    '''
-    Encode a type-union or single type to a list of type-name-strings
-    ready for IPC interchange.
-
-    '''
-    type_strs: list[str] = []
-    for typ in getattr(
-        union_or_type,
-        '__args__',
-        {union_or_type,},
-    ):
-        type_strs.append(typ.__qualname__)
-
-    return type_strs

tractor/msg/_ops.py

@@ -50,9 +50,7 @@ from tractor._exceptions import (
     _mk_recv_mte,
     pack_error,
 )
-from tractor._state import (
-    current_ipc_ctx,
-)
+from tractor._state import current_ipc_ctx
 from ._codec import (
     mk_dec,
     MsgDec,
@@ -80,7 +78,7 @@ if TYPE_CHECKING:
 log = get_logger(__name__)
 
 
-_def_any_pldec: MsgDec[Any] = mk_dec(spec=Any)
+_def_any_pldec: MsgDec[Any] = mk_dec()
 
 
 class PldRx(Struct):
@@ -110,11 +108,33 @@ class PldRx(Struct):
     # TODO: better to bind it here?
     # _rx_mc: trio.MemoryReceiveChannel
     _pld_dec: MsgDec
+    _ctx: Context|None = None
+    _ipc: Context|MsgStream|None = None
 
     @property
     def pld_dec(self) -> MsgDec:
         return self._pld_dec
 
+    # TODO: a better name?
+    # -[ ] when would this be used as it avoids needingn to pass the
+    #   ipc prim to every method
+    @cm
+    def wraps_ipc(
+        self,
+        ipc_prim: Context|MsgStream,
+
+    ) -> PldRx:
+        '''
+        Apply this payload receiver to an IPC primitive type, one
+        of `Context` or `MsgStream`.
+
+        '''
+        self._ipc = ipc_prim
+        try:
+            yield self
+        finally:
+            self._ipc = None
+
     @cm
     def limit_plds(
         self,
@@ -128,10 +148,6 @@ class PldRx(Struct):
         exit.
 
         '''
-        # TODO, ensure we pull the current `MsgCodec`'s custom
-        # dec/enc_hook settings as well ?
-        # -[ ] see `._codec.mk_codec()` inputs
-        #
         orig_dec: MsgDec = self._pld_dec
         limit_dec: MsgDec = mk_dec(
             spec=spec,
@@ -147,7 +163,7 @@ class PldRx(Struct):
     def dec(self) -> msgpack.Decoder:
         return self._pld_dec.dec
 
-    def recv_msg_nowait(
+    def recv_pld_nowait(
         self,
         # TODO: make this `MsgStream` compat as well, see above^
         # ipc_prim: Context|MsgStream,
@@ -158,95 +174,34 @@ class PldRx(Struct):
         hide_tb: bool = False,
         **dec_pld_kwargs,
 
-    ) -> tuple[
-        MsgType[PayloadT],
-        PayloadT,
-    ]:
-        '''
-        Attempt to non-blocking receive a message from the `._rx_chan` and
-        unwrap it's payload delivering the pair to the caller.
-
-        '''
+    ) -> Any|Raw:
         __tracebackhide__: bool = hide_tb
 
         msg: MsgType = (
             ipc_msg
             or
+
             # sync-rx msg from underlying IPC feeder (mem-)chan
             ipc._rx_chan.receive_nowait()
         )
-        pld: PayloadT = self.decode_pld(
+        return self.decode_pld(
             msg,
             ipc=ipc,
             expect_msg=expect_msg,
             hide_tb=hide_tb,
             **dec_pld_kwargs,
         )
-        return (
-            msg,
-            pld,
-        )
-
-    async def recv_msg(
-        self,
-        ipc: Context|MsgStream,
-        expect_msg: MsgType,
-
-        # NOTE: ONLY for handling `Stop`-msgs that arrive during
-        # a call to `drain_to_final_msg()` above!
-        passthrough_non_pld_msgs: bool = True,
-        hide_tb: bool = True,
-
-        **decode_pld_kwargs,
-
-    ) -> tuple[MsgType, PayloadT]:
-        '''
-        Retrieve the next avail IPC msg, decode its payload, and
-        return the (msg, pld) pair.
-
-        '''
-        __tracebackhide__: bool = hide_tb
-        msg: MsgType = await ipc._rx_chan.receive()
-        match msg:
-            case Return()|Error():
-                log.runtime(
-                    f'Rxed final outcome msg\n'
-                    f'{msg}\n'
-                )
-            case Stop():
-                log.runtime(
-                    f'Rxed stream stopped msg\n'
-                    f'{msg}\n'
-                )
-                if passthrough_non_pld_msgs:
-                    return msg, None
-
-        # TODO: is there some way we can inject the decoded
-        # payload into an existing output buffer for the original
-        # msg instance?
-        pld: PayloadT = self.decode_pld(
-            msg,
-            ipc=ipc,
-            expect_msg=expect_msg,
-            hide_tb=hide_tb,
-
-            **decode_pld_kwargs,
-        )
-        return (
-            msg,
-            pld,
-        )
 
     async def recv_pld(
         self,
         ipc: Context|MsgStream,
-        ipc_msg: MsgType[PayloadT]|None = None,
+        ipc_msg: MsgType|None = None,
         expect_msg: Type[MsgType]|None = None,
         hide_tb: bool = True,
 
         **dec_pld_kwargs,
 
-    ) -> PayloadT:
+    ) -> Any|Raw:
         '''
         Receive a `MsgType`, then decode and return its `.pld` field.
 
@@ -258,13 +213,6 @@ class PldRx(Struct):
             # async-rx msg from underlying IPC feeder (mem-)chan
             await ipc._rx_chan.receive()
         )
-        if (
-            type(msg) is Return
-        ):
-            log.info(
-                f'Rxed final result msg\n'
-                f'{msg}\n'
-            )
         return self.decode_pld(
             msg=msg,
             ipc=ipc,
@@ -453,6 +401,45 @@ class PldRx(Struct):
             __tracebackhide__: bool = False
             raise
 
+    dec_msg = decode_pld
+
+    async def recv_msg_w_pld(
+        self,
+        ipc: Context|MsgStream,
+        expect_msg: MsgType,
+
+        # NOTE: generally speaking only for handling `Stop`-msgs that
+        # arrive during a call to `drain_to_final_msg()` above!
+        passthrough_non_pld_msgs: bool = True,
+        hide_tb: bool = True,
+        **kwargs,
+
+    ) -> tuple[MsgType, PayloadT]:
+        '''
+        Retrieve the next avail IPC msg, decode it's payload, and return
+        the pair of refs.
+
+        '''
+        __tracebackhide__: bool = hide_tb
+        msg: MsgType = await ipc._rx_chan.receive()
+
+        if passthrough_non_pld_msgs:
+            match msg:
+                case Stop():
+                    return msg, None
+
+        # TODO: is there some way we can inject the decoded
+        # payload into an existing output buffer for the original
+        # msg instance?
+        pld: PayloadT = self.decode_pld(
+            msg,
+            ipc=ipc,
+            expect_msg=expect_msg,
+            hide_tb=hide_tb,
+            **kwargs,
+        )
+        return msg, pld
+
 
 @cm
 def limit_plds(
@@ -468,16 +455,11 @@ def limit_plds(
 
     '''
     __tracebackhide__: bool = True
-    curr_ctx: Context|None = current_ipc_ctx()
-    if curr_ctx is None:
-        raise RuntimeError(
-            'No IPC `Context` is active !?\n'
-            'Did you open `limit_plds()` from outside '
-            'a `Portal.open_context()` scope-block?'
-        )
     try:
+        curr_ctx: Context = current_ipc_ctx()
         rx: PldRx = curr_ctx._pld_rx
         orig_pldec: MsgDec = rx.pld_dec
+
         with rx.limit_plds(
             spec=spec,
             **dec_kwargs,
@@ -487,11 +469,6 @@ def limit_plds(
                 f'{pldec}\n'
             )
             yield pldec
-
-    except BaseException:
-        __tracebackhide__: bool = False
-        raise
-
     finally:
         log.runtime(
             'Reverted to previous payload-decoder\n\n'
@@ -545,8 +522,8 @@ async def maybe_limit_plds(
 async def drain_to_final_msg(
     ctx: Context,
 
-    msg_limit: int = 6,
     hide_tb: bool = True,
+    msg_limit: int = 6,
 
 ) -> tuple[
     Return|None,
@@ -575,8 +552,8 @@ async def drain_to_final_msg(
     even after ctx closure and the `.open_context()` block exit.
 
     '''
+    __tracebackhide__: bool = hide_tb
     raise_overrun: bool = not ctx._allow_overruns
-    parent_never_opened_stream: bool = ctx._stream is None
 
     # wait for a final context result by collecting (but
     # basically ignoring) any bi-dir-stream msgs still in transit
@@ -585,14 +562,13 @@ async def drain_to_final_msg(
     result_msg: Return|Error|None = None
     while not (
         ctx.maybe_error
-        and
-        not ctx._final_result_is_set()
+        and not ctx._final_result_is_set()
     ):
         try:
             # receive all msgs, scanning for either a final result
             # or error; the underlying call should never raise any
             # remote error directly!
-            msg, pld = await ctx._pld_rx.recv_msg(
+            msg, pld = await ctx._pld_rx.recv_msg_w_pld(
                 ipc=ctx,
                 expect_msg=Return,
                 raise_error=False,
@@ -639,11 +615,6 @@ async def drain_to_final_msg(
                     )
                     __tracebackhide__: bool = False
 
-            else:
-                log.cancel(
-                    f'IPC ctx cancelled externally during result drain ?\n'
-                    f'{ctx}'
-                )
             # CASE 2: mask the local cancelled-error(s)
             # only when we are sure the remote error is
             # the source cause of this local task's
@@ -675,24 +646,17 @@ async def drain_to_final_msg(
             case Yield():
                 pre_result_drained.append(msg)
                 if (
-                    not parent_never_opened_stream
-                    and (
-                        (ctx._stream.closed
-                         and
-                         (reason := 'stream was already closed')
-                        ) or
-                        (ctx.cancel_acked
-                            and
-                            (reason := 'ctx cancelled other side')
-                        )
-                        or (ctx._cancel_called
-                            and
-                            (reason := 'ctx called `.cancel()`')
-                        )
-                        or (len(pre_result_drained) > msg_limit
-                            and
-                            (reason := f'"yield" limit={msg_limit}')
-                        )
+                    (ctx._stream.closed
+                     and (reason := 'stream was already closed')
+                    )
+                    or (ctx.cancel_acked
+                        and (reason := 'ctx cancelled other side')
+                    )
+                    or (ctx._cancel_called
+                        and (reason := 'ctx called `.cancel()`')
+                    )
+                    or (len(pre_result_drained) > msg_limit
+                        and (reason := f'"yield" limit={msg_limit}')
                     )
                 ):
                     log.cancel(
@@ -710,7 +674,7 @@ async def drain_to_final_msg(
                 # drain up to the `msg_limit` hoping to get
                 # a final result or error/ctxc.
                 else:
-                    report: str = (
+                    log.warning(
                         'Ignoring "yield" msg during `ctx.result()` drain..\n'
                         f'<= {ctx.chan.uid}\n'
                         f'  |_{ctx._nsf}()\n\n'
@@ -719,14 +683,6 @@ async def drain_to_final_msg(
 
                         f'{pretty_struct.pformat(msg)}\n'
                     )
-                    if parent_never_opened_stream:
-                        report = (
-                            f'IPC ctx never opened stream on {ctx.side!r}-side!\n'
-                            f'\n'
-                            # f'{ctx}\n'
-                        ) + report
-
-                    log.warning(report)
                     continue
 
             # stream terminated, but no result yet..
@@ -818,7 +774,6 @@ async def drain_to_final_msg(
             f'{ctx.outcome}\n'
         )
 
-    __tracebackhide__: bool = hide_tb
     return (
         result_msg,
         pre_result_drained,

tractor/msg/types.py

@@ -599,15 +599,15 @@ def mk_msg_spec(
         Msg[payload_type_union],
         Generic[PayloadT],
     )
-    # defstruct_bases: tuple = (
-    #     Msg, # [payload_type_union],
-    #     # Generic[PayloadT],
-    #     # ^-XXX-^: not allowed? lul..
-    # )
+    defstruct_bases: tuple = (
+        Msg, # [payload_type_union],
+        # Generic[PayloadT],
+        # ^-XXX-^: not allowed? lul..
+    )
     ipc_msg_types: list[Msg] = []
 
     idx_msg_types: list[Msg] = []
-    # defs_msg_types: list[Msg] = []
+    defs_msg_types: list[Msg] = []
     nc_msg_types: list[Msg] = []
 
     for msgtype in __msg_types__:
@@ -625,7 +625,7 @@ def mk_msg_spec(
         # TODO: wait why do we need the dynamic version here?
         # XXX ANSWER XXX -> BC INHERITANCE.. don't work w generics..
         #
-        # NOTE previously bc msgtypes WERE NOT inheriting
+        # NOTE previously bc msgtypes WERE NOT inheritting
         # directly the `Generic[PayloadT]` type, the manual method
         # of generic-paraming with `.__class_getitem__()` wasn't
         # working..
@@ -662,35 +662,38 @@ def mk_msg_spec(
 
         # with `msgspec.structs.defstruct`
         # XXX ALSO DOESN'T WORK
-        # defstruct_msgtype = defstruct(
-        #     name=msgtype.__name__,
-        #     fields=[
-        #         ('cid', str),
+        defstruct_msgtype = defstruct(
+            name=msgtype.__name__,
+            fields=[
+                ('cid', str),
 
-        #         # XXX doesn't seem to work..
-        #         # ('pld', PayloadT),
+                # XXX doesn't seem to work..
+                # ('pld', PayloadT),
+
+                ('pld', payload_type_union),
+            ],
+            bases=defstruct_bases,
+        )
+        defs_msg_types.append(defstruct_msgtype)
 
-        #         ('pld', payload_type_union),
-        #     ],
-        #     bases=defstruct_bases,
-        # )
-        # defs_msg_types.append(defstruct_msgtype)
         # assert index_paramed_msg_type == manual_paramed_msg_subtype
+
         # paramed_msg_type = manual_paramed_msg_subtype
+
         # ipc_payload_msgs_type_union |= index_paramed_msg_type
 
     idx_spec: Union[Type[Msg]] = Union[*idx_msg_types]
-    # def_spec: Union[Type[Msg]] = Union[*defs_msg_types]
+    def_spec: Union[Type[Msg]] = Union[*defs_msg_types]
     nc_spec: Union[Type[Msg]] = Union[*nc_msg_types]
 
     specs: dict[str, Union[Type[Msg]]] = {
         'indexed_generics': idx_spec,
-        # 'defstruct': def_spec,
+        'defstruct': def_spec,
         'types_new_class': nc_spec,
     }
     msgtypes_table: dict[str, list[Msg]] = {
         'indexed_generics': idx_msg_types,
-        # 'defstruct': defs_msg_types,
+        'defstruct': defs_msg_types,
         'types_new_class': nc_msg_types,
     }
 

tractor/trionics/_broadcast.py

@@ -22,7 +22,7 @@ https://docs.rs/tokio/1.11.0/tokio/sync/broadcast/index.html
 from __future__ import annotations
 from abc import abstractmethod
 from collections import deque
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager as acm
 from functools import partial
 from operator import ne
 from typing import (
@@ -398,7 +398,7 @@ class BroadcastReceiver(ReceiveChannel):
 
             return await self._receive_from_underlying(key, state)
 
-    @asynccontextmanager
+    @acm
     async def subscribe(
         self,
         raise_on_lag: bool = True,

tractor/trionics/_supervisor.py

@@ -0,0 +1,322 @@
+# tractor: structured concurrent "actors".
+# Copyright 2018-eternity Tyler Goodlet.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+'''
+Erlang-style (ish) "one-cancels-one" nursery.
+
+'''
+from __future__ import annotations
+from contextlib import (
+    asynccontextmanager as acm,
+    contextmanager as cm,
+)
+from functools import partial
+from typing import (
+    Generator,
+    Any,
+)
+
+from outcome import (
+    Outcome,
+    acapture,
+)
+from msgspec import Struct
+import trio
+from trio._core._run import (
+    Task,
+    CancelScope,
+    Nursery,
+)
+
+
+class TaskOutcome(Struct):
+    '''
+    The outcome of a scheduled ``trio`` task which includes an interface
+    for synchronizing to the completion of the task's runtime and access
+    to the eventual boxed result/value or raised exception.
+
+    '''
+    lowlevel_task: Task
+    _exited = trio.Event()  # as per `trio.Runner.task_exited()`
+    _outcome: Outcome | None = None  # as per `outcome.Outcome`
+    _result: Any | None = None  # the eventual maybe-returned-value
+
+    @property
+    def result(self) -> Any:
+        '''
+        Either Any or None depending on whether the Outcome has compeleted.
+
+        '''
+        if self._outcome is None:
+            raise RuntimeError(
+                f'Task {self.lowlevel_task.name} is not complete.\n'
+                'First wait on `await TaskOutcome.wait_for_result()`!'
+            )
+        return self._result
+
+    def _set_outcome(
+        self,
+        outcome: Outcome,
+    ):
+        '''
+        Set the ``Outcome`` for this task.
+
+        This method should only ever be called by the task's supervising
+        nursery implemenation.
+
+        '''
+        self._outcome = outcome
+        self._result = outcome.unwrap()
+        self._exited.set()
+
+    async def wait_for_result(self) -> Any:
+        '''
+        Unwind the underlying task's ``Outcome`` by async waiting for
+        the task to first complete and then unwrap it's result-value.
+
+        '''
+        if self._exited.is_set():
+            return self._result
+
+        await self._exited.wait()
+
+        out = self._outcome
+        if out is None:
+            raise ValueError(f'{out} is not an outcome!?')
+
+        return self.result
+
+
+class TaskManagerNursery(Struct):
+    _n: Nursery
+    _scopes: dict[
+        Task,
+        tuple[CancelScope, Outcome]
+    ] = {}
+
+    task_manager: Generator[Any, Outcome, None] | None = None
+
+    async def start_soon(
+        self,
+        async_fn,
+        *args,
+
+        name=None,
+        task_manager: Generator[Any, Outcome, None] | None = None
+
+    ) -> tuple[CancelScope, Task]:
+
+        # NOTE: internals of a nursery don't let you know what
+        # the most recently spawned task is by order.. so we'd
+        # have to either change that or do set ops.
+        # pre_start_tasks: set[Task] = n._children.copy()
+        # new_tasks = n._children - pre_start_Tasks
+        # assert len(new_tasks) == 1
+        # task = new_tasks.pop()
+
+        n: Nursery = self._n
+
+        sm = self.task_manager
+        # we do default behavior of a scope-per-nursery
+        # if the user did not provide a task manager.
+        if sm is None:
+            return n.start_soon(async_fn, *args, name=None)
+
+        new_task: Task | None = None
+        to_return: tuple[Any] | None = None
+
+        # NOTE: what do we enforce as a signature for the
+        # `@task_scope_manager` here?
+        mngr = sm(nursery=n)
+
+        async def _start_wrapped_in_scope(
+            task_status: TaskStatus[
+                tuple[CancelScope, Task]
+            ] = trio.TASK_STATUS_IGNORED,
+
+        ) -> None:
+
+            # TODO: this was working before?! and, do we need something
+            # like it to implement `.start()`?
+            # nonlocal to_return
+
+            # execute up to the first yield
+            try:
+                to_return: tuple[Any] = next(mngr)
+            except StopIteration:
+                raise RuntimeError("task manager didn't yield") from None
+
+            # TODO: how do we support `.start()` style?
+            # - relay through whatever the
+            #   started task passes back via `.started()` ?
+            #   seems like that won't work with also returning
+            #   a "task handle"?
+            # - we were previously binding-out this `to_return` to
+            #   the parent's lexical scope, why isn't that working
+            #   now?
+            task_status.started(to_return)
+
+            # invoke underlying func now that cs is entered.
+            outcome = await acapture(async_fn, *args)
+
+            # execute from the 1st yield to return and expect
+            # generator-mngr `@task_scope_manager` thinger to
+            # terminate!
+            try:
+                mngr.send(outcome)
+
+
+                # I would presume it's better to have a handle to
+                # the `Outcome` entirely? This method sends *into*
+                # the mngr this `Outcome.value`; seems like kinda
+                # weird semantics for our purposes?
+                # outcome.send(mngr)
+
+            except StopIteration:
+                return
+            else:
+                raise RuntimeError(f"{mngr} didn't stop!")
+
+        to_return = await n.start(_start_wrapped_in_scope)
+        assert to_return is not None
+
+        # TODO: use the fancy type-check-time type signature stuff from
+        # mypy i guess..to like, relay the type of whatever the
+        # generator yielded through? betcha that'll be un-grokable XD
+        return to_return
+
+
+# TODO: define a decorator to runtime type check that this a generator
+# with a single yield that also delivers a value (of some std type) from
+# the yield expression?
+# @trio.task_manager
+def add_task_handle_and_crash_handling(
+    nursery: Nursery,
+
+    debug_mode: bool = False,
+
+) -> Generator[
+    Any,
+    Outcome,
+    None,
+]:
+    '''
+    A customizable, user defined "task scope manager".
+
+    With this specially crafted single-yield generator function you can
+    add more granular controls around every task spawned by `trio` B)
+
+    '''
+    # if you need it you can ask trio for the task obj
+    task: Task = trio.lowlevel.current_task()
+    print(f'Spawning task: {task.name}')
+
+    # User defined "task handle" for more granular supervision
+    # of each spawned task as needed for their particular usage.
+    task_outcome = TaskOutcome(task)
+
+    # NOTE: if wanted the user could wrap the output task handle however
+    # they want!
+    # class TaskHandle(Struct):
+    #     task: Task
+    #     cs: CancelScope
+    #     outcome: TaskOutcome
+
+    # this yields back when the task is terminated, cancelled or returns.
+    try:
+        with CancelScope() as cs:
+
+            # the yielded value(s) here are what are returned to the
+            # nursery's `.start_soon()` caller B)
+            lowlevel_outcome: Outcome = yield (task_outcome, cs)
+            task_outcome._set_outcome(lowlevel_outcome)
+
+    # Adds "crash handling" from `pdbp` by entering
+    # a REPL on std errors.
+    except Exception as err:
+        print(f'{task.name} crashed, entering debugger!')
+        if debug_mode:
+            import pdbp
+            pdbp.xpm()
+        raise
+
+    finally:
+        print(f'{task.name} Exitted')
+
+
+@acm
+async def open_nursery(
+    task_manager: Generator[Any, Outcome, None] | None = None,
+
+    **lowlevel_nursery_kwargs,
+):
+    async with trio.open_nursery(**lowlevel_nursery_kwargs) as nurse:
+        yield TaskManagerNursery(
+            nurse,
+            task_manager=task_manager,
+        )
+
+
+async def sleep_then_return_val(val: str):
+    await trio.sleep(0.2)
+    return val
+
+
+async def ensure_cancelled():
+    try:
+        await trio.sleep_forever()
+
+    except trio.Cancelled:
+        task = trio.lowlevel.current_task()
+        print(f'heyyo ONLY {task.name} was cancelled as expected B)')
+        assert 0
+
+    except BaseException:
+        raise RuntimeError("woa woa woa this ain't right!")
+
+
+if __name__ == '__main__':
+
+    async def main():
+        async with open_nursery(
+            task_manager=partial(
+                add_task_handle_and_crash_handling,
+                debug_mode=True,
+            ),
+        ) as sn:
+            for _ in range(3):
+                outcome, _ = await sn.start_soon(trio.sleep_forever)
+
+            # extra task we want to engage in debugger post mortem.
+            err_outcome, cs = await sn.start_soon(ensure_cancelled)
+
+            val: str = 'yoyoyo'
+            val_outcome, _ = await sn.start_soon(
+                sleep_then_return_val,
+                val,
+            )
+            res = await val_outcome.wait_for_result()
+            assert res == val
+            print(f'{res} -> GOT EXPECTED TASK VALUE')
+
+            await trio.sleep(0.6)
+            print(
+                f'Cancelling and waiting on {err_outcome.lowlevel_task} '
+                'to CRASH..'
+            )
+            cs.cancel()
+
+    trio.run(main)