Application

API reference for diameter.node.application.

Diameter application implementations.

Instances of Applications, or their subclasses, provided by this module can be passed directly to an instance of a Node, for receiving and sending diameter application messages.

In most cases, the most suitable option to use is SimpleThreadingApplication, which will cover the most scenarios without requiring any unnecessary setup.

Application ¶

Application(
    application_id: int = None,
    is_acct_application: bool = False,
    is_auth_application: bool = False,
)

A basic diameter application that can be registered with a Node.

Can be used as a starting point for building applications with custom logic. In most cases, SimpleThreadingApplication and ThreadingApplication are more practical.

Parameters:

Name	Type	Description	Default
`application_id`	`int`	Authentication application ID	`None`
`is_acct_application`	`bool`	Flag the application as an accounting app	`False`
`is_auth_application`	`bool`	Flag the application as an authorisation app	`False`

generate_answer ¶

generate_answer(
    message: _AnyMessageType,
    result_code: int = None,
    error_message: str = None,
) -> _AnyAnswerType

Produce an answer message from a request message.

Calls Message.to_answer and adds origin host, origin realm, session id and application IDs automatically.

Parameters:

Name	Type	Description	Default
`message`	`_AnyMessageType`	Any diameter message with a python implementation, accepting AVPs as instance attributes	required
`result_code`	`int`	An optional result code to add to the answer	`None`
`error_message`	`str`	An optional error message to add to the answer	`None`

handle_answer ¶

handle_answer(message: Message)

Called every time an unexpected answer message is received.

Normally, answers are returned directly as the return values of send_request; overriding this method is not strictly required. It is called every time an answer is received, with nobody expecting one. This could happen e.g. when the answer wait timeout has been exceeded. By default, this method does nothing and only discards every unexpected message.

Warning

This method is called in the main thread; its execution blocks the diameter Node from processing any incoming or outgoing messages. The implementing party is expected to utilise a message queue and do the work in a separate thread.

handle_request ¶

handle_request(message: Message)

Called every time a request message is received.

The parent diameter node does not check or expect this method to return anyhing; the application is expected to send its answer messages back towards the network by using the send_message method.

Warning

This method is called in the main thread; its execution blocks the diameter Node from processing any incoming or outgoing messages. The implementing party is expected to utilise a message queue and do the work in a separate thread. Alternatively, the ThreadingApplication can be used, which spawns a new thread for every request.

send_answer ¶

send_answer(message: Message)

Send an answer message.

Routes the message directly to the parent diameter node, where it will be forwarded through the network to the appropriate peer. The application ID, hop-by-hop identifier and end-to-end identifiers must already be set (copied from the original request).

Parameters:

Name	Type	Description	Default
`message`	`Message`	A diameter message to send	required

The method will return nothing; it returns immediately without waiting for any results from the network.

send_request ¶

send_request(message: Message, timeout: int = 30) -> Message

Send a request message.

Routes the message directly to the parent diameter node, where it will be forwarded through the network to the appropriate peer. The header application ID and end-to-end hop identifiers are set automatically, if not already present.

The hop-by-hop identifier will be set by the node, if the message can be routed to a peer and if the identifier is not already present.

Parameters:

Name	Type	Description	Default
`message`	`Message`	A diameter message to send	required
`timeout`	`int`	A timeout in seconds to wait for an answer	`30`

Returns:

Type	Description
`Message`	A diameter answer message, if one was received within the timeout seconds, otherwise `None`. If the sent message was not a request, returns `None` immediately without waiting.

wait_for_ready ¶

wait_for_ready(timeout: int = 30)

Wait for application connectivity to become ready.

Waits until at least one of the peers specified for the application has completed its CER/CEA procedure and become ready to accept requests. If all the configured peers for the application become again disconnected, wait_for_ready will block again, until at least one of the peers has returned and completed their CER/CEA.

Note

This method can be called every time before send_request is to be used, for increased certainty that a request will go through, however it will not guarantee that a peer will not go offline between calling this method and sending the request.

Parameters:

Name	Type	Description	Default
`timeout`	`int`	Amount of time to wait, in seconds	`30`

Raises:

Type	Description
`ApplicationError`	If no peer becomes available before timeout

ApplicationError ¶

Bases: Exception

Base error class for all Application-raised errors.

EmptyAnswer ¶

Bases: ApplicationError

An error received when a diameter peer fails to respond.

RequestTimeout ¶

Bases: ApplicationError

An error received when no answer is received within a given timeout.

SimpleThreadingApplication ¶

SimpleThreadingApplication(
    application_id: int = None,
    is_acct_application: bool = False,
    is_auth_application: bool = False,
    max_threads: int = 0,
    request_handler: Callable = None,
)

Bases: ThreadingApplication

A diameter application that starts a thread for each request.

An alternative to the base threading application, that does not require subclassing or overwriting. The implementing party should pass a callback function in the request_handler argument. The application will call the passed function for every received request in a separate thread, passing an instance of the app itself and the message to handle as arguments.

If the application acts as a client only and never expects any requests, the callback function is optional.

from diameter.node.application import SimpleThreadingApplication
from diameter.message import constants

def handle_request(app: Application, message: Message):
    print("Got", message)
    answer = app.generate_answer(message)
    return answer

app = SimpleThreadingApplication(
    constants.APP_DIAMETER_BASE_ACCOUNTING,
    is_acct_application=True,
    request_handler=handle_request)

Parameters:

Name	Type	Description	Default
`application_id`	`int`	Authentication application ID	`None`
`is_acct_application`	`bool`	Flag the application as an accounting app	`False`
`is_auth_application`	`bool`	Flag the application as an authorisation app	`False`
`max_threads`	`int`	Maximum threads to start simultaneously for processing messages. When maximum thread count is reached, the application does not handle any further messages, until at least one of the already started threads has exited. If set to 0, the amount of threads to spawn is unlimited.	`0`
`request_handler`	`Callable`	Any callable that will be called whenever a request is received. It will receive an instance of the app and request message as its arguments and is expected to return an answer message	`None`

ThreadingApplication ¶

ThreadingApplication(
    application_id: int = None,
    is_acct_application: bool = False,
    is_auth_application: bool = False,
    max_threads: int = 0,
)

Bases: Application

A diameter application that starts a thread for each request.

An alternative to the base application, where each message received by the diameter node is handled in a separate thread. The implementing party should override the handle_request method and do the message processing work within, returning a new answer.

Parameters:

Name	Type	Description	Default
`application_id`	`int`	Authentication application ID	`None`
`is_acct_application`	`bool`	Flag the application as an accounting app	`False`
`is_auth_application`	`bool`	Flag the application as an authorisation app	`False`
`max_threads`	`int`	Maximum threads to start simultaneously for processing messages. When maximum thread count is reached, the application does not handle any further messages, until at least one of the already started threads has exited. If set to 0, the amount of threads to spawn is unlimited.	`0`

handle_request ¶

handle_request(message: Message) -> Message | None

Called by diameter node every time a request message is received.

Unlike the base Application version of this same method, the handle_request is expected to return an answer, either None or a valid diameter Message. The return value of the method is sent automatically back towards the network. Any exceptions raised by the method are caught and result in a DIAMETER_UNABLE_TO_COMPLY result being returned to the network.