1diameter_app(3) Erlang Module Definition diameter_app(3)
2
6 diameter_app - Callback module of a Diameter application.
7
9 A diameter service as started by diameter:start_service/2 configures
10 one of more Diameter applications, each of whose configuration speci‐
11 fies a callback that handles messages specific to the application. The
12 messages and AVPs of the application are defined in a dictionary file
13 whose format is documented in diameter_dict(4) while the callback mod‐
14 ule is documented here. The callback module implements the Diameter ap‐
15 plication-specific functionality of a service.
16 A callback module must export all of the functions documented below.
18 The functions themselves are of three distinct flavours:
19 * peer_up/3 and peer_down/3 signal the attainment or loss of connec‐
21 tivity with a Diameter peer.
22 * pick_peer/4, prepare_request/3, prepare_retransmit/3, handle_an‐
24 swer/4 and handle_error/4 are (or may be) called as a consequence
25 of a call to diameter:call/4 to send an outgoing Diameter request
26 message.
27 * handle_request/3 is called in response to an incoming Diameter re‐
29 quest message.
30 The arities for the the callback functions here assume no extra argu‐
32 ments. All functions will also be passed any extra arguments configured
33 with the callback module itself when calling diameter:start_service/2
34 and, for the call-specific callbacks, any extra arguments passed to di‐
35 ameter:call/4.
36
38 capabilities() = #diameter_caps{}:
39 A record containing the identities of the local Diameter node and
40 the remote Diameter peer having an established transport connec‐
41 tion, as well as the capabilities as determined by capabilities ex‐
42 change. Each field of the record is a 2-tuple consisting of values
43 for the (local) host and (remote) peer. Optional or possibly multi‐
44 ple values are encoded as lists of values, mandatory values as the
45 bare value.
46 message() = diameter_codec:message():
48 The representation of a Diameter message as passed to diame‐
49 ter:call/4 or returned from a handle_request/3 callback.
50 packet() = diameter_codec:packet():
52 A container for incoming and outgoing Diameter messages that's
53 passed through encode/decode and transport. Fields should not be
54 set in return values except as documented.
55 peer_ref() = term():
57 A term identifying a transport connection with a Diameter peer.
58 peer() = {peer_ref(), capabilities()}:
60 A tuple representing a Diameter peer connection.
61 state() = term():
63 The state maintained by the application callback functions
64 peer_up/3, peer_down/3 and (optionally) pick_peer/4. The initial
65 state is configured in the call to diameter:start_service/2 that
66 configures the application on a service. Callback functions return‐
67 ing a state are evaluated in a common service-specific process
68 while those not returning state are evaluated in a request-specific
69 process.
70
72 Mod:peer_up(SvcName, Peer, State) -> NewState
73 Types:
75 SvcName = diameter:service_name()
77 Peer = peer()
78 State = NewState = state()
79 Invoked to signal the availability of a peer connection on the
81 local Erlang node. In particular, capabilities exchange with the
82 peer has indicated support for the application in question, the
83 RFC 3539 watchdog state machine for the connection has reached
84 state OKAY and Diameter messages can be both sent and received.
85 Note:
87 A watchdog state machine can reach state OKAY from state SUSPECT
88 without a new capabilities exchange taking place. A new trans‐
89 port connection (and capabilities exchange) results in a new
90 peer_ref().
91 Note:
94 There is no requirement that a callback return before incoming
95 requests are received: handle_request/3 callbacks must be han‐
96 dled independently of peer_up/3 and peer_down/3.
97 Mod:peer_down(SvcName, Peer, State) -> NewState
100 Types:
102 SvcName = diameter:service_name()
104 Peer = peer()
105 State = NewState = state()
106 Invoked to signal that a peer connection on the local Erlang
108 node is no longer available following a previous call to
109 peer_up/3. In particular, that the RFC 3539 watchdog state ma‐
110 chine for the connection has left state OKAY and the peer will
111 no longer be a candidate in pick_peer/4 callbacks.
112 Mod:pick_peer(LocalCandidates, RemoteCandidates, SvcName, State) -> Se‐
114 lection | false
115 Types:
117 LocalCandidates = RemoteCandidates = [peer()]
119 SvcName = diameter:service_name()
120 State = NewState = state()
121 Selection = {ok, Peer} | {Peer, NewState}
122 Peer = peer() | false
123 Invoked as a consequence of a call to diameter:call/4 to select
125 a destination peer for an outgoing request. The return value in‐
126 dicates the selected peer.
127 The candidate lists contain only those peers that have adver‐
129 tised support for the Diameter application in question during
130 capabilities exchange, that have not be excluded by a filter op‐
131 tion in the call to diameter:call/4 and whose watchdog state ma‐
132 chine is in the OKAY state. The order of the elements is unspec‐
133 ified except that any peers whose Origin-Host and Origin-Realm
134 matches that of the outgoing request (in the sense of a {filter,
135 {all, [host, realm]}} option to diameter:call/4) will be placed
136 at the head of the list. LocalCandidates contains peers whose
137 transport process resides on the local Erlang node while Remote‐
138 Candidates contains peers that have been communicated from other
139 nodes by services of the same name.
140 A callback that returns a peer() will be followed by a pre‐
142 pare_request/3 callback and, if the latter indicates that the
143 request should be sent, by either handle_answer/4 or handle_er‐
144 ror/4 depending on whether or not an answer message is received
145 from the peer. If the transport becomes unavailable after pre‐
146 pare_request/3 then a new pick_peer/4 callback may take place to
147 failover to an alternate peer, after which prepare_retransmit/3
148 takes the place of prepare_request/3 in resending the request.
149 There is no guarantee that a pick_peer/4 callback to select an
150 alternate peer will be followed by any additional callbacks
151 since a retransmission to an alternate peer is abandoned if an
152 answer is received from a previously selected peer.
153 The return values false and {false, State} (that is, NewState =
155 State) are equivalent, as are {ok, Peer} and {Peer, State}.
156 Note:
158 The diameter:service_opt() use_shared_peers determines whether
159 or not a service uses peers shared from other nodes. If not then
160 RemoteCandidates is the empty list.
161 Warning:
164 The return value {Peer, NewState} is only allowed if the Diame‐
165 ter application in question was configured with the diameter:ap‐
166 plication_opt() {call_mutates_state, true}. Otherwise, the State
167 argument is always the initial value as configured on the appli‐
168 cation, not any subsequent value returned by a peer_up/3 or
169 peer_down/3 callback.
170 Mod:prepare_request(Packet, SvcName, Peer) -> Action
173 Types:
175 Packet = packet()
177 SvcName = diameter:service_name()
178 Peer = peer()
179 Action = Send | Discard | {eval_packet, Action, PostF}
180 Send = {send, packet() | message()}
181 Discard = {discard, Reason} | discard
182 PostF = diameter:eval()}
183 Invoked to return a request for encoding and transport. Allows
185 the sender to use the selected peer's capabilities to modify the
186 outgoing request. Many implementations may simply want to return
187 {send, Packet}
188 A returned packet() should set the request to be encoded in its
190 msg field and can set the transport_data field in order to pass
191 information to the transport process. Extra arguments passed to
192 diameter:call/4 can be used to communicate transport (or any
193 other) data to the callback.
194 A returned packet() can set the header field to a #diame‐
196 ter_header{} to specify values that should be preserved in the
197 outgoing request, values otherwise being those in the header
198 record contained in Packet. A returned length, cmd_code or ap‐
199 plication_id is ignored.
200 A returned PostF will be evaluated on any encoded #diame‐
202 ter_packet{} prior to transmission, the bin field containing the
203 encoded binary. The return value is ignored.
204 Returning {discard, Reason} causes the request to be aborted and
206 the diameter:call/4 for which the callback has taken place to
207 return {error, Reason}. Returning discard is equivalent to re‐
208 turning {discard, discarded}.
209 Mod:prepare_retransmit(Packet, SvcName, Peer) -> Action
211 Types:
213 Packet = packet()
215 SvcName = diameter:service_name()
216 Peer = peer()
217 Action = Send | Discard | {eval_packet, Action, PostF}
218 Send = {send, packet() | message()}
219 Discard = {discard, Reason} | discard
220 PostF = diameter:eval()}
221 Invoked to return a request for encoding and retransmission. Has
223 the same role as prepare_request/3 in the case that a peer con‐
224 nection is lost an an alternate peer selected but the argument
225 packet() is as returned by the initial prepare_request/3.
226 Returning {discard, Reason} causes the request to be aborted and
228 a handle_error/4 callback to take place with Reason as initial
229 argument. Returning discard is equivalent to returning {discard,
230 discarded}.
231 Mod:handle_answer(Packet, Request, SvcName, Peer) -> Result
233 Types:
235 Packet = packet()
237 Request = message()
238 SvcName = diameter:service_name()
239 Peer = peer()
240 Result = term()
241 Invoked when an answer message is received from a peer. The re‐
243 turn value is returned from diameter:call/4 unless the detach
244 option was specified.
245 The decoded answer record and undecoded binary are in the msg
247 and bin fields of the argument packet() respectively. Request is
248 the outgoing request message as was returned from prepare_re‐
249 quest/3 or prepare_retransmit/3.
250 For any given call to diameter:call/4 there is at most one han‐
252 dle_answer/4 callback: any duplicate answer (due to retransmis‐
253 sion or otherwise) is discarded. Similarly, only one of han‐
254 dle_answer/4 or handle_error/4 is called.
255 By default, an incoming answer message that cannot be success‐
257 fully decoded causes the request process to fail, causing diame‐
258 ter:call/4 to return {error, failure} unless the detach option
259 was specified. In particular, there is no handle_error/4 call‐
260 back in this case. The diameter:application_opt() answer_errors
261 can be set to change this behaviour.
262 Mod:handle_error(Reason, Request, SvcName, Peer) -> Result
264 Types:
266 Reason = timeout | failover | term()
268 Request = message()
269 SvcName = diameter:service_name()
270 Peer = peer()
271 Result = term()
272 Invoked when an error occurs before an answer message is re‐
274 ceived in response to an outgoing request. The return value is
275 returned from diameter:call/4 unless the detach option was spec‐
276 ified.
277 Reason timeout indicates that an answer message has not been re‐
279 ceived within the time specified with the corresponding diame‐
280 ter:call_opt(). Reason failover indicates that the transport
281 connection to the peer to which the request has been sent has
282 become unavailable and that not alternate peer was not selected.
283 Mod:handle_request(Packet, SvcName, Peer) -> Action
285 Types:
287 Packet = packet()
289 SvcName = term()
290 Peer = peer()
291 Action = Reply | {relay, [Opt]} | discard |
292 {eval|eval_packet, Action, PostF}
293 Reply = {reply, packet() | message()} | {answer_message,
294 3000..3999|5000..5999} | {protocol_error, 3000..3999}
295 Opt = diameter:call_opt()
296 PostF = diameter:eval()
297 Invoked when a request message is received from a peer. The ap‐
299 plication in which the callback takes place (that is, the call‐
300 back module as configured with diameter:start_service/2) is de‐
301 termined by the Application Identifier in the header of the in‐
302 coming request message, the selected module being the one whose
303 corresponding dictionary declares itself as defining either the
304 application in question or the Relay application.
305 The argument packet() has the following signature.
307 #diameter_packet{header = #diameter_header{},
309 avps = [#diameter_avp{}],
310 msg = record() | undefined,
311 errors = [Unsigned32() | {Unsigned32(), #diameter_avp{}}],
312 bin = binary(),
313 transport_data = term()}
314 The msg field will be undefined in case the request has been re‐
317 ceived in the relay application. Otherwise it contains the
318 record representing the request as outlined in diameter_dict(4).
319 The errors field specifies any results codes identifying errors
321 found while decoding the request. This is used to set Result-
322 Code and/or Failed-AVP in a returned answer unless the callback
323 returns a #diameter_packet{} whose errors field is set to either
324 a non-empty list of its own, in which case this list is used in‐
325 stead, or the atom false to disable any setting of Result-Code
326 and Failed-AVP. Note that the errors detected by diameter are of
327 the 3xxx and 5xxx series, Protocol Errors and Permanent Failures
328 respectively. The errors list is empty if the request has been
329 received in the relay application.
330 The transport_data field contains an arbitrary term passed into
332 diameter from the transport module in question, or the atom un‐
333 defined if the transport specified no data. The term is pre‐
334 served if a message() is returned but must be set explicitly in
335 a returned packet().
336 The semantics of each of the possible return values are as fol‐
338 lows.
339 {reply, packet() | message()}:
341 Send the specified answer message to the peer. In the case
342 of a packet(), the message to be sent must be set in the msg
343 field and the header field can be set to a #diame‐
344 ter_header{} to specify values that should be preserved in
345 the outgoing answer, appropriate values otherwise being set
346 by diameter.
347 {answer_message, 3000..3999|5000..5999}:
349 Send an answer message to the peer containing the specified
350 Result-Code. Equivalent to
351 {reply, ['answer-message' | Avps]
353 where Avps sets the Origin-Host, Origin-Realm, the specified
356 Result-Code and (if the request contained one) Session-Id
357 AVPs, and possibly Failed-AVP as described below.
358 Returning a value other than 3xxx or 5xxx will cause the re‐
360 quest process in question to fail, as will returning a 5xxx
361 value if the peer connection in question has been configured
362 with the RFC 3588 common dictionary diame‐
363 ter_gen_base_rfc3588. (Since RFC 3588 only allows 3xxx val‐
364 ues in an answer-message.)
365 When returning 5xxx, Failed-AVP will be populated with the
367 AVP of the first matching Result-Code/AVP pair in the errors
368 field of the argument packet(), if found. If this is not ap‐
369 propriate then an answer-message should be constructed ex‐
370 plicitly and returned in a reply tuple instead.
371 {relay, Opts}:
373 Relay a request to another peer in the role of a Diameter
374 relay agent. If a routing loop is detected then the request
375 is answered with 3005 (DIAMETER_LOOP_DETECTED). Otherwise a
376 Route-Record AVP (containing the sending peer's Origin-Host)
377 is added to the request and pick_peer/4 and subsequent call‐
378 backs take place just as if diameter:call/4 had been called
379 explicitly. The End-to-End Identifier of the incoming re‐
380 quest is preserved in the header of the relayed request.
381 The returned Opts should not specify detach. A subsequent
383 handle_answer/4 callback for the relayed request must return
384 its first argument, the packet() containing the answer mes‐
385 sage. Note that the extra option can be specified to supply
386 arguments that can distinguish the relay case from others if
387 so desired. Any other return value (for example, from a han‐
388 dle_error/4 callback) causes the request to be answered with
389 3002 (DIAMETER_UNABLE_TO_DELIVER).
390 discard:
392 Discard the request. No answer message is sent to the peer.
393 {eval, Action, PostF}:
395 Handle the request as if Action has been returned and then
396 evaluate PostF in the request process. The return value is
397 ignored.
398 {eval_packet, Action, PostF}:
400 Like eval but evaluate PostF on any encoded #diame‐
401 ter_packet{} prior to transmission, the bin field containing
402 the encoded binary. The return value is ignored.
403 {protocol_error, 3000..3999}:
405 Equivalent to {answer_message, 3000..3999}.
406 Note:
408 Requests containing errors may be answered by diameter, without
409 a callback taking place, depending on the value of the diame‐
410 ter:application_opt() request_errors.
411Ericsson AB diameter 2.2.5 diameter_app(3)