This is an automated email from the ASF dual-hosted git repository. cmcfarlen pushed a commit to branch 10.0.x in repository https://gitbox.apache.org/repos/asf/trafficserver.git
commit 05f9b4e0fd9378ee66609c52832fe28074ce5367 Author: Leif Hedstrom <[email protected]> AuthorDate: Wed May 15 16:47:50 2024 -0600 Adding Cripts documentation structure (#11359) (cherry picked from commit 1e0f57495ba82fdf668917cec8eba91ccbbe9aac) --- doc/developer-guide/cripts/cripts-bundles.en.rst | 26 ++ .../cripts/cripts-connections.en.rst | 26 ++ doc/developer-guide/cripts/cripts-examples.en.rst | 26 ++ doc/developer-guide/cripts/cripts-headers.en.rst | 163 ++++++++++++ doc/developer-guide/cripts/cripts-matcher.en.rst | 26 ++ doc/developer-guide/cripts/cripts-misc.en.rst | 26 ++ doc/developer-guide/cripts/cripts-overview.en.rst | 286 +++++++++++++++++++++ doc/developer-guide/cripts/cripts-urls.en.rst | 118 +++++++++ doc/developer-guide/cripts/cripts-variables.en.rst | 155 +++++++++++ doc/developer-guide/cripts/index.en.rst | 36 +++ doc/developer-guide/index.en.rst | 1 + 11 files changed, 889 insertions(+) diff --git a/doc/developer-guide/cripts/cripts-bundles.en.rst b/doc/developer-guide/cripts/cripts-bundles.en.rst new file mode 100644 index 0000000000..c50efe31db --- /dev/null +++ b/doc/developer-guide/cripts/cripts-bundles.en.rst @@ -0,0 +1,26 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-bundles: + +Bundles +******* diff --git a/doc/developer-guide/cripts/cripts-connections.en.rst b/doc/developer-guide/cripts/cripts-connections.en.rst new file mode 100644 index 0000000000..c0ee65105c --- /dev/null +++ b/doc/developer-guide/cripts/cripts-connections.en.rst @@ -0,0 +1,26 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-connections: + +Connections +*********** diff --git a/doc/developer-guide/cripts/cripts-examples.en.rst b/doc/developer-guide/cripts/cripts-examples.en.rst new file mode 100644 index 0000000000..a94c885f9f --- /dev/null +++ b/doc/developer-guide/cripts/cripts-examples.en.rst @@ -0,0 +1,26 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-examples: + +Examples +******** diff --git a/doc/developer-guide/cripts/cripts-headers.en.rst b/doc/developer-guide/cripts/cripts-headers.en.rst new file mode 100644 index 0000000000..46fe2b96bf --- /dev/null +++ b/doc/developer-guide/cripts/cripts-headers.en.rst @@ -0,0 +1,163 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-headers: + +Headers +******* + +Just like the URL objects, all header objects are managed and owned by the Cripts +system, and must always be borrowed. The pattern for this is as follows: + +.. code-block:: cpp + + borrow req = Client::Request::get(); + + auto foo = req["X-Foo"]; + +There are four types of headers that can be borrowed: + +===================== =========================================================================== +Header Object Description +===================== =========================================================================== +``Client::Request`` The client request headers. Always available. +``Client::Response`` The client response headers. +``Server::Request`` The server request headers. +``Server::Response`` The server response headers. +===================== =========================================================================== + +Note that for all of these headers, except the ``Client::Request``, the headers are not +available until the respective hook is called. For example, the ``Client::Response`` headers +are not available until the response headers are received from the origin server or cache lookup. + +Assigning the empty value (``""``) to a header will remove it from the header list. For example: + +.. code-block:: cpp + + borrow req = Client::Request::get(); + + req["X-Foo"] = "bar"; // Set the header + req["X-Fie"] = ""; // Remove the header + +A header can also be removed by using the ``erase`` method, which is a little more explicit: + +.. code-block:: cpp + + borrow req = Client::Request::get(); + + req.erase("X-Foo"); + +.. _cripts-headers-iterators: + +Iterators +--------- + +A common use pattern with the header values is to iterate (loop) over all of them. This is easily done with +a pattern such as the following example: + +.. code-block:: cpp + + borrow req = Client::Request::get(); + + for (auto header : req) { + CDebug("Header: {}: {}", header, req[header]); // This will print all headers and their values + } + +The request object implements a standard C++ style iterator, so any type of loop that works with +standard C++ iterators will work with the request object. + +.. _cripts-headers-methods: + +Methods +------- + +In addition to holding all the request headers, the request objects also holds the ``method`` verb. +For the ``Client::Request`` object, this is the client request method (GET, POST, etc.). For the +``Server::Request`` object, this is the method that will be sent to the origin server (GET, POST, etc.). + +Cripts provides the following convenience symbols for common methods (and performance): + +========================== ====================================================================== +Method Description +========================== ====================================================================== +``Cript::Method::GET`` The GET method. +``Cript::Method::POST`` The POST method. +``Cript::Method::PUT`` The PUT method. +``Cript::Method::DELETE`` The DELETE method. +``Cript::Method::HEAD`` The HEAD method. +``Cript::Method::OPTIONS`` The OPTIONS method. +``Cript::Method::CONNECT`` The CONNECT method. +``Cript::Method::TRACE`` The TRACE method. +========================== ====================================================================== + +These symbols can be used to compare against the method in the request object. For example: + +.. code-block:: cpp + + borrow req = Client::Request::get(); + + if (req.method == Cript::Method::GET) { + // Do something + } + +.. _cripts-headers-status: + +Status +------ + +The two response objects also hold the status code of the response. This includes: + +========================== ====================================================================== +Member Description +========================== ====================================================================== +``status`` The status code of the response. E.g. ``200``. +``reason`` The reason phrase of the response. E.g. ``OK``. +``cache`` The cache status of the response. E.g. ``miss``. +========================== ====================================================================== + +Of these, the first two are pretty self explanatory, but the ``cache`` status is a bit more +complex. This is a string that represents the cache status of the response. The possible values +are: + +========================== ====================================================================== +Value Description +========================== ====================================================================== +``miss`` The response was not found in the cache. +``hit-stale`` The response was found in the cache, but it was stale. +``hit-fresh`` The response was found in the cache and is fresh. +``skipped`` We skipped cache lookup completely +========================== ====================================================================== + +This status can be used to determine if the response was found in the cache, and if so, if it was +fresh or stale. Example usage of the cache status: + +.. code-block:: cpp + + do_read_response() { + borrow resp = Server::Response::get(); + + if (resp.cache == "miss") { + // Do something + } + } + +.. diff --git a/doc/developer-guide/cripts/cripts-matcher.en.rst b/doc/developer-guide/cripts/cripts-matcher.en.rst new file mode 100644 index 0000000000..17876d83ec --- /dev/null +++ b/doc/developer-guide/cripts/cripts-matcher.en.rst @@ -0,0 +1,26 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-matchers: + +Matchers +******** diff --git a/doc/developer-guide/cripts/cripts-misc.en.rst b/doc/developer-guide/cripts/cripts-misc.en.rst new file mode 100644 index 0000000000..4590e9ad8b --- /dev/null +++ b/doc/developer-guide/cripts/cripts-misc.en.rst @@ -0,0 +1,26 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-misc: + +Miscelanious +************ diff --git a/doc/developer-guide/cripts/cripts-overview.en.rst b/doc/developer-guide/cripts/cripts-overview.en.rst new file mode 100644 index 0000000000..0a56371f0d --- /dev/null +++ b/doc/developer-guide/cripts/cripts-overview.en.rst @@ -0,0 +1,286 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-overview: + +Overview +******** + +Cripts, *C-Scripts*, is a set of wrappers and include files for making simple ATS +plugins easy to generate, modify or create from scratch. A key design here is that +the Code is the Configuration, i.e. the intent really is to have a custom Cript file +for every remap rule in the running system. + +Cripts can also be seen as the scripting configuration language for many custom +ATS setups. ATS can even load Cripts directly, if so desired. See the section on +using Cripts for more information. + +.. _cripts-overview-building: + +Building +======== + +Cripts is built as a separate library, which can be enabled with ``-DENABLE_CRIPTS=ON`` +when configuring *cmake*. Building a Cript itself is just like compiling a normal +ATS plugin, except it will also need the Cripts library linked in: ``-lcripts``. + +Plugins built using this method loads exactly like any other ATS plugin, and can be +used in the same way. The only difference is that the plugin will be a lot simpler +to write and maintain. + +.. _cripts-overview-usage: + +Usage +===== + +The easiest way to use Cripts is to let ATS itself compile and load the Cript. This +requires three things: + +1. The :file:`records.yaml` must have the ``plugin.compiler_path`` set to a build script. +2. The remap rule must specify the Cript file to load. +3. The Cript file must be in either the configuration or plugin installation directory. + +The first step is to set the plugin.compiler_path in the records.yaml file. For example: + +.. code-block:: yaml + + ts: + plugin: + compiler_path: /opt/ats/bin/compiler.sh + +The second step is to specify the Cript file in the remap rule. For example: + +:: + + map https://www.example.com https://origin.example.com \ + @plugin=example.cript + +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: + +.. code-block:: cpp + + #include <cripts/Preamble.hpp> + + do_remap() + { + borrow url = Client::URL::get(); + + url.query.keep({"foo", "bar"}); + } + + #include <cripts/Epilogue.hpp> + +In this example, note that both the Preamble and Epilogue are explicitly included. +This is strictly necessary for the Cript to compile and load correctly. + +.. _cripts-overview-usage-compiler: + +Compiler +-------- + +The compiler is a simple shell script that compiles the Cript file into a shared object +file. The script is responsible for setting up the environment and calling the compiler +with the correct arguments. The script must be executable and readable by the ATS process. + +Two arguments are always given to the compiler script: + +1. The path to the Cript file. +2. The path to the shared object file to create. + +An example compiler script is provided in the ATS source directory, but an example is +also shown below: + +.. code-block:: bash + + #!/usr/bin/env bash + + # This was done for a Mac, may need to be adjusted for other platforms. + ATS_ROOT=/opt/ats + CXX=clang++ + CXXFLAGS="-std=c++20 -I/opt/homebrew/include -undefined dynamic_lookup" + STDFLAGS="-shared -fPIC -Wall -Werror -I${ATS_ROOT}/include -L${ATS_ROOT}/lib -lcripts" + + SOURCE=$1 + DEST=$2 + + ${CXX} ${CXXFLAGS} ${STDFLAGS} -o $DEST $SOURCE + +The example in the ATS source directory is more complex, as it also provides a basic +cache for the shared object files. This is useful for large setups with many Cript files. +In fact, moving the compilation details to be separate from the ATS process is a good +idea with a lot of flexibility for the user. + +.. _cripts-overview-hooks: + +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. + +.. _cripts-overview-hooks-do-remap: + +do_remap() +^^^^^^^^^^ + +The ``do_remap()`` hook is called when a remap rule matches. This is the main hook for +modifying the request or response. In ATS plugin terms, this is the main entry point +for all remap plugins. + +.. _cripts-overview-hooks-do-post-remap: + +do_post_remap() +^^^^^^^^^^^^^^^ + +The ``do_post_remap()`` hook is called after the remap has been done. This can sometimes +be useful for modifying the request details *after* the remap has been done. More often +than not, this hook is not needed. + +.. _cripts-overview-hooks-do-send-response: + +do_send_response() +^^^^^^^^^^^^^^^^^^ + +The ``do_send_response()`` hook is called when the response is ready to be sent to the +client. In this hook you can modify or add to the response headers for example. + +.. _cripts-overview-hooks-do-cache-lookup: + +do_cache_lookup() +^^^^^^^^^^^^^^^^^ + +The ``do_cache_lookup()`` hook is called when a cache lookup is done. This can be useful +to take action on the response from the cache, once you know if the cache lookup succeeded +or not. + +.. _cripts-overview-hooks-do-send-request: + +do_send_request() +^^^^^^^^^^^^^^^^^ + +The ``do_send_request()`` hook is called when the request is ready to be sent to the +origin server. This is the main hook for modifying the request to the origin server. + +.. _cripts-overview-hooks-do-read-response: + +do_read_response() +^^^^^^^^^^^^^^^^^^ + +The ``do_read_response()`` hook is called when the response is being read from the origin +server. This is the main hook for modifying the response from the origin server. + +.. _cripts-overview-hooks-do-txn-close: + +do_txn_close() +^^^^^^^^^^^^^^ + +The ``do_txn_close()`` hook is called when the transaction is closed. + +Instance Hooks +-------------- + +In addition to these normal hooks, there are also three hooks that are used for setting +up a cript and remap plugin instance. This is primarily useful when writing traditional +remap plugins in Cripts. + +**Note:** These hooks are not needed for most Cripts that are used in remap rules. + +.. _cripts-overview-hooks-do-init: + +do_init() +^^^^^^^^^ + +The ``do_init()`` hook is called once when the plugin is loaded. + +.. _cripts-overview-hooks-do-create-instance: + +do_create_instance() +^^^^^^^^^^^^^^^^^^^^ + +The ``do_create_instance()`` hook is called when a new instance of the plugin is created. +Of particular interest here is the ability to read and save the instance parameters that +can be provided in the remap rule (e.g. ``@plugin=example.cript @pparam=value``). + +.. _cripts-overview-hooks-do-delete-instance: + +do_delete_instance() +^^^^^^^^^^^^^^^^^^^^ + +The ``do_delete_instance()`` hook is called when the instance is deleted. + +.. _cripts-overview-instance-data: + +Instance Data +============= + +Instance data is a way to store data that is specific to a plugin instance. This is +primarily useful when writing traditional remap plugins in Cripts using the instance hooks. +Instance data is stored in a map that is specific to the plugin instance, and each slot +is initially a string, as provided by the remap rule. + +Best way to understand this is to look at an example: + +.. code-block:: cpp + + #include <cripts/Preamble.hpp> + + do_create_instance() + { + if (instance.size() == 3) { + auto first = float(AsString(instance.data[0])); + auto second = integer(AsString(instance.data[1])); + auto third = boolean(AsString(instance.data[3])); + + instance.data[0] = first; + instance.data[1] = second; + instance.data[2] = third; + } + } + + do_remap() + { + auto first = AsFloat(instance.data[0]); + auto second = AsInteger(instance.data[1]); + auto third = AsBoolean(instance.data[3]); + + // Use the instance parameter here in the Cript rules. + } + + #include <cripts/Epilogue.hpp> + +As you can see, it takes a little bit of work to manage these instance parameters, which +is a limitation of the language constructs in Cripts. But writing plugins like this is for +more advanced users, and users just writing simple Cripts for their remap rules will not +need to worry about this. diff --git a/doc/developer-guide/cripts/cripts-urls.en.rst b/doc/developer-guide/cripts/cripts-urls.en.rst new file mode 100644 index 0000000000..c9877abe36 --- /dev/null +++ b/doc/developer-guide/cripts/cripts-urls.en.rst @@ -0,0 +1,118 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-urls: + +Urls +**** + +The URL objects are managed and own by the Cripts subsystem, and as such +must always be borrewed. The pattern for this is as follows: + +.. code-block:: cpp + + borrow url = Client::URL::get(); + + auto path = url.path; + +There are four types of URLs that can be borrowed: + +=================== ============================================================================= +URL Object Description +=================== ============================================================================= +``Client::URL`` The client request URL, as it currently stands (may be modified). +``Pristine:URL`` The pristine client request URL, as it was coming into the ATS server. +``Parent::URL`` The outgoing server URL, as sent to the next server (parent or origin). +``Cache::URL`` The cache URL, which will be used for the cache lookups. +=================== ============================================================================= + +These URLs all have the same methods and properties, but they are used in different +hooks and have different meanings. The ``Client::URL`` is the most commonly used URL, +which you will also modify in the tradtional remapping use case; for example changing +the ``path`` or ``host`` before further processing. + +.. _cripts-urls-components: + +Components +---------- + +Every URL object has the following components: + +=============== ================================================================================= +Component Description +=============== ================================================================================= +``host`` The host name. +``port`` The port number, this is an integer value. +``scheme`` The scheme (http, https, etc). +``path`` The path. +``query`` The query. +=============== ================================================================================= + +These components can be accessed and modified as needed. Both the ``path`` and ``query`` are +strings, and can be manipulated as such. However, they are both also considered list of their +constituent parts, and can be accessed as such. For example, to get the first part of the path, +you can use the following: + +.. code-block:: cpp + + borrow url = Client::URL::get(); + + auto path = url.path; // This is the entire path + auto first = url.path[0]; // This is the first part of the path + +The same pattern applies for the query parameters, except they are key-value pairs, instead of +indexed in a list. To get the value of a specific query parameter, you can use the following: + +.. code-block:: cpp + + borrow url = Client::URL::get(); + + auto value = url.query["key"]; // This is the value of the key + +You can retreive the size of the path or query using the ``size()`` method, and you can clear +the path or query using the ``erase()`` method. To summarize the ``path`` and ``query`` components +have the following methods available to them: + +================= =============================================================================== +Method / access Description +================= =============================================================================== +Index [] Access a specific part of the path or query. +``size()`` Get the number of parts of the path or query. +``erase()`` Clears the component. Also available as ``clear()``. +``sort()`` Sorts the query parameters. **Note**: Only for query parameters. +``flush()`` Flushes any changes. This is rarely used, since Cripts will manage flushing. +================= =============================================================================== + +In addition, the query parameters ``erase()`` method can take a single key, or a list of keys to +remove specific parameters. It also allows specify a list of keys to keep, and will remove all other +keys. This is useful for filtering out unwanted query parameters. + +For example: + +.. code-block:: cpp + + borrow url = Client::URL::get(); + + url.query.erase("key"); // Removes the key from the query + url.query.erase({"key1", "key2"}); // Removes both keys from the query + url.query.erase({"key1", "key2"}, true); // Removes all keys except key1 and key2 + url.query.keep({"key1", "key2"}); // Same as previous diff --git a/doc/developer-guide/cripts/cripts-variables.en.rst b/doc/developer-guide/cripts/cripts-variables.en.rst new file mode 100644 index 0000000000..80e0e994de --- /dev/null +++ b/doc/developer-guide/cripts/cripts-variables.en.rst @@ -0,0 +1,155 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. highlight:: cpp +.. default-domain:: cpp + +.. _cripts-variables: + +Variables +********* + +Cripts supports a wide variety of variable types, and they can be used in many places. In +many cases, the variable types are automatically converted to the correct type, but in some +cases you may need to explicitly declare the variable. Most commonly you will declare a +variable using either ``auto`` or ``borrow``. The latter is used when working with a +complex object, like a URL or a header, that is managed by ATS itself. + +For ``auto`` variables, these are the most common types: + +=================== ================================================================================== +Type Description +=================== ================================================================================== +``integer`` A 64-bit signed integer. +``float`` A 64-bit floating point number. +``boolean`` A boolean value. +``string`` A string. +``string_view`` A string view. +=================== ================================================================================== + +Of these, ``string_view`` is perhaps the least familiar type, but it is the most commonly used +type of strings within ATS itself. As such, they are incredibly efficient to use. Again, most of the +time just declare your variables as ``auto`` and let the compiler figure out the type. + +.. _cripts-variables-strings: + +Strings +======= + +String and ``string_views`` are probably the types you will work with most. These types +have a number of methods that can be used to manipulate the string. Strings here are secretly +wrapped in standard C++ strings, and have all the methods that come with them. As an example, to +get the length of a string, you can use the ``size()`` method: + +.. code-block:: cpp + + borrow req = Client::Request::get(); + + if (req["Host"].size() > 3) { + // Do something + } + +Here's a list of methods available on strings: + +=================== ============================================================================= +Method Description +=================== ============================================================================= +``clear()`` Clear (empty) the string. +``empty()`` Check if the string is empty or not, returns ``true`` or ``false``. +``size()`` Return the length of the string. Also available as ``length()``. +``starts_with()`` Check if the string starts with a given string. +``ends_with()`` Check if the string ends with a given string. +``find()`` Find a string within the string. **TBD** +``rfind()`` Find a string within the string, starting from the end. **TBD** +``contains()`` Check if the string contains a given string. **TBD** +``substr()`` Get a substring of the string, arguments are ``start`` and ``end`` position. +``split()`` Split the string into a list of strings, using a delimiter. Returns a list. +``trim()`` Trim whitespace from the string. +``ltrim()`` Trim whitespace from the left of the string. +``rtrim()`` Trim whitespace from the right of the string. +``remove_prefix()`` Remove a prefix string from the string. This does not return a new string. +``remove_suffix()`` Remove a suffix string from the string. This does not return a new string. +``toFloat()`` Convert the string to a float. +``toBool()`` Convert the string to a boolean. +``toInteger()`` Convert the string to an integer. +``toFloat()`` Convert the string to a float. +=================== ============================================================================= + +In addition to this, there's a number of *matching* features in Cripts, which can be used together +with strings. These are covered in more detail in the :ref:`cripts-matcher` section. Of course, +regular comparisons such as ``==`` and ``!=`` are also available. + +**Note:** We'll continue to update features of Cripts as we start using it more in production. If you +have any suggestions or requests for strings (or any other data type), please let us know! + +.. _cripts-variables-configuration: + +Configuration Variable +====================== + +ATS has a flexible set of configurations, many of which can be accessed and modified using Cripts. +These configurations are, in ATS terms, what's called overridable. They all have a default value, +that is set globally via :file:`records.yaml`, but they are also overridable per transaction. + +Cript exposes this via the global ``proxy`` object, which is a map of all the configurations. +Best way to understand this is to look at an example: + +.. code-block:: cpp + + auto cache_on = proxy.config.http.cache.http.get(); + + if (cache_on > 0) { + proxy.config.http.ignore_server_no_cache.set(1); + } + +This is a pretty artificial example, but shows the name space of these configurations, and how they +match the documented ATS configuration names. + +.. _cripts-variables-control: + +Control Variable +================ + +ATS plugins (and Cripts) have access to a number of control functions that can be used to control +some behavior of ATS. This is exposed via the global ``control`` object. This object has a number of +variables that can be used to control the behavior of ATS. + +============================ ==================================================================== +Variable Description +============================ ==================================================================== +``control.cache.request`` Control the cache behavior for the request. +``control.cache.response`` Control the cache behavior for the response. +``control.cache.nostore`` Control the cache behavior for the no-store. +``control.logging`` Turn logging on or off. +``control.intercept`` Turn incepts on or off. +``control.debug`` Enable debugging (rarely used) +``control.remap`` Indicate whether remap matching is required or not. +============================ ==================================================================== + +All of these are controlled via a boolean value, and can be set to either ``true`` or ``false``, +the same ``.get()`` and ``.set()`` as for configuration variables. As an example, lets randomly +turn off logging for some percentage of requests: + +.. code-block:: cpp + + do_remap() { + if (Cript::random(1000) > 99) { + control.logging.set(false); // 10% log sampling + } + } diff --git a/doc/developer-guide/cripts/index.en.rst b/doc/developer-guide/cripts/index.en.rst new file mode 100644 index 0000000000..6a61611bd5 --- /dev/null +++ b/doc/developer-guide/cripts/index.en.rst @@ -0,0 +1,36 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. _developer-guide-cripts: + +Cripts +****** + +.. toctree:: + :maxdepth: 2 + + cripts-overview.en + cripts-variables.en + cripts-urls.en + cripts-headers.en + cripts-connections.en + cripts-matcher.en + cripts-misc.en + cripts-bundles.en + cripts-examples.en diff --git a/doc/developer-guide/index.en.rst b/doc/developer-guide/index.en.rst index c273039c94..c681318025 100644 --- a/doc/developer-guide/index.en.rst +++ b/doc/developer-guide/index.en.rst @@ -48,6 +48,7 @@ duplicate bugs is encouraged, but not required. logging-architecture/index.en internal-libraries/index.en plugins/index.en + cripts/index.en config-vars.en api/index.en continuous-integration/index.en
