Diameter Lua Agent

Introduction

The DiameterLuaAgent is an asynchronous helper for Lua scripts running within the LogicApp. It is used for sending out Diameter client requests.

• The Diameter Agent may be used by any Lua script, regardless of which Service initiated that script.

The DiameterLuaAgent communicates with one or more instances of the DiameterApp which can be used to communicate with one or more external Diameter servers.

The DiameterLuaAgent communicates with the DiameterApp using the DIAMETER-C-… messages.

Diameter Agent API methods are accessed via the “n2.n2svcd.diameter_agent” module:

local diameter_agent = require "n2.n2svcd.diameter_agent"

Configuring DiameterLuaAgent

The DiameterLuaAgent is configured within a LogicApp.

    <?xml version="1.0" encoding="utf-8"?>
    <n2svcd>
      ...
      <applications>
        ...
        <application name="Logic" module="LogicApp">
          <include>
            <lib>../apps/logic/lib</lib>
          </include>
          <parameters>
            ...
            <parameter name="default_diameter_app_name" value="DIAMETER-CLIENT"/>
            <parameter name="diameter_app_name_sms" value="DIAMETER-CLIENT-SMS"/>
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="DiameterApp::DiameterLuaAgent" libs="../apps/diameter/lib"/>
            </agents>
          </config>
        </application>
        ...
      </applications>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

In addition, the DiameterLuaAgent must be configured with the name of the DiameterApp with which it will communicate. This is configured within the parameters of the containing LogicApp.

The DiameterLuaAgent API

All methods may raise a Lua Error in the case of exception, including:

• Invalid input parameters supplied by Lua script.
• Unexpected results structure returned from DiameterApp.
• Processing error occurred at DiameterApp.
• Timeout occurred at DiameterApp.

.session_id [Synchronous]

The session_id method returns an auto-incremented unique Session-ID for a Diameter request.

This is the same Session ID as would be assigned internally by the .request_response method, except that this method allows you to know it in advance of making the call to .request_response which could be useful for debugging/tracing, for writing to a database, or for generating an EDR record prior to sending the request.

The following parameters are accepted.

The method returns a String scalar value.

Example:

local n2svcd = require "n2.n2svcd"
local diameter_agent = require "n2.n2svcd.diameter_agent"

local soap_args = ...

local session_id = diameter_agent.session_id ()

.request_response [Asynchronous]

The request_response method sends a Diameter request, and returns the response. The following parameters are accepted.

The request_response method returns a Diameter response object with the following fields.

Example (Diameter Client Request - Combined):

local avps = {
    { name = "Service-Context-Id", value = "sms@huawei.com" },
    { name = "CC-Request-Type", value = 1 },
    { name = "CC-Request-Number", value = 1 },
    { name = "Rating-Group", value = 900 },
    { name = "Requested-Action", value = 0 },
    { name = "Requested-Service-Unit",
        value = { { name = "CC-Service-Specific-Units", value = 1 } },
        vendor_specific = 0
    },
    { name = "Service-Identifier", value = 200 },
    { name = "Subscription-Id",
        value = {
            { name = "Subscription-Id-Data", value = "64220635462" },
            { name = "Subscription-Id-Type", value = 0 }
        }
    },
    { name = "Custom-1", value = 789 }
}

local result = diameter_agent.request_response ('sms', 'Credit-Control-Request', avps, true, 3.5)

The above example shows a LogicApp script invoked by an arbitrary service.

Note that the decoded .avps array will contain all fields, i.e. the [].name and [].code and [].type and [].mandatory, etc. will all be present.

The only exception will be when decoding AVPs which are not part of the core fields defined within N2::DIAMETER::Codec and are not defined as custom AVPs in the configuration for DiameterApp. In these cases, the [].name and [].type AVP attributes will not be present, and the [].value will be the raw undecoded bytes of the AVP value without any interpretation.

.send_request [Synchronous]

The send_request method sends a Diameter request but does not wait for the response.

The send_request method returns an Lua number which is an (integer) sequence_num which must be used to query the progress or return the response if and when it arrives. It is possible to have more than one Diameter request active at any time.

The send_request method returns two values.

.expect_response [Asynchronous]

The expect_response method waits for the response to a Diameter request that was previously sent with the send_request method.

The method takes a single parameter.

The return structure is identical to the request_response method.

The expect_response method will wait until the specified timeout in seconds as provided (or defaulted) in the original call to send_request. The timeout is measured from the time of the original call to send_request.

If the response (or notification of failure) has been received at the time of the call to expect_response then it will be returned, even if the timeout in seconds from sending has in fact been reached or exceeded.

Note that you may call expect_response more than once for the same sequence number. Once a result is returned, subsequent calls will provide exactly the same result and have no other effect.

Example (Diameter Client Request - Send and Expect):

local avps = {
    { name = "Service-Context-Id", value = "sms@huawei.com" },
    { name = "CC-Request-Type", value = 1 },
    { name = "CC-Request-Number", value = 1 },
    { name = "Rating-Group", value = 900 },
    { name = "Requested-Action", value = 0 },
    { name = "Requested-Service-Unit",
        value = { { name = "CC-Service-Specific-Units", value = 1 } },
        vendor_specific = 0
    },
    { name = "Service-Identifier", value = 200 },
    { name = "Subscription-Id",
        value = {
            { name = "Subscription-Id-Data", value = "64220635462" },
            { name = "Subscription-Id-Type", value = 0 }
        }
    },
    { name = "Custom-1", value = 789 }
}

local ccr_seqnum = diameter_agent.send_request (nil, 'Credit-Control-Request', avps, true)

-- Illustrates use of the "progress" method.
local progress = n2svcd.progress (2.0)
if (not progress.diameter) then
    error ("Progress from unexpected source (not Diameter)."
end

local ccr_result = diameter_agent.expect_response (ccr_seqnum)

The progress method is useful when a script potentially might receive action responses from two different sources and it is not guaranteed which one will arrive first.

.check_response [Asynchronous]

The check_response method checks to see if a response (or a failure) has been received for a sent request.

The method takes a single parameter.

The method returns two boolean values.

Example (Checking Two Responses):

local ccr_seqnum1 = diameter_agent.send_request ("app1", 'Credit-Control-Request', {}, true)
local ccr_seqnum2 = diameter_agent.send_request ("app2", 'Credit-Control-Request', {}, true)

-- Wait 5 seconds for some Diameter action.
local progress = n2svcd.progress (5)
if (not progress.diameter) then error ("Progress from unexpected source (not Diameter)." end

-- Get the first response that arrived.
local result1
local result2
if (diameter_agent.check_response (ccr_seqnum1)) then
    result1 = diameter_agent.expect_response (ccr_seqnum1)

else if (diameter_agent.check_response (ccr_seqnum2)) then
    result2 = diameter_agent.expect_response (ccr_seqnum2)
end

-- Wait 5 seconds for the second response Diameter action.
local progress = n2svcd.progress (5)
if (not progress.diameter) then error ("Progress from unexpected source (not Diameter)." end

-- Get the "other" response.
if (diameter_agent.check_response (ccr_seqnum1)) then
    result1 = diameter_agent.expect_response (ccr_seqnum1)
    
else if (diameter_agent.check_response (ccr_seqnum2)) then
    result2 = diameter_agent.expect_response (ccr_seqnum2)
end

.register_session [Asynchronous]

The register_session method requests the DiameterApp to pass DIAMETER-S-REQUEST messages for the specified Diameter Session-ID through to this Lua script execution.

The method takes two parameters.

This method returns a number lifetime which is the granted lifetime of the registration.
This lifetime may be less than the originally requested lifetime.

.deregister_session [Asynchronous]

The deregister_session method deregisters a previously registered session.

In general this is not required, since the registration will be automatically deregistered when the script ends.

The method takes a single parameter.

This method returns nil.

.expect_request [Asynchronous]

The expect_request method waits for an inbound Diameter request to arrive on the indicated session ID which was previously registered. If one or more requests are already present on the inbound queue, the earliest request is returned immediately.

The method takes two parameters.

The return structure is identical to the request_response method except that the message name will be an Answer message not a Request message name.

Note that the message will stay at the front of the queue until you reply to this message. If you call expect_request again before calling send_response then you will get the repeated request.

Once the response has been sent, subsequent calls to expect_request will return the next inbound request on that session, if any.

The n2svcd.progress () method will return if an inbound Diameter request arrives for a registered session ID.

.count_requests [Synchronous]

The count_requests method returns a count of the number of received and not yet responded inbound requests in the queue associated with the registered Session-ID.

The method takes one parameter.

.send_response [Synchronous]

The send_response method replies to the most recent inbound request for the indicated registered Session ID. That request is then removed from the queue.

The method takes two parameters.

.get_first_instance_of_avp [Synchronous]

The get_first_instance_of_avp method searches an array of AVPs, returning the first AVP with name matching a specified name. The following parameters are accepted.

If a matching AVP is found, the get_first_instance_of_avp method returns an avp object with the following fields.

.get_first_value_of_avp [Synchronous]

The get_first_value_of_avp method searches an array of AVPs, returning the value of the first AVP with name matching a specified name. The following parameters are accepted.

If a matching AVP is found, the get_first_value_of_avp method returns that AVP’s value. For AVPs of type Grouped this will be an ARRAY of AVPs. For all other AVPs this is a SCALAR of the appropriate type.

.get_all_instances_of_avp [Synchronous]

The get_all_instances_of_avp method searches an array of AVPs, returning all AVPs with name matching a specified name. The following parameters are accepted.

If at least one matching AVP is found, the get_all_instances_of_avp method returns an array of AVPs as per get_first_instance_of_avp. Otherwise an empty array is returned.

Built-In N2::Diameter::Codec Commands

The following list of Command names is built-in to the N2::Diameter::Codec encoding and decoding library. Commands not in this list may be referenced by numeric code, although they will not have support for setting special flags, or for changing the Diameter Application ID.

Built-In N2::Diameter::Codec AVPs

The following list of AVPs is built-in to the N2::Diameter::Codec encoding and decoding library. Additional custom AVPs may be added as necessary on a per-site basis by using configuration in the DiameterApp.