HTTP/2 Server Agent(3.0)
The HTTP/2 Server agent enables you to configure a HTTP server in a real-time workflow. The agent receives requests, convert them into UDRs routed into the workflow, and then sends responses back on a TCP/IP connection.
The agent can be used for both HTTP/1 and HTTP/2.
Prerequisites
The reader of this information should be familiar with:
Hypertext Transfer Protocol version 2 (RFC 7540: https://tools.ietf.org/html/rfc7540)
Hypertext Transfer Protocol version 1.1 (RFC 2616: http://www.ietf.org/rfc/rfc2616.txt)
- The Transport Layer Security (TLS) Protocol version 1.3 (RFC 5246: https://www.ietf.org/rfc/rfc5246.txt)
Configuration
The HTTP/2 agent's configuration contains four tabs; Server, Overload Protection, OpenAPI/5G and Authentication.
Server
The Server tab contains the following settings:
| Setting | Description |
|---|---|
Use SSL | Select this option if you want to use SSL. |
| Security Profile | If you have selected to use SSL, select which Security (3.0) the agent should use. |
| Enable 2-way Authentication | If you have selected to use SSL, you can select this option to enable 2-way Authentication. If this option is selected, the Security (3.0) used must be configured using Java Truststore. |
| Host | Enter the IP address or hostname that you want the agent to bind to. |
| Port | Enter the port number you want the agent to bind to. |
| Default connection concurrent streams | Fundamentally HTTP2 is designed to make it easy for a client to send multiple parallel requests. Each request is entitled to a thread and if blocking APIs are used, then there are many ways a client can cause that thread to block. To handle the resource problem this can cause, the setting Default connection concurrent streams can be used. The setting specifies the maximum number of concurrently open streams allowed per single HTTP/2 connection. The default value uses in Jetty HTTP/2 server is 128. Larger values increase parallelism, but cost a memory commitment. |
| Route Error to APL | Select this option if you want to route HTTP errors to APL for custom handling. An example for how to handle the error using APL can be found at the end of this page. |
Client Timeout (sec) | The period in seconds after which the HTTP/2 Server should close the connection if a client is inactive. That is, this is the period of inactivity from when the client has opened the connection or received the last expected response until the server should close the connection. For example, if Client Timeout is set to 6, this means that the server will close the connection if the client is inactive for 6 seconds. |
| Server Timeout (sec) | The period in seconds before which the HTTP/2 Server has to reply to a request. That is, this is the period within which a server has to process a request and send a response to a client. If the time limit is reached, an error response with a status code of 500 will be sent. |
| Default Charset | Select the character set you want to use as default character set. UTF-8 is preselected. This character set will be used if the character set requested by Accept-Charset is not found in system. |
| GZIP Compression Level | If gzip is requested, then the response will be be gzipped with the compression level you specify in this field, 1-9. |
Overload Protection
The Overload Protection tab controls overload protection and contains the following settings:
| Setting | Description |
|---|---|
Enable Overload Protection | Select this option if you want enable overload protection. |
| Number of Requests | If you have selected enable overload protection, enter the maximum number of requests that are allowed to be sent during the time specified in Average Period (sec). When this number of requests has been reached, further requests will be blocked until the time specified in Wait Duration (sec) has passed, then a retry will be attempted. |
| Period (sec) | Enter the time period in seconds for which the number of requests should be counted. |
| Wait Before Retry (sec) | Enter the number of seconds to wait before attempting to retry a request. |
OpenAPI/5G
The OpenAPI/5G tab contains the following settings:
| Setting | Description |
|---|---|
Use OpenAPI Profile | Select this option if you want the agent to use an OpenAPI profile. |
| OpenAPI Profile | If Use OpenAPI Profile has been selected, select which profile to use in this field. |
| Enable Validation | Select this option if you want to validate the OpenAPI profile. Warning! Turning this option ON will have a very significant performance impact on the overall performance of the flow. When validation is enabled, each payload will be validated against the Open API schema, an operation that can be very resource-intensive. We recommend to only enable this setting during development and testing and to disable it in a stable production environment. Note! Strict validation is applied against the OpenAPI specification due to the upgrade of third party libraries. For Example, if the response contains the body but the schema doesn't expect the response to contain body then it will causing validation failure. Refer to this link for further information https://bitbucket.org/atlassian/swagger-request-validator/issues/246/validator-does-not-check-a-response-body |
| Override Error Response on Server Shutdown | Select this option to enable the customization of the HTTP response for when a request to the server is received upon the server being terminated. |
| Override Error Response on Server Overload | Select this option to enable the customization of the HTTP response for when a request to the server is received upon the server being overloaded. Note! Overload protection should be enabled to utilize this feature |
| Status Code | The HTTP error code for the error response. The default error code set is 503 for server shutdown and 429 for server overload. |
| Content Type | |
| UDR Type | Browse for the UDR that will be populated as part of the HTTP response message. |
| UDR Field | The fields in the selected UDR Type will be shown in this column. |
| Type | The data type for the each of the UDR fields will be shown here.
|
| Value | Enter a value that conforms to the data type of the UDR field. The value will then be parsed into the HTTP response when the error is triggered. |
| Enable 5G Profile | Select this option if you want the agent to use a 5G profile. |
| 5G Profile | If Use 5G Profile has been selected, select which profile to use in this field. |
| NRF Address (Primary) | Enter the primary NRF (NF Repository Function) address in this field. |
| NRF Address (Secondary) | Enter one or more secondary NRF (NF Repository Function) address in this list, this is to allow for alternative connections when the heartbeat with the primary NRF Address is not established. |
| Fall back to primary | Enable this option to have the agent fall back to the primary NRF address from the secondary address. The agent to constantly send a registration request to the primary NRF address at every heartbeat interval. The heartbeat interval will be based off of the value that you have configured in the 5G profile. |
Authentication
The Authentication tab contains the following settings:
| Setting | Description |
|---|---|
Use Token Authentication | Select this option if you want to use token authentication. |
Access Token Required | If you have selected Token Authentication, you can select this option if you want the access token to be required. |
Public Key | Paste the public key into this field. |
Input/Output Data
Input Data
NRFSpecificationUDR(3.0) will only be required when Custom Specification is enabled on the 5G Profile. Refer to 5G (3.0) for more information about enabling Custom Specifications for 5G.
Output Data
NRFSpecificationUDR(3.0) will only be required when Custom Specification is enabled on the 5G Profile. Refer to 5G (3.0) for more information about enabling Custom Specifications for 5G.
Route Error to APL
When enabling Route Error to APL, you will send the request over as part of the RequestCycle UDR where you will then be able to use the Analysis agent to customize your own response. The example shown below has an If statement to catch any requests with errors by checking for isError that are set to True. The APL code will then go on to populate the response and route it back to the HTTP/2 Server agent.
import ultra.openapi.Test_5G.TS29510_Nnrf_NFDiscovery;
consume {
http.RequestCycle cycleUdr = (http.RequestCycle) input;
debug("input from client \n" + cycleUdr);
ProblemDetails problemDetails = udrCreate(ProblemDetails);
http.Response response = udrCreate(http.Response);
if (cycleUdr.isError) { // cycleUdr.isError will be true if any errors is encountered while processing the request
list<string> headers = listCreate(string);
listAdd(headers, "application/problem+json");
mapSet(response.headers, "Content-Type", headers);
problemDetails.title = "Request Error";
problemDetails.cause = cycleUdr.errorMessages[0]; // cycleUdr.errorMessages is a list containing error messages set from the error encountered
problemDetails.status = cycleUdr.errorStatusCode; // cycleUdr.errorStatusCode contains the status code of the error encountered
response.openAPIUDR = problemDetails;
response.statusCode = cycleUdr.errorStatusCode;
}
cycleUdr.response = response;
debug("after apl logic \n" + cycleUdr);
udrRoute("to_server", cycleUdr);
}