macula_dist_tunnel_socket (macula v13.2.1)

The socket a distribution tunnel's TLS session runs on.

A distribution tunnel's data travels inside a TLS 1.3 session run end to end between the two nodes (D29): the carrier underneath forwards the bytes and is not trusted with them, whether that carrier is a relay or the stations of the pool path. OTP's ssl runs over whatever transport a cb_info option names, so this module makes a macula QUIC stream look like a socket to it.

One process owns the stream and is the socket: it takes the stream's events, hands them to ssl in the tags ssl expects, and answers recv when ssl is passive. Sends go through it as well, because a QUIC stream is written by its owner and ssl writes from a process of its own.

Use it as

{ok, Socket} = macula_dist_tunnel_socket:own(Stream), {ok, Session} = ssl:connect(Socket, [{cb_info, ?MACULA_TUNNEL_CB_INFO} | Opts], Timeout)

and on the accepting side ssl:handshake/3 with the same cb_info.

⚠ What is NOT here: nothing in this module decides who the peer is. It carries bytes. The connection handshake that names the peer runs inside the session, against the leaf the session presented.

Summary

Types

socket/0

Functions

cb_info()

The cb_info option naming this module and its tags. The passive tag is the fifth, and it is not optional here: ssl reads with {active, N}, and without a passive tag to end a run it cannot tell that its count is spent.

close(Socket)

controlling_process(Socket, Pid)

getopts(Socket, Opts)

getstat(Socket, Opts)

handle_call(Request, From, State)

handle_cast(Cast, S)

handle_info(Info, State)

init(_)

own(Stream)

Take over Stream and return the socket to hand ssl. The caller is the socket's owner: it receives the active messages until controlling_process/2 names another, and the socket ends when it does.

peername(Socket)

port(Socket)

recv(Socket, Length, Timeout)

send(Socket, Data)

setopts(Socket, Opts)

shutdown(Socket, How)

sockname(Socket)

terminate(Reason, State)