Transport

casty.MessageTransport

Bases: Protocol

Protocol for delivering messages to actors by address.

Any object with a deliver(address, msg) method satisfies this protocol.

Examples:

Minimal implementation:

>>> class NullTransport:
...     def deliver(self, address: ActorAddress, msg: object) -> None:
...         pass  # discard all messages

deliver(address, msg)

Deliver a message to the actor at the given address.

Parameters:

Name	Type	Description	Default
address	ActorAddress	Target actor address.	required
msg	Any	The message to deliver.	required

casty.LocalTransport

In-process message transport that routes by actor path.

Messages to unregistered paths are buffered (up to max_pending_per_path) until a handler registers. Messages to paths that have been unregistered (dead actors) are dropped.

Parameters:

Name	Type	Description	Default
max_pending_per_path	int	Maximum buffered messages per path before dropping. Default is 64.	64

Examples:

>>> transport = LocalTransport()
>>> received = []
>>> transport.register("/user/actor", received.append)
>>> transport.deliver(ActorAddress(system="sys", path="/user/actor"), "hello")
>>> received
['hello']

__init__(*, max_pending_per_path=64)

register_path_factory(prefix, factory)

Register a factory that lazily spawns handlers for paths with a given prefix.

When deliver() encounters an unregistered path starting with prefix, it calls factory(path) which should register a handler for that path.

Parameters:

Name	Type	Description	Default
prefix	str	Path prefix to match (e.g. "/_coord-").	required
factory	Callable[[str], None]	Called with the full path; must call register() for that path.	required

register(path, handler)

Register a message handler for the given path.

Any messages buffered for this path are flushed to the handler immediately.

Parameters:

Name	Type	Description	Default
path	str	Actor path (e.g. /user/counter).	required
handler	Callable[[Any], None]	Callback invoked with each delivered message.	required

unregister(path)

Remove the handler for the given path and mark it dead.

Future messages to this path are dropped rather than buffered.

Parameters:

Name	Type	Description	Default
path	str	Actor path to unregister.	required

wait_for_path(path) async

Wait until a handler is registered for the given path.

deliver(address, msg)

Deliver a message to the handler registered for the address path.

If no handler is registered and the path is not dead, the message is buffered. If the buffer is full, the message is dropped.

Parameters:

Name	Type	Description	Default
address	ActorAddress	Target actor address.	required
msg	Any	The message to deliver.	required

casty.MessageEnvelope dataclass

Wire-format envelope for messages sent over TCP.

Serializes to binary as [header_len:4][header_json][payload].

Parameters:

Name	Type	Description	Default
target	str	URI of the target actor.	required
sender	str	URI of the sending actor or system.	required
payload	bytes	Serialized message body.	required
type_hint	str	Fully-qualified type name of the message.	required

Examples:

>>> env = MessageEnvelope(target="casty://sys/user/a", sender="casty://sys/",
...                       payload=b'{"x":1}', type_hint="mymod.Msg")
>>> data = env.to_bytes()
>>> MessageEnvelope.from_bytes(data).target
'casty://sys/user/a'

target instance-attribute

sender instance-attribute

payload instance-attribute

type_hint instance-attribute

to_bytes()

Serialize the envelope to binary wire format.

Returns:

Type	Description
bytes	Binary data: [header_len:4][header_json][payload].

from_bytes(data) staticmethod

Deserialize a MessageEnvelope from binary wire format.

Parameters:

Name	Type	Description	Default
data	bytes	Binary data produced by to_bytes().	required

Returns:

Type	Description
MessageEnvelope

__init__(target, sender, payload, type_hint)

casty.RemoteTransport

Bridge between MessageTransport and the TCP transport actor.

Routes local messages through LocalTransport and remote messages through TCP serialization via tell(SendToNode(...)).

sender_host property

Host used in outbound sender URIs (advertised or local).

sender_port property

Port used in outbound sender URIs (advertised or local).

__init__(*, local, tcp, local_host, local_port, system_name, advertised_host=None, advertised_port=None, task_runner=None, on_send_failure=None, local_node_id=None)

update_node_index(index)

Replace the node index used for node_id resolution.

deliver(address, msg)

Deliver a message to the given address.

Local addresses are routed through LocalTransport; remote addresses are serialized and sent via TCP.

make_ref(address)

Create an ActorRef with the appropriate transport for the address.

clear_blacklist(host, port)

Clear the TCP circuit breaker for a specific endpoint.

casty.TcpTransportConfig dataclass

host instance-attribute

port instance-attribute

self_address = None class-attribute instance-attribute

client_only = False class-attribute instance-attribute

server_ssl = None class-attribute instance-attribute

client_ssl = None class-attribute instance-attribute

connect_timeout = 2.0 class-attribute instance-attribute

blacklist_duration = 5.0 class-attribute instance-attribute

address_map = field(default_factory=(lambda: _identity_address)) class-attribute instance-attribute

__init__(host, port, self_address=None, client_only=False, server_ssl=None, client_ssl=None, connect_timeout=2.0, blacklist_duration=5.0, address_map=(lambda: _identity_address)())

casty.TcpTransportMsg = SendToNode | SendFrameToNode | InboundAccepted | PeerDown | ClearNodeBlacklist | GetPort | DeliverToNode | LogSerializationFailure

casty.tcp_transport(config, handler, logger=None, serializer=None)

Actor managing TCP connections to all peers.

On setup, starts a TCP server (unless client_only). The accept callback performs the handshake outside the actor, then tells itself InboundAccepted. Outbound connections are established inside the receive handler on first SendToNode to a new peer.

casty.SendToNode dataclass

host instance-attribute

port instance-attribute

data instance-attribute

__init__(host, port, data)

casty.DeliverToNode dataclass

host instance-attribute

port instance-attribute

msg instance-attribute

target instance-attribute

sender instance-attribute

__init__(host, port, msg, target, sender)

casty.ClearNodeBlacklist dataclass

host instance-attribute

port instance-attribute

__init__(host, port)

casty.GetPort dataclass

reply_to instance-attribute

__init__(reply_to)

casty.InboundMessageHandler

Deserializes inbound TCP frames and delivers them locally.

Satisfies InboundHandler structurally. Passed directly to tcp_transport at spawn time — no placeholder or delegate wiring needed.

ref_factory = ref_factory instance-attribute

__init__(*, local, serializer, system_name, ref_factory=None)

on_message(data) async