Application-Specific Implementations

In the Diameter protocol architecture, Application-Specific Components handle the specific needs of various Diameter applications. These components allow the core stack to adapt to the requirements of different network interfaces, such as Credit Control (CCA), Cx/Dx, E4, Gx, and many more, enabling it to manage distinct protocols, state machines, and message flows specific to each application. 
The structure of these components ensures modularity and scalability, allowing developers to easily extend and customize the Diameter stack for different telecom use cases, including billing systems, policy control, authentication, and service management.

Key Principles

Modular Design
The components are organized in a modular fashion, where each application is implemented as a separate package. This structure ensures that the logic and processing rules for each application are encapsulated, avoiding dependencies between different application modules. Application-Specific components include session management, message creation, attribute-value pair (AVP) handling, and protocol state management, all grouped within their respective packages.
Session-Centric Architecture
Each application package centers around managing Diameter sessions. Sessions are the core units of communication between two Diameter peers, representing ongoing interactions. Application-specific sessions differ based on the application requirements. For example, some applications require stateful sessions (where the server maintains session state), while others are stateless (where the server does not retain session data between requests).
Role Separation Between Client and Server
Each application implements logic for both client-side and server-side interactions through distinct ClientSession and ServerSession classes. These sessions encapsulate the application-specific state machines, message flows, and protocols required for managing client and server behavior in the Diameter network. For instance, the Credit Control Application (CCA) has dedicated sessions to manage the lifecycle of charging requests from clients and responses from servers.
Dynamic Session Creation via Session Factories
SessionFactory is responsible for dynamically creating new session instances based on incoming requests. These session factories abstract the session creation logic, allowing different applications to implement session management tailored to their protocol's needs, whether for credit control, authentication, or policy control.
Message and AVP Handling
Each application package contains a MessageFactory responsible for creating Diameter messages specific to the application. These message factories generate requests and responses, handling AVPs (Attribute-Value Pairs) essential to the application logic.
AVPs are key-value pairs used in Diameter messages to convey information. Each application has its own set of required and optional AVPs, managed by the AvpFactory. This component ensures the correct AVPs are created, parsed, and validated as per the application's protocol specifications.
Provider Implementation for Application Management
The Provider component for each application serves as the main interface between the core Diameter stack and the application-specific logic. Providers handle tasks like routing Diameter messages, initiating sessions, and ensuring the correct state machine is followed.
Application-Specific Providers extend a common base provider class that defines shared behavior, such as listener management, session retrieval, and error handling. This design allows for consistency across different applications while providing the flexibility to implement specific behaviors for each application.

Application-Specific Structure

The structure of the application-specific components is designed to achieve several goals:
Protocol Compliance: Each application follows the specific Diameter protocol rules and standards set by IETF RFCs. The modular structure ensures that the Diameter stack adheres to these standards while being adaptable to different use cases.
Scalability and Extensibility: The separation of components into different packages allows developers to extend the Diameter stack easily by adding new applications or modifying existing ones. This structure enables telecom networks to scale and handle complex use cases, such as policy management and charging for different services.
Maintainability: By isolating the logic of each Diameter application, the stack remains maintainable, with clear boundaries between different functional areas. This design supports the continuous evolution of telecom systems, allowing the Diameter stack to integrate with newer technologies like 5G while maintaining legacy support.
Efficient Session Management: Sessions are crucial for the reliability of the Diameter protocol. The dedicated session classes for client and server roles enable efficient state tracking, ensuring that messages are processed correctly according to the application-specific protocol’s state machine.
Error Handling and Robustness: Application-specific components include built-in error handling mechanisms, particularly in the provider classes, to ensure graceful recovery from failures like unknown session IDs, missing AVPs, or protocol violations.

Factories

In the Mobius Diameter Stack, factories play a central role in the creation and management of various protocol-specific entities such as AVPs (Attribute-Value Pairs), messages, and sessions. Each factory is responsible for generating instances of protocol components that are used in Diameter communication, tailored to specific applications like Credit Control (CC), Cx/Dx, EAP, Gq, and others. These factories allow for consistent and efficient object creation, encapsulating complex logic while ensuring that required parameters are validated and all necessary attributes are properly handled.
The implementation of these factories is generally split into three types:
AVP Factories - For creating AVP instances.
Message Factories - For creating Diameter requests and responses.
Session Factories - For creating client and server session objects.

AVPFactory 

AVP Factories are responsible for the creation of Diameter AVPs (Attribute-Value Pairs), which are the building blocks of Diameter messages. These factories encapsulate logic to handle various AVP-specific attributes such as data types, constraints (e.g., minimum and maximum occurrences), and validation rules. AVP factories ensure that the AVPs conform to the Diameter protocol specifications for the relevant application.

Structure
Each AVP factory typically extends from a common base factory (e.g., com.mobius.software.telco.protocols.diameter.app.commons.AvpFactoryImpl) and specializes in handling AVPs for a specific application like Credit Control, Gq, etc. The factory methods are used to instantiate AVP objects, often performing necessary validation checks such as ensuring that required AVPs are present and occur within the allowed limits.

Common Workflow
Creating AVPs: The factory receives necessary parameters (e.g., a value or an identifier) and returns an instance of the corresponding AVP object.
Validation: If an AVP is missing, occurs too many times, or contains an invalid value, exceptions such as MissingAvpException, AvpOccursTooManyTimesException, or InvalidAvpValueException are thrown.

Examples:
getUserEquipmentInfoExtension: Creates a UserEquipmentInfoExtension AVP.
getFlowDescription: Creates a FlowDescription AVP used in the Gq application.
getSubscriptionId: Creates a SubscriptionId AVP for Credit Control messages.

MessageFactory 

Message Factories are responsible for creating Diameter requests and answers for specific applications. Each Diameter application defines a set of messages (requests and answers), and the message factory provides a structured way to generate these messages with all the necessary AVPs. This ensures that each message adheres to the expected protocol format and contains all mandatory attributes.

Structure
Each Message Factory implements a specific message interface (e.g., MessageFactory for Gq or Cx/Dx applications) and is tasked with creating both requests (e.g., AARequest, LocationInfoRequest) and answers (e.g., AAAnswer, LocationInfoAnswer) for the application. The factory also handles setting key parameters such as session IDs, host information, and other relevant AVPs.

Common Workflow
Creating Requests: The factory creates request messages such as AARequest, MultimediaAuthRequest, or UserAuthorizationRequest. Each request contains mandatory and optional AVPs, which are added by the factory methods.
Creating Answers: When receiving a request, the factory creates the corresponding answer message (e.g., AAAnswer, LocationInfoAnswer) and fills in the result codes, session IDs, and any application-specific AVPs.

Examples:
createAARequest: Creates an AARequest message with the necessary AVPs for Gq application.
createLocationInfoRequest: Generates a LocationInfoRequest for the Cx/Dx application.
createReAuthAnswer: Responds to a ReAuthRequest with a ReAuthAnswer.

SessionFactory

Session Factories handle the creation of client and server sessions within the Diameter protocol. These sessions encapsulate the state and lifecycle of a communication between Diameter peers. Session Factories ensure that client and server sessions are initialized with all necessary properties, including session identifiers and relevant AVPs.

Structure
Each SessionFactory implements a specific interface, which defines methods for creating client (createClientSession) and server sessions (createServerSession). The factory uses input parameters from requests to instantiate a session object that encapsulates the session state, peer information, and any application-specific data.

Common Workflow
Creating Client Sessions: The factory uses the request object to initialize a ClientSession, which represents the client-side state of the communication.
Creating Server Sessions: Similarly, the factory uses the request object to create a ServerSession, representing the server-side state.

Examples:
createClientSession: Creates an EAPAuthClientSession or GqAuthClientSession from an incoming request.
createServerSession: Initializes an EAPAuthServerSession or GqAuthServerSession using session data.

ClientSession and ServerSession

ClientSession and ServerSession are components in Diameter-based applications. They manage the lifecycle of user sessions by handling requests and responses between Diameter clients and servers. These sessions are designed to implement state machines and handle authorization, authentication, credit control, and service termination processes.
ClientSession: Initiates requests on behalf of clients (e.g., user devices or network clients). It manages requests for services like authentication, reauthorization, session termination, and more. The session ensures the client's service is correctly validated and maintains session states until completion.
ServerSession: Listens for and processes requests sent by clients. It is responsible for authenticating users, authorizing services, and responding with appropriate results or errors. ServerSession may also handle session terminations and reauthorization requests initiated by external servers or clients.

Key features:
Session lifecycle management: These sessions manage the entire lifecycle of interactions, including starting, maintaining, and terminating sessions.
State transitions: Each session maintains state transitions based on the type of request and success or failure of operations.
Error handling: Supports handling of various errors and exceptions during communication.
Support for multiple Diameter applications: These sessions are implemented in various Diameter applications such as Gx, Gq, and E4, etc. Each extending the core session management principles.

General Principles Behind Application-Specific Sessions
Both ClientSession and ServerSession follow certain general principles:
Stateful and Stateless Modes: Depending on the application, these sessions can operate in either stateful or stateless mode. For example, the E4ClientSession and E4ServerSession are stateless, meaning they do not maintain state across transactions, while sessions like GMBAuthClientSession and CreditControlServerSession are stateful, meaning they maintain session information until the session is terminated.
Common Interface Structure: Both sessions follow a similar interface structure across applications, making them modular and easy to extend for new Diameter applications.
Consistency and Reusability: Common methods such as sendInitialRequest, sendReauthAnswer, and sendSessionTerminationRequest in ClientSession and sendInitialAnswer, sendReauthRequest in ServerSession allow for consistency and code reuse across different applications.

ClientSession Workflow:

• Initialization: The client session starts when a user device or client requests access to a service, such as via a Credit Control Request (CCR) or AA-Request.
• Pending State: The session moves into the Pending state while waiting for an answer. During this state, the session may handle timeouts, errors, or reattempts if the service is not successfully authorized.
• Open State: Upon receiving a successful answer (e.g., AA-Answer), the session grants service access to the client and transitions to the Open state.
• Session Updates: During the session's lifecycle, the client may request additional services or updates. For example, Re-Authorization Requests (RAR) may be processed in the Open state.
• Session Termination: When the service is no longer required, a Session Termination Request (STR) or Abort Session Request (ASR) is sent, and the session transitions back to Idle or Disconnected states.

ServerSession Workflow:

• Session Creation: The server session starts when a client request, such as a CCR or AA-Request, is received.
• Processing Requests: The session processes the client request, authenticating the user and checking whether the service can be granted. A successful response is sent back to the client.
• Open State: If service authorization is successful, the session moves to the Open state, where it maintains the connection with the client and handles session updates (e.g., via Credit Control Updates (CCU) or ReAuthRequests).
• Session Termination: Similar to the client session, the server can initiate session termination based on external signals (e.g., ASR or Session-Timeout).
• Cleanup: After the session ends, resources are released, and the session returns to the Idle state.

In both ClientSession and ServerSession, the transition between states (Idle, Pending, Open, etc.) ensures smooth management of user sessions, with proper error handling and session cleanup at the end of each process.

Application-Specific Providers

Application-Specific Providers manage and coordinate the Diameter sessions and message exchanges within specific applications. Each provider is responsible for a particular Diameter application (such as Credit Control, Cx/Dx, or E4) and acts as the primary interface between the core Diameter stack and the application-specific logic. The goal of these providers is to ensure seamless session creation, message handling, and protocol compliance within their respective application domains.

Key Features

Session Management: The primary task of the Application-Specific Provider is to manage Diameter sessions. For each incoming Diameter request, the provider must decide whether to associate it with an existing session or create a new one. This decision is typically based on the session ID found within the request.
The provider maintains a session factory that is responsible for generating new session instances. These sessions represent ongoing communication between two network nodes and encapsulate the logic for managing the state transitions based on received Diameter messages.

Message Handling and Routing: The provider is responsible for the routing and processing of Diameter messages, including requests and responses. When a Diameter request is received, the provider directs it to the appropriate session based on the session ID or creates a new session if needed.
Providers ensure that both client and server messages are handled according to the application's specific state machine and protocol rules. For example, in Credit Control applications, providers handle specific message types like Credit Control Requests (CCR) and Credit Control Answers (CCA).

Application-Specific Logic: Each provider encapsulates logic that is specific to the application it serves. For example, the Credit Control Provider manages credit control sessions and the Cx/Dx Provider handles user authentication and service information.
The application-specific providers use a combination of AVP (Attribute-Value Pair) factories, message factories, and session factories to ensure that the correct messages are created, parsed, and processed in compliance with the corresponding Diameter application protocol.

Concurrency and Thread Safety: The providers implement concurrency control using thread-safe data structures such as ConcurrentHashMap to manage session listeners and handle concurrent requests. This is crucial in high-performance environments where multiple sessions are processed in parallel.

Separation of Client and Server Logic: Each provider distinguishes between client and server sessions by managing them separately. This is achieved through different session factories and listeners tailored to client and server operations.
Message Factories and AVP Factories: Providers leverage message factories to create and handle Diameter requests and answers specific to the application. AVP factories are responsible for constructing the AVPs used within these messages.

Session Factory: This component of the provider is responsible for instantiating new session objects when required. The session factory ensures that new sessions adhere to the specific application’s protocol and state machine.

Error Handling: Providers include mechanisms to handle Diameter exceptions, such as when a session is not found or when a message processing error occurs.

Example of implementation of DiameterProvider for CreditControl application: