diameter_transport(3)

👑 diameter_transport — Erlang Module Definition ✨

okay bestie, welcome to diameter_transport(3), the manual page for the Diameter transport interface. it's giving "spec document that actually ate" 💅

---

🌸 NAME 🌸

diameter_transport — Diameter transport interface. periodt.

---

🦋 DESCRIPTION 🦋

so here's the deal: if you hand a module over as a transport_module to diameter:add_transport/2, that module must implement the interface documented right here. no cap. the interface is two things: a function that diameter uses to start a transport process, and a message interface that lets the transport process talk to the process that started it (aka its parent 🫶).

📦 DATA TYPES 📦

message() = binary() | diameter_codec:packet()

that's a Diameter message the way it travels over the transport interface. lowkey important, so let's break it down:

• for an inbound message coming from a transport process, a diameter_codec:packet() has to have the received message sitting in its bin field. and if it's an inbound request, whatever value you set in the transport_data field gets passed right back to the transport module in the matching answer message 💖 — unless the sender supplies a different value, in which case, respectfully, that one wins.
• for an outbound message going to a transport process, a diameter_codec:packet() has a value that is not undefined in its transport_data field, and it has the binary() to send in its bin field. that's it, that's the vibe.

💌 MESSAGES 💌

every single message sent over the transport interface has the exact form {diameter, term()}. iconic, consistent, we love that for us.

a transport process can expect these message types from its parent 👇

• {diameter, {send, message() | false}} — an outbound Diameter message. the atom false can only show up when request acknowledgements have been requested — go read the ack message below, iykyk 🔥
• {diameter, {close, Pid}} — a request to terminate the transport process, sent after it's received DPA in response to DPR. the transport process should exit. Pid is the pid() of the parent process.
• {diameter, {tls, Ref, Type, Bool}} — a heads-up about whether or not capabilities exchange has selected inband security using TLS. Ref is a reference() that has to be included in the {diameter, {tls, Ref}} reply message to the transport's parent process (see below 👇). Type is either connect or accept, depending on whether the process got started for a connecting or a listening transport respectively. Bool is a boolean() saying whether or not the transport connection should be upgraded to TLS.

if TLS is requested (Bool=true) then a connecting process should initiate a TLS handshake with the peer, and an accepting process should get ready to accept a handshake. a successful handshake should be followed by a {diameter, {tls, Ref}} message to the parent process. a failed handshake should cause the process to exit. like, it's over, go home 😭

not me reminding you: this message is only sent to a transport process whose Inband-Security-Id configuration has indicated support for TLS. no TLS config, no message, periodt.

and a transport process should send these message types to its parent 👇

• {diameter, {self(), connected}} — tells the parent that the transport process with Type=accept has established a connection with the peer. not sent if the transport process has Type=connect.
  • {diameter, {self(), connected, Remote}}
• {diameter, {self(), connected, Remote, [LocalAddr]}} — tells the parent that the transport process with Type=connect has established a connection with a peer. not sent if the transport process has Type=accept. Remote is an arbitrary term that uniquely identifies the remote endpoint the transport has connected to. a LocalAddr list has the same semantics as one returned from start/3 👑
• {diameter, ack} — request acknowledgements of unanswered requests. a transport process should send this once before passing incoming Diameter messages into diameter. as a result, every Diameter request passed into diameter with a recv message (below) will be answered with a send message (above) — either a message() for the transport process to send, or the atom false if the request has been discarded or otherwise not answered.

the whole point is to let a transport process keep count of the number of incoming request messages that have not yet been answered or discarded, so it can regulate the amount of incoming traffic. both diameter_tcp and diameter_sctp request acknowledgements when a message_cb is configured, which turns send/recv messages into callbacks you can use to regulate traffic. cute and functional 💖

• {diameter, {recv, message()}} — an inbound Diameter message. hi bestie 👋
• {diameter, {tls, Ref}} — acknowledgment of a successful TLS handshake. Ref is the reference() received in the {diameter, {tls, Ref, Type, Bool}} message in response to which the reply is sent. a transport must exit if a handshake is not successful. no half measures 🚫

---

🌈 SEE ALSO 🌈

diameter_tcp, diameter_sctp — go read those next, bestie.

---

🔥 FUNCTIONS 🔥

🎀 CALLBACKS 🎀

⭐ start/3

starts a transport process. diameter calls this as a consequence of a call to diameter:add_transport/2, in order to establish or accept a transport connection respectively. a transport process maintains a connection with a single remote peer. one peer, one process, monogamy 🫶

• Type tells you whether the transport process in question is being started for a connecting (Type=connect) or a listening (Type=accept) transport. in the accept case, transport processes get started as required to accept connections from multiple peers.
• Ref is the value that was returned from the call to diameter:add_transport/2 that has lead to starting of a transport process.
• Svc contains capabilities passed to diameter:start_service/2 and diameter:add_transport/2, and values passed to the latter override those passed to the former. later wins, that's the law 💅
• Config is as passed in the transport_config tuple in the diameter:transport_opt() list passed to diameter:add_transport/2.

the start function should use the Host-IP-Address list in Svc and/or Config to select and return an appropriate list of local IP addresses. in the connecting case, the local address list can instead be communicated in a connected message (see MESSAGES above ⬆️) following connection establishment. either way, the local address list is used to populate Host-IP-Address AVPs in outgoing capabilities exchange messages if Host-IP-Address is unspecified.

okay and this part is mandatory, no skipping: a transport process must implement the message interface documented below. it should retain the pid of its parent, monitor the parent and terminate if it dies. it should not link to the parent. and it should exit if its transport connection with its peer is lost. protect your peace and also protect your parent process, fr fr 🧚

---

and that's the whole page, bestie — this one came from Ericsson AB, it's diameter 2.7.2, and it's filed under diameter_transport(3). slay, go implement a transport 💖✨🎀