From 7ac730e326e6ae20619d5f3ac3415d08b5b97a50 Mon Sep 17 00:00:00 2001
From: Tyler Goodlet <jgbt@protonmail.com>
Date: Tue, 28 May 2024 09:55:16 -0400
Subject: [PATCH] Drop `msg.types.Msg` for new replacement types

The `TypeAlias` for the msg type-group is now `MsgType` and any user
touching shuttle messages can now be typed as `PayloadMsg`.

Relatedly, add MTE specific `Error._bad_msg[_as_dict]` fields which are
handy for introspection of remote decode failures.
---
 tractor/_ipc.py       |  2 +-
 tractor/msg/_codec.py | 10 +++++-----
 tractor/msg/types.py  | 39 +++++++++++++++++++++++----------------
 3 files changed, 29 insertions(+), 22 deletions(-)

diff --git a/tractor/_ipc.py b/tractor/_ipc.py
index 511a053..ec7d348 100644
--- a/tractor/_ipc.py
+++ b/tractor/_ipc.py
@@ -291,7 +291,7 @@ class MsgpackTCPStream(MsgTransport):
 
     async def send(
         self,
-        msg: msgtypes.Msg,
+        msg: msgtypes.MsgType,
 
         strict_types: bool = True,
         # hide_tb: bool = False,
diff --git a/tractor/msg/_codec.py b/tractor/msg/_codec.py
index cd86552..e1c59e9 100644
--- a/tractor/msg/_codec.py
+++ b/tractor/msg/_codec.py
@@ -140,7 +140,7 @@ class MsgDec(Struct):
     #      * also a `.__contains__()` for doing `None in
     #      TypeSpec[None|int]` since rn you need to do it on
     #      `.__args__` for unions..
-    #     - `MsgSpec: Union[Type[Msg]]
+    #     - `MsgSpec: Union[MsgType]
     #
     # -[ ] auto-genning this from new (in 3.12) type parameter lists Bo
     # |_ https://docs.python.org/3/reference/compound_stmts.html#type-params
@@ -188,7 +188,7 @@ def mk_dec(
 
     return MsgDec(
         _dec=msgpack.Decoder(
-            type=spec,  # like `Msg[Any]`
+            type=spec,  # like `MsgType[Any]`
             dec_hook=dec_hook,
         )
     )
@@ -561,7 +561,7 @@ def mk_codec(
 
     '''
     # (manually) generate a msg-payload-spec for all relevant
-    # god-boxing-msg subtypes, parameterizing the `Msg.pld: PayloadT`
+    # 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).
@@ -607,7 +607,7 @@ _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
-# to use any `msgspec` supported type as the `Msg.pld` payload,
+# to use any `msgspec` supported type as the `PayloadMsg.pld` payload,
 # https://jcristharif.com/msgspec/supported-types.html
 #
 _def_tractor_codec: MsgCodec = mk_codec(
@@ -743,7 +743,7 @@ def limit_msg_spec(
 ) -> MsgCodec:
     '''
     Apply a `MsgCodec` that will natively decode the SC-msg set's
-    `Msg.pld: Union[Type[Struct]]` payload fields using
+    `PayloadMsg.pld: Union[Type[Struct]]` payload fields using
     tagged-unions of `msgspec.Struct`s from the `payload_types`
     for all IPC contexts in use by the current `trio.Task`.
 
diff --git a/tractor/msg/types.py b/tractor/msg/types.py
index f8205c2..08511ec 100644
--- a/tractor/msg/types.py
+++ b/tractor/msg/types.py
@@ -89,11 +89,12 @@ class PayloadMsg(
     # -[ ] `uuid.UUID` which has multi-protocol support
     #  https://jcristharif.com/msgspec/supported-types.html#uuid
 
-    # The msgs "payload" (spelled without vowels):
+    # The msg's "payload" (spelled without vowels):
     # https://en.wikipedia.org/wiki/Payload_(computing)
-    #
-    # NOTE: inherited from any `Msg` (and maybe overriden
-    # by use of `limit_msg_spec()`), but by default is
+    pld: Raw
+
+    # ^-NOTE-^ inherited from any `PayloadMsg` (and maybe type
+    # overriden via the `._ops.limit_plds()` API), but by default is
     # parameterized to be `Any`.
     #
     # XXX this `Union` must strictly NOT contain `Any` if
@@ -106,7 +107,6 @@ class PayloadMsg(
     # TODO: could also be set to `msgspec.Raw` if the sub-decoders
     # approach is preferred over the generic parameterization 
     # approach as take by `mk_msg_spec()` below.
-    pld: Raw
 
 
 # TODO: complete rename
@@ -412,19 +412,24 @@ class Error(
     relay_path: list[tuple[str, str]]
     tb_str: str
 
-    cid: str|None = None
-
-    # TODO: use UNSET or don't include them via
+    # TODO: only optionally include sub-type specfic fields?
+    # -[ ] use UNSET or don't include them via `omit_defaults` (see
+    #      inheritance-line options above)
     #
-    # `ContextCancelled`
+    # `ContextCancelled` reports the src cancelling `Actor.uid`
     canceller: tuple[str, str]|None = None
 
-    # `StreamOverrun`
+    # `StreamOverrun`-specific src `Actor.uid`
     sender: tuple[str, str]|None = None
 
-    # for the `MsgTypeError` case where the receiver side
-    # decodes the underlying original `Msg`-subtype
-    _msg_dict: dict|None = None
+    # `MsgTypeError` meta-data
+    cid: str|None = None
+    # when the receiver side fails to decode a delivered
+    # `PayloadMsg`-subtype; one and/or both the msg-struct instance
+    # and `Any`-decoded to `dict` of the msg are set and relayed
+    # (back to the sender) for introspection.
+    _bad_msg: Started|Yield|Return|None = None
+    _bad_msg_as_dict: dict|None = None
 
 
 def from_dict_msg(
@@ -436,9 +441,11 @@ def from_dict_msg(
 
 ) -> MsgType:
     '''
-    Helper to build a specific `MsgType` struct from
-    a "vanilla" decoded `dict`-ified equivalent of the
-    msg: i.e. if the `msgpack.Decoder.type == Any`.
+    Helper to build a specific `MsgType` struct from a "vanilla"
+    decoded `dict`-ified equivalent of the msg: i.e. if the
+    `msgpack.Decoder.type == Any`, the default when using
+    `msgspec.msgpack` and not "typed decoding" using
+    `msgspec.Struct`.
 
     '''
     msg_type_tag_field: str = (