Crate theater_handler_tcp 

TCP Handler

Provides raw TCP networking capabilities to WebAssembly actors in the Theater system. This handler is deliberately minimal — it moves bytes across the boundary and leaves all protocol complexity (framing, routing, addressing) to actor-space code.

Connection Handoff

Connections can be transferred between actors for the “accept and hand off” pattern:

1. Acceptor calls accept() - connection starts in PENDING state
2. Acceptor spawns a worker actor
3. Acceptor calls transfer(conn_id, worker_id) - atomically transfers and activates
4. Worker receives handle-connection callback and can immediately send/receive

This prevents race conditions where data arrives before the handoff completes.

Data Modes (Erlang-style)

Connections support three data modes via set-active():

• "passive" (default): Data received only via explicit receive() calls
• "active": Data pushed to actor via on-data callback continuously
• "once": Single on-data callback, then switches back to passive

This matches Erlang/OTP’s {active, true/false/once} socket options.

TLS Support

TLS can be enabled via manifest configuration:

[[handler]]
type = "tcp"

[handler.client_tls]
enabled = true
# ca_cert = "/path/to/ca.pem"  # Optional custom CA
# skip_verify = false          # For development only

[handler.server_tls]
enabled = true
cert = "/path/to/server.pem"
key = "/path/to/server-key.pem"

When TLS is configured, connections are automatically encrypted. The actor code doesn’t need to change - it uses the same tcp-connect, tcp-listen, tcp-read, tcp-write interface.

Structs

TcpHandler

Handler for providing raw TCP networking access to WebAssembly actors.