diameter_tcp(3)

💖 diameter_tcp(3) — Erlang Module Definition 💖

okay bestie, gather round, because we're talking about diameter_tcp, the Diameter-over-TCP transport module, and honestly? it's giving main character energy in the Erlang/OTP diameter world. this is page 3 of the manual, section 3, and it's literally the whole vibe of how Diameter rides on TCP. let's go 🫶

---

✨ NAME ✨

diameter_tcp — Diameter transport over TCP. that's it, that's the whole name, no cap 💅

---

🌸 DESCRIPTION 🌸

so this module implements Diameter transport over TCP, and it does it using gen_tcp. iconic behaviour, truly. you specify it as the value of a transport_module option to diameter:add_transport/2, and it implements the behaviour that's documented over in diameter_transport. 🎀

TLS security is supported, bestie — either as an upgrade following capabilities exchange, or at connection establishment. two paths, both slay 💖

ok queen, heads up: the ssl application is required for TLS and it must be started before configuring TLS capability on diameter transports. no ssl, no TLS, periodt. 😭

🌈 SEE ALSO

• diameter
• diameter_transport
• gen_tcp
• inet
• ssl

---

🦋 DATA TYPES 🦋

here's the tea on the types, and we're keeping every last drop 🍓

connect_option() ::
          {raddr, inet:ip_address()} |
          {rport, pos_integer()} |
          {ssl_options, true | [ssl:tls_client_option()]} |
          option() |
          ssl:tls_client_option() |
          gen_tcp:connect_option().

listen_option() ::
          {accept, match()} |
          {ssl_options, true | [ssl:tls_server_option()]} |
          option() |
          ssl:tls_server_option() |
          gen_tcp:listen_option().

match() :: inet:ip_address() | string() | [match()].

option() ::
          {port, non_neg_integer()} |
          {sender, boolean()} |
          sender |
          {message_cb, false | diameter:eval()} |
          {fragment_timer, 0..4294967295}.

---

👑 FUNCTIONS 👑

⭐ start/3 ⭐

start({accept, Ref}, #diameter_service{}, [listen_option()]) ->
               {ok, pid(), [inet:ip_address()]}
               when Ref :: diameter:transport_ref();
           ({connect, Ref}, #diameter_service{}, [connect_option()]) ->
               {ok, pid()}
               when Ref :: diameter:transport_ref().

start({Type, Ref}, Svc, [Opt]) -> {ok, Pid} | {ok, Pid, [LAddr]}
| {error, Reason}

this is the start function required by diameter_transport. it's the entry point, the whole moment, the vibe check that gets your transport going 🔥

---

🌷 the options, one by one, no skipping

• raddr and rport — these specify the remote address and port for a connecting transport. and listen, they are not valid for a listening transport. nope, not today 💀
• accept — specifies remote addresses for a listening transport, and it is not valid for a connecting transport. if you specify it, a remote address that doesn't match one of the specified addresses causes the connection to be aborted. you can specify multiple accept options, multiple!! and a string-valued Match that doesn't parse as an address is interpreted as a regular expression. fancy ✨
• ssl_options — this one must be specified for a transport that should support TLS:
  • a value of true results in a TLS handshake immediately upon connection establishment 🫶
  • while list/0 specifies options to be passed to ssl:connect/2 or ssl:handshake/2 after capabilities exchange, if TLS is negotiated.
• fragment_timer — specifies the timeout, in milliseconds, of a timer used to flush messages from the incoming byte stream even if the number of bytes indicated in the Message Length field of its Diameter Header have not yet been accumulated. such a message is received over the transport interface after two successive timeouts without the reception of additional bytes. defaults to 1000. ⏱️
• sender — specifies whether or not to use a dedicated process for sending outgoing messages, which avoids the possibility of send blocking reception. defaults to false. but if you set it to true, then a message_cb that avoids the possibility of messages being queued in the sender process without bound should be configured. lowkey important, bestie 😭
• message_cb — specifies a callback that is invoked on incoming and outgoing messages, and it can be used to implement flow control. it's applied to two arguments:
  • an atom indicating the reason for the callback (send, recv, or ack after a completed send), and
  • the message in question (binary() on recv, binary() or diameter*packet record on send or ack, or false on ack when an incoming request has been discarded).

it should return a list of actions and a new callback as tail; eg. [fun cb/3, State]. valid actions are:

• the atoms send or recv, to cause a following message-valued action to be sent/received,
• a message to send/receive (binary() or diameter_packet record), or
• a boolean() to enable/disable reading on the socket.

more than one send/recv/message sequence can be returned from the same callback, and an initial send/recv can be omitted if the same as the value passed as the callback's first argument. reading is initially enabled, and returning false does not imply there cannot be subsequent recv callbacks since messages may already have been read. an empty tail is equivalent to the prevailing callback. defaults to a callback equivalent to fun(ack, *) -> []; (\_, Msg) -> [Msg] end.

---

🧚 the rest of the options

remaining options are any accepted by ssl:connect/3 or gen_tcp:connect/3 for a connecting transport, or ssl:listen/2 or gen_tcp:listen/2 for a listening transport, depending on whether or not {ssl_options, true} has been specified.

options binary, packet and active cannot be specified. 🚫

also, option port can be specified for a listening transport to specify the local listening port, the default being the standardized 3868. and note that the option ip specifies the local address. 💅

---

💀 the TLS rules, pay attention bestie

an ssl_options list must be specified if and only if the transport in question has set Inband-Security-Id to 1 (TLS), as specified to either diameter:start_service/2 or diameter:add_transport/2, so that the transport process will receive notification of whether or not to commence with a TLS handshake following capabilities exchange.

failing to specify an options list on a TLS-capable transport for which TLS is negotiated will cause TLS handshake to fail. 😭

failing to specify TLS capability when ssl_options has been specified will cause the transport process to wait for a notification that will not be forthcoming, which will eventually cause the RFC 3539 watchdog to take down the connection. not the ending we wanted, fr fr 💀

---

🌟 one last local-address detail

the first element of a non-empty Host-IP-Address list in Svc provides the local IP address if an ip option is not specified. the local address is either returned from start/3 or passed in a connected message over the transport interface. 🦋

---

and that's the whole page, bestie — every option, every default, every warning, all of it, no crumbs left behind 🍓✨

---

this gem of a manual page came to you from Ericsson AB, and it's the diameter application, version 2.7.2, page diameter_tcp(3) — that's the version and date stamp right there, lovingly folded into this little sign-off instead of the boring footer. mwah 💋