You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by cm...@apache.org on 2024/05/16 14:24:22 UTC
(trafficserver) 08/08: Adding Cripts documentation structure (#11359)
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 <zw...@apache.org>
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