This is an automated email from the ASF dual-hosted git repository.
zwoop pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 1e0f57495b Adding Cripts documentation structure (#11359)
1e0f57495b is described below
commit 1e0f57495ba82fdf668917cec8eba91ccbbe9aac
Author: Leif Hedstrom <[email protected]>
AuthorDate: Wed May 15 16:47:50 2024 -0600
Adding Cripts documentation structure (#11359)
---
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
