The HTTP resource adaptor provides a generic HTTP interface for SLEE services, supporting the Hypertext Transfer Protocol (HTTP) as specified in RFC1945 and RFC2616.
The resource adaptor
-
is bidirectional; applications can receive incoming HTTP requests and also initiate outgoing HTTP requests
-
implements a subset of HTTP/1.1 (request methods GET, HEAD, POST, PUT and DELETE)
-
supports incoming and outgoing HTTPS.
-
Integrates with Metaswitch Service Assurance Server (SAS)
Topics
configure the resource adaptor using profiles and properties |
|
use event types, activities, ACI and SBB interfaces |
|
Metaswitch Service Assurance Server integration |
|
install and run the example service included with the HTTP Resource Adaptor |
Other documentation for the HTTP Resource Adaptor can be found on the HTTP Resource Adaptor product page.
Notices
Copyright © 2022 Microsoft. All rights reserved
This manual is issued on a controlled basis to a specific person on the understanding that no part of the Metaswitch Networks product code or documentation (including this manual) will be copied or distributed without prior agreement in writing from Metaswitch Networks.
Metaswitch Networks reserves the right to, without notice, modify or revise all or part of this document and/or change product features or specifications and shall not be responsible for any loss, cost, or damage, including consequential damage, caused by reliance on these materials.
Metaswitch and the Metaswitch logo are trademarks of Metaswitch Networks. Other brands and products referenced herein are the trademarks or registered trademarks of their respective holders.
Configuring the HTTP Resource Adaptor
Below are properties for configuring the HTTP resource adaptor (from the HTTP API), including properties for secure configuration.
Name | Type | Default | Description |
---|---|---|---|
|
|
|
Local IP address that the HTTP resource adaptor will listen on for requests. |
|
|
|
Local TCP port that the HTTP resource adaptor will listen on for requests. |
|
|
Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the HTTP resource adaptor will listen on for requests. If BindAddresses is empty, ListenAddress and ListenPort will be employed. For syntax see Specifying bind addresses. |
|
|
|
|
The maximum number of outgoing TCP connections the resource adaptor will open to a single host when sending requests to that host. |
|
|
|
The time (in ms) that the resource adaptor will wait for a response to an outgoing request before failing the request. The application will see a 500 Server Error response and in case of asynchronous request, activity will end. |
|
|
|
The time (in ms) that the resource adaptor will keep an outgoing TCP connection open for, with no activity on the connection. |
|
|
|
Controls how many HTTP requests may be queued up on a single connection without receiving a response from the server. This is known as "HTTP pipelining". A value of 1 is strongly recommended if the server does not support non-persistent connections. When the connection closes (which it always will if they are non-persistent) the other requests in the pipeline will have to be re-sent on another connection. A value of 1 is also recommended for slow or unreliable servers, to avoid head-of-line blocking. |
|
|
|
The time (in ms) that a request can be held on the queue waiting for an outgoing connection before timing out and firing an event with response code 500 and reason "Timed out waiting for server connection". |
|
|
|
When a burst of (send) requests occurs, the resource adaptor queues them, and only creates new connections if they cannot be sent on existing connections. NewConnectionDelay is the time in milliseconds that the resource adaptor will wait for an outgoing connection to become available before creating a new one. If the server does not support persistent connections, it is strongly recommended that this value be set to 0. |
|
|
|
The time (in ms) that the resource adaptor will wait for the SLEE to send a response to an incoming request before failing the request. The resource adaptor will automatically send an error response to the client and end the activity. |
|
|
|
The time (in ms) that the resource adaptor will keep an incoming TCP connection open for, with no activity on the connection. |
|
|
|
The default value of the Server header set in outgoing responses. Applications may override this by setting the Server header in the response manually. |
|
|
|
The default value of the User-Agent header set in outgoing requests. Applications may override this by setting the User-Agent header in the request manually. |
|
|
|
Defines how the resource adaptor generates the javax.slee.Address object for HTTP events. Default is to not use any address. Setting this to the value |
|
|
|
Maximum value in bytes for the Content-Length header of the HTTP messages which have a message body. If this value is exceeded, the application will see a 413 Client Error Response. MaxContentLength value update will apply to new connections. |
|
|
|
The number of workers used by the server and client worker executors. 0 means use Netty default: 2 * |
|
|
|
If enabled, the HTTP resource adaptor will compress outgoing responses automatically, while respecting the |
|
|
|
If enabled, the HTTP resource adaptor will decompress incoming responses automatically, while respecting the |
|
|
|
If enabled, the HTTP resource adaptor will create SAS Trails for incoming requests, and report them automatically. |
|
|
Local IP address of the service mesh server, if present. If unset no service mesh will be used. If a service mesh is used, the message sent from the RA will be modified to be sent to the ServiceMesh address, with the original destination stored in the 'Host' header. Proxy and Service Mesh are mutually exclusive |
|
|
|
|
Local TCP port of the service mesh server, if present. If set to 0 no service mesh will be used. If a service mesh is used, the message sent from the RA will be modified to be sent to the ServiceMesh address, with the original destination stored in the 'Host' header. Proxy and Service Mesh are mutually exclusive. |
|
|
Local IP address or FQDN of the proxy server, if present. If unset no proxy will be used. Proxy and Service Mesh are mutually exclusive. |
|
|
|
|
Local TCP port of the proxy server, if present. If set to 0 no proxy will be used. Proxy and Service Mesh are mutually exclusive. |
|
|
|
Comma-separated list of regular expressions that will be matched against request URI paths when reporting incoming requests to SAS. Requests with matching URIs will have their content redacted in traces sent to SAS, to avoid sensitive information leaking via SAS. If empty then no redaction is performed. Partial matches are accepted, e.g. the pattern |
ThreadPoolSize , MaxChannelMemorySize and MaxTotalMemorySize are not currently used. In future, they will support configuration of the Netty OrderedMemoryAwareThreadPoolExecutor . |
Secure configuration
Name | Type | Default | Description |
---|---|---|---|
|
|
|
Local TCP port that the HTTP resource adaptor will listen on for HTTPS requests. If set to a value greater than 0, then a KeyStore must be provided that contains the private key for the server. |
|
|
Contains per-node configuration information regarding each node’s specified local IP address and local TCP port that the HTTP resource adaptor will listen on for requests. If SecureBindAddresses is empty, ListenAddress and SecureListenPort will be employed. If a SecureBindAddress is specified then a KeyStore must be provided that contains the private key for the server. For syntax see Specifying bind addresses. |
|
|
|
|
Path to JKS keystore file. System properties (such as |
|
|
|
Keystore password for file specified by KeyStore. |
|
|
|
Path to JKS keystore for trust certificates. |
|
|
|
Keystore password for file specified by TrustStore. |
|
|
|
List of cipher suites to pass to |
|
|
|
Value to pass to |
|
|
|
When set to true, this will set the same flag on the SSL Engine for incoming HTTPS connections, meaning a valid client certificate is required to connect. The client certificates can be retrieved from the |
Specifying bind addresses
BindAddresses
and SecureBindAddresses
are specified as a comma-separated list of {node}host:port
elements.
This allows entities running on two nodes on the same host to use different ports, for example:
{101}0.0.0.0:8000,{102}0.0.0.0:8001
It also allows entities running on different hosts to specify an interface to listen on that is specific to each host, for example:
{101}192.168.1.100:8000,{102}192.168.1.101:8000
Events and Activities
Below are details of events, activities, and the ACI and SBB interfaces for the resource adaptor.
Events
The resource adaptor emits the following event types:
All listed classes are in the com.opencloud.slee.resources.http package. |
Event ID |
|
---|---|
Event Object |
|
Activity Object |
|
Description |
The resource adaptor received an HTTP GET request. |
Event ID |
|
---|---|
Event Object |
|
Activity Object |
|
Description |
The resource adaptor received an HTTP POST request. |
Event ID |
|
---|---|
Event Object |
|
Activity Object |
|
Description |
The resource adaptor received an HTTP HEAD request. |
Event ID |
|
---|---|
Event Object |
|
Activity Object |
|
Description |
The resource adaptor received an HTTP PUT request. |
Event ID |
|
---|---|
Event Object |
|
Activity Object |
|
Description |
The resource adaptor received an HTTP DELETE request. |
Event ID |
|
---|---|
Event Object |
|
Activity Object |
|
Description |
The resource adaptor received a response or generated an error response to an earlier outgoing HTTP request. Only one response event type is defined (instead of separate events 2xx, 3xx and so on), because the resource adaptor assumes that applications will always want to see the HTTP response, regardless of the status-code value. |
Activities
The resource adaptor creates two types of activities:
Activity Object | Description |
---|---|
This activity is created when the resource adaptor receives a HTTP request. The activity object has methods for creating and sending a response to the request. The activity ends when the response is sent. In addition, if for some reason a SBB does not send a response in time, the resource adaptor will automatically send an error response back to the client, ending the activity. The timeout is specified by the IncomingRequestTimeout configuration property. |
|
This activity is created when a SBB sends an outgoing HTTP request. There is nothing that can be done with the activity, it is only there so that the SBB may attach to it in order to receive the response asynchronously. |
Activity Context Interface Factory
The ACI Factory interface is HttpActivityContextInterfaceFactory
.
SBB Interface
The SBB Interface is HttpProvider
. This interface must be used for creating and sending outgoing requests. If the service only deals with incoming requests, then this interface does not need to be used.
Error Response Codes
This page describes HTTP response codes sent by the resource adaptor in server mode, and response codes used in artificial response events generated in client mode.
Acting as a server
The resource adaptor sends the following response codes to clients when there are event processing errors:
Code | Message | Reason |
---|---|---|
|
"Server Too Busy" |
Activity could not be started due to non system-level issues such as an input rate limiting policy. |
|
"Internal Server Error" |
Activity could not be started due to non system-level or any other issues. |
|
"Server Error" |
Resource adaptor event processing failed. |
|
"Not Implemented" |
Event filtered by an |
The resource adaptor also sends the following response codes to clients in the cases described:
Code | Message | Reason |
---|---|---|
|
"Missing Host Header" |
Host header not set for HTTP v1.1 request. |
|
"Not found" |
Host and URI constitute a malformed URL. |
Acting as a client
In certain scenarios when operating in client mode, the resource adaptor will fire response events when no response has been received from the server.
The HttpResponse.isServerResponse() method allows a service to distinguish between responses received from the remote server and responses generated by the resource adaptor. |
Code | Message | Reason |
---|---|---|
|
"Server closed connection" |
Connection closed by a remote server. |
|
"Read error: <cause>" |
Failure on receiving response in client. |
|
"Write error: <cause>" |
Failure on sending request from client. |
|
"Timed out waiting for server connection" |
Queue timeout met before a connection was available and the request could be sent. |
|
"RA deactivation while waiting for server connection" |
The resource adaptor reactivated before a connection was available and the request could be sent. |
Service Assurance Server (SAS) Tracing
The HTTP resource adaptor contains code for integration with Metaswitch Service Assurance Server (SAS), which is a platform for recording and viewing detailed call handling information.
Rhino TAS 2.6 or later supports SAS tracing. You can use the HTTP resource adaptor with earlier Rhino versions if the Rhino API Compatibility SLEE library is deployed. The script that deploys the HTTP Ping service included in the resource adaptor package has an example of how to deploy the library. |
For details about SAS tracing in Rhino TAS, see the SAS Facility section in the Rhino extended API document. For details about developing applications with the SAS tracing functionality, see the Rhino SAS API Development Guide.
The HTTP resource adaptor has two models for managing SAS trails, depending on whether it is handling incoming or outgoing requests.
Incoming requests
The resource adaptor creates a new SAS trail for every incoming request if it is configured to do so. After that, it logs the HTTP request with this trail.
The CreateIncomingSasTrail
configuration property controls this trail creation behavior. For details, see Configuring the HTTP Resource Adaptor.
Outgoing requests
For outgoing HTTP requests, if there is a SAS trail attached to the OutgoingHttpRequestActivity
, the resource adaptor uses it to log the HTTP request. It will never create a SAS trail. Therefore, if there is no trail attached to the outgoing HTTP request activity, the resource adaptor does not log the request to SAS.
Rhino TAS has a feature that automatically sets the trail for activities created within event handlers for activities that have a trail attached. To disable the tracing of outgoing HTTP requests in this scenario, set the SAS trail on the OutgoingHttpRequestActivity
to null
.
For details about automatic trail handling, see the Rhino SAS API Development Guide.
SAS events
The mini-bundle that the HTTP resource adaptor uses is as follows. As shown in the code, the following SAS events are defined:
-
INCOMING_MESSAGE
-
OUTGOING_MESSAGE
-
SENDING_MESSAGE
-
SENDING_MESSAGE_VIA_MESH
---
version: 1.0
events:
INCOMING_MESSAGE:
summary: 'Received HTTP {{ var_data[3] }} from {{ var_data[2] }}'
details: |
Received HTTP message from {{ var_data[2] }}:{{ static_data[1] }} on {{ var_data[1] }}:{{ static_data[0] }}
<sas:fixed-width-font>{{ var_data[0] }}</sas:fixed-width-font>
level: 60
call_flow:
caption: '{{ var_data[3] }}'
data: '{{ var_data[0] }}'
protocol: HTTP
direction: in
local_address: '{{ var_data[1] }}:{{ static_data[0] }}'
remote_address: '{{ var_data[2] }}:{{ static_data[1] }}'
message_id: '{{ var_data[4] }}'
call_info_id: '{{ var_data[5] }}'
OUTGOING_MESSAGE:
summary: 'Sent HTTP {{ var_data[3] }} to {{ var_data[2] }}'
details: |
Sent HTTP message to {{ var_data[2] }}:{{ static_data[1] }} from {{ var_data[1] }}:{{ static_data[0] }}
<sas:fixed-width-font>{{ var_data[0] }}</sas:fixed-width-font>
level: 60
call_flow:
caption: '{{ var_data[3] }}'
data: '{{ var_data[0] }}'
protocol: HTTP
direction: out
local_address: '{{ var_data[1] }}:{{ static_data[0] }}'
remote_address: '{{ var_data[2] }}:{{ static_data[1] }}'
message_id: '{{ var_data[4] }}'
call_info_id: '{{ var_data[5] }}'
SENDING_MESSAGE:
summary: 'Sending HTTP {{ var_data[0] }} to {{ var_data[1] }}:{{ var_data[2] }}'
details: |
Attempting connection to {{ var_data[1] }}:{{ var_data[2] }}
level: 40
SENDING_MESSAGE_VIA_MESH:
summary: 'Sending HTTP {{ var_data[0] }} to {{ var_data[1] }} via service mesh at {{ var_data[2] }}:{{ var_data[3] }}'
details: |
Attempting connection to {{ var_data[1] }} via service mesh at {{ var_data[2] }}:{{ var_data[3] }}
level: 40
For details about the mini-bundle or the event fields, see the Rhino SAS API Development Guide.
If SAS tracing is configured and enabled, when the resource adaptor logs a request or a response message, it also raises a |
Running the Example HTTP Service
HTTP resource adaptor package includes an example "Ping" service. This service simply responds with a page displaying the request contents.
Install and run the service
Below are basic instructions for deploying and testing the HTTP example service in your SLEE, followed by an excerpt of SBB code showing how a client sends and a server processes HTTP requests.
1 |
Install the service: $ cd examples $ ant |
---|---|
2 |
Navigate to |
HTTPS
To enable HTTPS:
1 |
Generate a keystore for the server: $ keytool -keystore http-ra.ks -storepass changeit -genkeypair
|
||
---|---|---|---|
2 |
Configure the resource adaptor entity and restart it: |
||
3 |
The URL |
Sample code
Below are excerpts of SBB code showing how servers can process HTTP requests, and clients can send them.
Server
Below is an excerpt of SBB code showing how incoming HTTP requests can be processed.
import com.opencloud.slee.resources.http.*;
...
// SBB event handler
public void onGET(HttpRequest event, ActivityContextInterface aci) {
IncomingHttpRequestActivity activity = (IncomingHttpRequestActivity) aci.getActivity();
// Send a redirect response...
HttpResponse response = activity.createResponse(302, "Moved Temporarily");
response.setHeader("Location", "http://anotherserver/index.html");
try {
// send the response
InvokingTrailAccessor.getInvokingTrail().event(SasEvent.SENDING_MESSAGE).varParam(request.getMethod()).report();
activity.sendResponse(response);
} catch (IOException e) {
warning("unable to generate response", e);
InvokingTrailAccessor.getInvokingTrail().event(SasEvent.UNABLE_TO_GENERATE_RESPONSE).report();
}
}
Client
Below is an excerpt of SBB code showing how outgoing HTTP requests can be made.
import com.opencloud.slee.resources.http.*;
...
public void setSbbContext(SbbContext sbbContext) {
this.sbbContext = sbbContext;
Context sbbEnv = (Context) new InitialContext().lookup("java:comp/env");
provider = (HttpProvider) sbbEnv.lookup("slee/resources/http/2.2/provider");
acif = (HttpActivityContextInterfaceFactory) sbbEnv.lookup("slee/resources/http/2.2/acifactory");
...
}
public void onSomeEvent(SomeEvent event, ActivityContextInterface aci) {
...
HttpRequest newRequest = provider.createRequest(HttpRequest.POST, new URL("http://someserver/service.jsp"));
newRequest.setContentAsString("text/plain; charset=\"utf-8\"", "test message");
OutgoingHttpRequestActivity activity = provider.createRequestActivity(newRequest);
ActivityContextInterface newACI = acif.getActivityContextInterface(activity);
// attach so we will receive response...
newACI.attach(sbbContext.getSbbLocalObject());
//Set the SAS trail to one we have on hand.
sasFacility.setActivityTrail(newACI, trail);
activity.sendRequest();
}
public void onHttpResponse(HttpResponse event, ActivityContextInterface aci) {
trace("Received " + event.getStatusCode() + " response");
byte[] data = event.getContent(); // Or getContentAsString() if appropriate
// process response content...
}
// instance vars
private SbbContext sbbContext;
private HttpProvider provider;
private HttpActivityContextInterfaceFactory acif;