Custom Messaging
Introduction
With the JSLEE scripting engine it is possible to develop and run custom processing logic when proxying Diameter requests/answer messages through a Diameter Gateway.
Incoming Diameter requests received by a Diameter Gateway (where the gateway is configured as a server) may be proxied directly out again, or passed through a secondary service (such as a Lua extension).
Incoming Diameter answer messages follow the same path backwards, such that they can be manipulated by the same processing logic as well.
JSLEE services (including scripted services) may generate Diameter requests and also be the destination for incoming diameter messages. In all cases, the API described herein is used to send messages across the JSLEE.
Sending Diameter Requests
Sending Diameter requests is done by sending a DiameterMessageEvent
over the JSLEE event bus to a Diameter service configured with
either client endpoints, or if a ReAuthRequest is being sent,
a server endpoint.
Receiving Diameter Requests
Incoming Diameter messages will themselves be sent by a Diameter
server service in a DiameterMessageEvent event. From this event,
the internal DiameterMessage and associated AVPs can be extracted,
altered and then proxied (if required) using a new DiameterMessageEvent
object.
DiameterMessageEvent API
The simplest interface to send Diameter requests requires only
a DiameterMessageEvent with no communication-specific AVPs.
A Lua service might, for example, create and send a diameter request using code similar to:
local targetEndpoint = "diameter-out/ocs"
local msg = JSLEE.createJavaObject ("nz.co.nsquared.slee.protocol.diameter.message.DiameterMessage");
-- add message AVPs
local event = JSLEE.createEvent ("nz.co.nsquared.slee.diameter.DiameterMessageEvent", "1", msg)
ok, result = JSLEE.send(targetEndpoint, event)
When creating a Diameter message, the message will consist of both the Diameter header, and message AVPs.
Diameter message header fields have the following requirements:
| Header Field | Value Required | Notes |
|---|---|---|
| Version | No | Defaults to 1, matching RFC 6733. Should not be set to another value. |
| Message Length | No | Calculated internally. Should never be set manually. |
| Command Flags | No | The defaults (Request, Proxyable, not Erro, not reTransmitted) are generally sufficient, but may be altered if appropriate. |
| Command Code | Yes | The message command must be given when creating the message. This needs to always be set by the source of the message. |
| Application ID | Yes | The application ID must be defined. Normally this should be set to 4 and is used to determine if the message can be sent to a connected peer. |
| End-to-End ID | Optional | If set to a non-zero value, the service endpoint sending the message out will not set their own end-to-end ID. It may be set to 0 to have the Diameter service set this to an appropriate value. |
| Hop-by-Hop ID | No | The hop-by-hop ID is always reset by the outgoing endpoint so that it can be set to the appropriate ID for the peer connection maintained by the endpoint. |
Where a Diameter message includes a non-zero end-to-end ID, the sending endpoint will not alter it. This allows the end-to-end ID to be maintained across service boundaries and create a transaction-level tracing ID. However note that if the Diameter service itself is not setting the end-to-end ID in one case, it should not generally be asked to set it in any case.
However the hop-by-hop ID is always set to the next value appropriate for the peer connection the message is sent on by the endpoint. If this value is non-zero it is overwritten.
Most Diameter AVPs included in a Diameter message are application-specific and are not altered (or analysed) by the sending Diameter Service.
However, some AVPs are intrinsic to the Diameter protocol (particularly in routing) and these are injected where required into outgoing messages sent. They are also used to determine the appropriate Diameter peer to send messages to.
The following AVPs are used in Diameter message routing:
| AVP | Value Required | Notes |
|---|---|---|
Session-ID |
Yes | For messages where a session ID is appropriate (or required), the Session-ID must be defined before being sent to the Diameter service. The Diameter service will never generate a Session ID itself for a message. |
Origin-Realm |
Optional | If not specified in the AVP list, the Origin-Realm AVP will be added based on the outgoing endpoint configuration. In practice this should be equivalent to the outgoing JSLEE endpoint configuration, unless the message is being proxied or relayed. |
Origin-Host |
Optional | If not specified in the AVP list, the Origin-Host AVP will be added based on the outgoing endpoint configuration. In practice this should be equivalent to the outgoing JSLEE endpoint configuration, unless the message is being proxied or relayed. |
Origin-State-ID |
Optional | For services which manage sessions and wish to publish an Origin-State-ID to allow peers to determine when session termination has occurred due to shutdown, the field must be added by the service. It is not added by the sending endpoint. |
Destination-Realm |
Yes | The Destination-Realm AVP is required to determine the correct peer to send the request to. Without this a service endpoint with multiple realms connected would not be able to determine the correct realm. The JSLEE will not default to a destination realm if one is not specified. |
Destination-Host |
Optional | The Destination-Host is not required, however may be included if appropriate. When specified, will be used to determine the peer to send the message too, and if the Diameter-Host is not a direct peer, the request will not be sent. |
| routing AVPs | Optional | Routing AVPs, including Route-Record, Proxy-Info, Proxy-Host and Proxy-State may be included if appropriate for the service being provided. These are not added by the sending Diameter service (however note that these are added by the Diameter Agent application, which is run on the Diameter Server service). |
Event-Timestamp |
Yes | For messages where an event timestamp is appropriate (or required), the timestamp must be defined before being sent to the service endpoint sending the message out. It is not added by the Diameter service which is sending the message. |
Receiving Diameter Messages
Diameter messages received over the JSLEE event bus from the Diameter Gateway
(whether Agent, or Credit-Control Server) will be received as DiameterMessageEvent
objects.
The DiameterMessageEvent will contain the original Diameter Message AVPs,
potentially adjusted by the incoming Diameter agent or credit-control server
Application.
When a Diameter Agent receives and forwards on a Diameter message, it will
add proxy AVPs, and potentially alter other AVPs (particularly the Destination-Realm
AVP). Most AVPs however are left intact.
In addition to the Diameter message itself, the following are received in the event as additional auxiliary data:
| Field | Description |
|---|---|
| Origin Host | The Origin-Host of the peer from which the message was recieved. This may not be consistent with the Origin-Host in the message if the message was received through a relay. This should not be used as the destination host of the answer (that should come from the message itself). |
| Origin Realm | The Origin-Realm of the peer from which the message was received. This may not be consistent with the Origin-Realm in the message if the message was received through a relay. This should not be used as the destination realm of the answer (that should come from the message itself). |
| Destination Host | The Destination-Host of our local peer endpoint - i.e. the endpoint that received the message. This should be used as the Origin-Host of the message, if the message is being processed by the JSLEE service receiving the message. |
| Destination Realm | The Destination-Realm of our local peer endpoint - i.e. the endpoint that received the message. |
| Origin State ID | The value of the Origin-State-ID of the peer from which the message was received, if one is known (i.e. if one has been given). This will be 0 if no such ID has been provided. |
| Destination State ID | The value of the Origin-State-ID of our peer, to be used when answering the message (i.e. for injecting as the Origin-State-ID. This will be non-zero if an origin state ID is able to be provided by the receiving endpoint (i.e. credit-control server), but will be 0 for endpoint applications without session management (e.g. the Diameter Agent, configured without session management). |
It is the responsibility of the software generating the answer message to use the origin details appropriate for their purposes (whether that is from the message AVPs, or from the message itself). Unless the message is being relayed (and hence the answer is relayed back), then it is generally appropriate to use the auxiliary information. However if the JSLEE service must pretend to be the originally targeted service this rule may require bending.