bneradt commented on code in PR #10191: URL: https://github.com/apache/trafficserver/pull/10191#discussion_r1320075256
########## src/cripts/README.md: ########## @@ -0,0 +1,453 @@ +# 1. Cripts + +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. + +ToDo: This document is not 100% updated with all features, but is at least a starting point. + +- [1. Cripts](#1-cripts) +- [2. Building Cripts](#2-building-cripts) + - [2.1. Building a Cript](#21-building-a-cript) + - [2.2. Lint: Validating a Cript](#22-lint-validating-a-cript) + - [2.3. Clang-tidy](#23-clang-tidy) +- [3. Writing Cripts](#3-writing-cripts) + - [3.1. Data types](#31-data-types) + - [3.2. Hooks](#32-hooks) + - [3.3. Processing and modifying headers](#33-processing-and-modifying-headers) + - [3.4. Processing and modifying URLs](#34-processing-and-modifying-urls) + - [3.4.1. Special case: Cache Key URL](#341-special-case-cache-key-url) + - [3.5. Accessing and modifying connections](#35-accessing-and-modifying-connections) + - [3.6. Overridable configurations](#36-overridable-configurations) + - [3.7. Pattern and identity matching](#37-pattern-and-identity-matching) + - [3.8. Cryptography functions](#38-cryptography-functions) + - [3.9. Various other utilities](#39-various-other-utilities) + - [3.10. Transaction contexts](#310-transaction-contexts) + - [3.10.1. Instance data (parameters)](#3101-instance-data-parameters) + - [3.10.2. Transaction data](#3102-transaction-data) +- [4. Plugins Cript can mimic or replace](#4-plugins-cript-can-mimic-or-replace) + - [4.1. conf\_remap](#41-conf_remap) + - [4.2. cachekey](#42-cachekey) + - [4.3. header\_rewrite](#43-header_rewrite) + - [4.4. regex\_remap](#44-regex_remap) + - [4.5. geoip\_acl and maxmind\_acl](#45-geoip_acl-and-maxmind_acl) + - [4.6. tcpinfo](#46-tcpinfo) Review Comment: Is this an autogenerated table of contents? If so, to keep it updated, lets add `<!---` describing how to generate it. I do this in the yahoo/proxy-verifier README.md: https://github.com/yahoo/proxy-verifier/blob/e0f644464018198e5e0c248dbe40918eacb55ebb/README.md?plain=1#L1-L12 ########## src/cripts/README.md: ########## @@ -0,0 +1,453 @@ +# 1. Cripts + +Cripts, C-Scripts, is a set of wrappers and include files, for making simple ATS Review Comment: Suggest: `, for making` -> `that make` ########## src/cripts/README.md: ########## @@ -0,0 +1,453 @@ +# 1. Cripts + +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. + +ToDo: This document is not 100% updated with all features, but is at least a starting point. + +- [1. Cripts](#1-cripts) +- [2. Building Cripts](#2-building-cripts) + - [2.1. Building a Cript](#21-building-a-cript) + - [2.2. Lint: Validating a Cript](#22-lint-validating-a-cript) + - [2.3. Clang-tidy](#23-clang-tidy) +- [3. Writing Cripts](#3-writing-cripts) + - [3.1. Data types](#31-data-types) + - [3.2. Hooks](#32-hooks) + - [3.3. Processing and modifying headers](#33-processing-and-modifying-headers) + - [3.4. Processing and modifying URLs](#34-processing-and-modifying-urls) + - [3.4.1. Special case: Cache Key URL](#341-special-case-cache-key-url) + - [3.5. Accessing and modifying connections](#35-accessing-and-modifying-connections) + - [3.6. Overridable configurations](#36-overridable-configurations) + - [3.7. Pattern and identity matching](#37-pattern-and-identity-matching) + - [3.8. Cryptography functions](#38-cryptography-functions) + - [3.9. Various other utilities](#39-various-other-utilities) + - [3.10. Transaction contexts](#310-transaction-contexts) + - [3.10.1. Instance data (parameters)](#3101-instance-data-parameters) + - [3.10.2. Transaction data](#3102-transaction-data) +- [4. Plugins Cript can mimic or replace](#4-plugins-cript-can-mimic-or-replace) + - [4.1. conf\_remap](#41-conf_remap) + - [4.2. cachekey](#42-cachekey) + - [4.3. header\_rewrite](#43-header_rewrite) + - [4.4. regex\_remap](#44-regex_remap) + - [4.5. geoip\_acl and maxmind\_acl](#45-geoip_acl-and-maxmind_acl) + - [4.6. tcpinfo](#46-tcpinfo) + +# 2. Building Cripts + +Cripts needs the `{fmt}` and `PCRE2` libraries and include files. We currently only +build cripts when explicitly enabled, and only using `cmake``. + +## 2.1. Building a Cript + +At the moment, building Cripts is the same as building any other ATS plugin, using +either existing build system or tooling such as `tsxs`. + +``` +tsxs -lcript -o cript_test.so cript_test.cc +``` + +This will read the Cript file cript_test.cc and produce a cript_test.so plugin, that can be +loaded in ATS via remap.config: + +``` +map https://example.com https://origin.example.com @plugin=cript_test.so +``` + +## 2.2. Lint: Validating a Cript + +TBD: I have the beginning of this tool, will land it later. + +## 2.3. Clang-tidy + +A custom clang-tidy configuration is provided with this patch, and I've run all +code through clang-tidy with this configuration. + +# 3. Writing Cripts + +Cripts follow the same basic model of how ATS splits up transaction processing +into what we call "hooks". A hook is essentially a callback mechanism, where +custom code can be injected into the ATS core via plugins. + +The Cript language itself is essentially C++17, except it imposes some serious, +but important, limitations on what can and can not be used. Albeit we call this +a scripting language, it's truly compiled into regular, reloadable ATS plugins. + +To start off with, we'll show a very basic Cript, to get an idea of what to +expect: + +``` Review Comment: Lets tell markdown this is c++ code: ```md ```cpp ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
