Cripts for global plugin

In addition to be a scripting language for per-property, or remap rules, Cripts can also be used to write global ATS plugins. This is a more advanced use case, and requires some knowledge of how ATS works.

The automatic building of plugins that Cripts supports as a remap rule is not available (yet) to global plugins. As such, you must compile any global plugin manually. You can see this as an alternative to writing a plugin in regular C++, in fact you can still combine a global plugin with a remap rule plugin in the same Cript file.

Usage

As with remap rules, global Cripts still requires both the preamble as well as the epilogue. However, all callbacks are prefixed with glb_ to indicate that they are global hooks. See the hooks below for more details. Example:

The third step is to put the Cript file in either the configuration or plugin installation, depending on your preference. The file must be readable by the ATS process. Example:

#include <cripts/Preamble.hpp>

glb_read_request()
{
  borrow url = cripts::Client::URL::get();

  url.query.keep({"foo", "bar"});
}

#include <cripts/Epilogue.hpp>

Hooks

Hooks are the main way to interact with ATS. The hooks are the same as the ATS hooks, but with a few differences. The hooks are all in the global namespace, and the hooks are all functions. Cripts provides a core set of hooks which are always available, but they are not required to be used.

Not all ATS hooks are available in Cripts, but the most common ones are. Hooks are implicitly called if they are defined in the Cript file. The Cript will never explicitly setup the hooks, as this is done by the ATS process.

Normal Hooks

Lets look at the normal hooks that are available in Cripts. Note here that the name of the function dictates the underlying ATS hook.

glb_txn_start()

The glb_txn_start() hook is called at the beginning of a transaction. This is also where Cripts will setup other HTTP hooks as necessary. Note that in this hook, the client request has not yet been read, so you cannot access the request headers.

glb_read_request()

The glb_read_request() hook is called after the client request has been read. This means that you can access the request headers, and the request URL. However, remap rules has not yet been applied, so the URL may not be the final URL, or even complete.

glb_pre_remap()

This hook may not be particularly useful in Cripts, as remap rules are not applied here yet as well. We’ve added it for completeness.

glb_post_remap()

The glb_post_remap() hook is called after remap rules have been applied. This is the closest to the do_remap() hook in remap rules.

glb_cache_lookup()

This is identical to the do_cache_lookup() hook in remap rules.

glb_send_request()

This is identical to the do_send_request() hook in remap rules.

glb_read_response()

This is identical to the do_read_response() hook in remap rules.

glb_send_response()

This is identical to the do_send_response() hook in remap rules.

glb_txn_close()

This is identical to the do_txn_close() hook in remap rules.

glb_init()

This callback is called when the plugin is loaded. This is where you can setup any global state that you need etc.