OpenIG HTTP client
This step details removing the dependency on the http-builder library and using the built-in CHF APIs instead. The migrated example script below demonstrates the basics of the CHF API: request creation, obtaining a response and reading its content as JSON (without forgetting to release resources).
In each script’s execution context there is an HTTP binding (Client interface) that provides you with a way to perform HTTP requests from within your script.
From the Client API:
class Client {
Promise<Response, NeverThrowsException> send(Request request);
Promise<Response, NeverThrowsException> send(Context context, Request request);
}There is only one thing that you can obviously do with this interface, that is, send an HTTP request. You do not get back the response directly, but you have the promise of a response. This is comparable to a Future on which you would attach listeners that get notified when the response has been fully received (or an error has happened).
This part of the migration uses the Promise as a Future (blocking on a .get()). In essence, this migration step is all about creating and populating a CHF Request object.
The following shows the above example script after it has been migrated to use the built-in CHF APIs:
// Check if OpenAM session cookie is present
if (null != request.cookies[ 'iPlanetDirectoryPro' ]) {
String openAMCookieValue = request.cookies[ 'iPlanetDirectoryPro' ][ 0 ].value
logger.info("iPlanetDirectoryPro cookie found, performing logout")
def logout = new Request()
logout.method = "POST"
logout.uri = "${openamUrl}/sessions"
logout.uri.query = "_action=logout"
logout.headers['iPlanetDirectoryPro'] = openAMCookieValue
// Block for at most 20 seconds before using the response
def logoutResponse = http.send(logout)
.get(20, SECONDS)
def result = logoutResponse.entity.json.result
logger.info("OpenAM logout response: " + result)
// Don’t forget to release resources associated with the response
logoutResponse.close()
}
return next.handle(context, request)The logic in this script is as follows:
- Request initialization: the following snippet of this script creates a POST request to the AM/OpenAM sessions endpoint (using Groovy String substitution). It specifies the logout action in the query URL component and places the current request’s SSO Token (the iPlanetDirectoryPro cookie) in a header (as this is where the sessions endpoint expects it):
def logout = new Request()
logout.method = "POST"
logout.uri = "${openamUrl}/sessions"
logout.uri.query = "_action=logout"
logout.headers['iPlanetDirectoryPro'] = openAMCookieValue- Perform the request and wait for the response: the following snippet of this script uses the get() method. The returned promise can never throw an exception, which means you do not need to use the getOrThrow() variant of the get() method; if something goes wrong when making the request, you will receive a 502 Bad Gateway response. This example also includes a timeout to prevent deadlocks if there is no response. When the timeout is reached, a RuntimeException is returned; ideally the timeout should be configurable and IG/OpenIG provides the args configuration point in the script configuration, which can be used for this purpose:
// Block for at most 20 seconds before using the response
def logoutResponse = http.send(logout)
.get(20, SECONDS)- Read the response's content using the CHF's native JSON support: the following snippet of this script calls logoutResponse.entity.json, which provides the JSON-parsed content of the message, with a focus on the result JSON attribute. The message is then closed to release resources:
def result = logoutResponse.entity.json.result
// Don’t forget to release resources associated with the response
logoutResponse.close()- Call the next element of the chain and continue the request processing:
return next.handle(context, request)This step details moving away from synchronous programming (where we spend valuable CPU time waiting for things to happen) to asynchronous programming (where we register callbacks to notify us when things are ready and act when that happens rather than waiting for something; this allows our valuable CPU time to do other things). It also introduces the http.send() returned Promise object, where it’s the promise of a response that may or may not have been received yet. Put simply, we want to read the response content after it has been received, log the result and then continue the chain execution.
This step demonstrates adding an asynchronous function that calls the next element in the chain, after the response processing has been done.
The following shows the example script after it has been migrated to use the CHF asynchronous APIs:
// Check if OpenAM session cookie is present
if (null != request.cookies[ 'iPlanetDirectoryPro' ]) {
String openAMCookieValue = request.cookies[ 'iPlanetDirectoryPro' ][ 0 ].value
logger.info("iPlanetDirectoryPro cookie found, performing logout")
def logout = new Request()
logout.method = "POST"
logout.uri = "${openamUrl}/sessions"
logout.uri.query = "_action=logout"
logout.headers['iPlanetDirectoryPro'] = openAMCookieValue
// Return the "promise" of a result => non-blocking
// Processing will happen when a response from AM will be received
return http.send(logout)
.then { response ->
def result = response.entity.json.result
logger.info("OpenAM logout response: " + result)
response.close()
return response
}
.thenAsync({
next.handle(context, request)
} as AsyncFunction)
}
logger.info("iPlanetDirectoryPro cookie not found, continue and ignore logout action")
return next.handle(context, request)As you can see, most of the changes have occurred towards the end of the script, with the response being processed using callbacks. Additionally, since we no longer block, we do not need a timeout to prevent deadlocks.
The logic in this script is as follows:
- Process the response when it’s ready: the following snippet of this script introduces a then(Function) method to process this response. The callback Function provided in this then() method accepts the result of the invocation as a parameter, which can be processed as required; this example reuses the response processing logic from before to return the response (a result is expected from Function callbacks):
return http.send(logout)
.then { response ->
def result = response.entity.json.result
logger.info("OpenAM logout response: " + result)
response.close()
return response
}You must include the first return in this section of the script to ensure the promise that is configured with the response processing function is returned when the logout action is triggered. If you exclude the return, for example, the first line is simply:
http.send(logout)The script will execute, do an HTTP call, register a callback on the promise and then just continue. This means the logout action will get missed when there is an iPlanetDirectoryPro cookie, which is not the desired behavior of this script.
- Continue the execution of the chain after triggering the logout action: the following snippet of this script calls the next element of the chain by performing the call in a then-able fashion (chaining different then() methods together). You can use this approach because you will just see the response of the logout action when a request with an iPlanetDirectoryPro cookie enters the filter, rather than the usual response sent back from the protected application:
.thenAsync({
next.handle(context, request)
} as AsyncFunction)- There is no return statement, because Groovy considers the last evaluated expression of a method to be the returned value.
- The as AsyncFunction is only required for asynchronous functions (ResultHandler, ExceptionHandler and Function don’t need it). The Groovy compiler doesn’t handle all the generic types of AsyncFunction very well.
There are a number of then-able methods offered by the Promise API that you can try, which will make your code simpler and avoid 'callback hell'. These methods fall into the following categories:
- thenOn****(****Handler): These methods are pure notification functions (on successful result, on error). You can’t return anything from within these methods, they are here as a side-effect-free type of handler. No exceptions should be thrown in theses callbacks. * then(Function), with 1, 2 or 3 Function arguments: These methods are designed for when you need to return something different to the next handler in the Promise chain (a transformation). They could be parsing an input string and return a JSON, or modifying the result. Throwing exceptions is accepted here and they will be propagated to the next functions in the Promise chain.
- thenAsync(AsyncFunction), with 1, 2 or 3 AsyncFunction arguments: These methods are quite similar to those in then(Function). The real difference is that they have to return a promise of their result instead of the actual result. These methods are an ideal fit when you need to call another method that itself returns a promise (like returning the result of the filter’s chain). |
- then***(), the rest of the then-able methods (thenAlways(), thenFinally(), thenCatch(), ...): These methods are really syntactic sugar to make the promise more fluent to read.
Now you can understand why our first then() can be turned into a thenOnResult() instead, which saves the last return statement as the received parameter is returned:
return http.send(logout)
.thenOnResult { response ->
def result = response.entity.json.result
logger.info("OpenAM logout response: " + result)
response.close()
}
.thenAsync({
next.handle(context, request)
} as AsyncFunction)
