plugins/experimental/fastcgi/src/Readme

-----------------------------------------------------------------------------
Coding convention and formatting in VS Code:
   Using below config and store it in settings.json :
    {
    "C_Cpp.clang_format_path": "oathto/trafficserver-7.1.1/.git/fmt/20160415/clang-format/clang-format.linux",
    "editor.formatOnSave": true,
    "editor.formatOnType": true,
    "C_Cpp.intelliSenseEngine": "Default"
    }

Download the ATS clang-format binary ,find the url from path/to/trafficserver/tools/git/pre-commit
Extract the file and set the flag  "C_Cpp.clang_format_path" to file path.

2. Adding pre-commit hook :
   Copy the file path/to/trafficserver/tools/git/pre-commit under .git/hook/ directory.
   This will does the formatting every time does a commit.

-----------------------------------------------------------------------------

-----------------------------------------------------------------------------
Build and Install cmd =

#building CPP ats_fastcgi.so

```bash
set -e

# Update the path below for your system
ats_dir="/path/to/trafficserver-source/"

tsxs -o ats_fastcgi.so \
     -c ats_fastcgi.cc \
     -L "${ats_dir}lib/" \
     -I "${ats_dir}lib" \
     -I "${ats_dir}lib/cppapi/include/" \
     -c ats_fcgi_client.cc \
     -latscppapi

# Remember the tsxs path here and use it below
# (for the case where the sudo context doesn't know about tsxs)
mtsxs=$(which tsxs)

sudo $mtsxs -o ats_fastcgi.so  -i
```

OR Build and install using Makefile utility:
  Before doing make Plz set below directories.
# 1. ATS_SRC		--either set or export env variable path to traffic server src directory
# 2. ATS_EXEC       --either set or export env variable path to traffic server exec directory

  Afterwords command, $> make && sudo -E make install
  For example:
  make ATS_SRC=/home/oschaaf/code/apache/trafficserver ATS_EXEC=/usr/local/ CPPFLAGS=-std=c++11

------------------------------------------------------------------------------

ATS (Apache Traffic Server) FastCGI Plugin
------------------------------------------------------------------------------

This plugin collapses connections with identical CacheUrl/EffectiveUrl.

If an entry was created for a given CacheUrl/EffectiveUrl in our global hashTable,
successive GET requests with identical CacheUrl/EffectiveUrl will be blocked in
POST_REMAP hook until the hash entry was removed.  (POST_REMAP hook is the last
hook before 'cache lookup')

For requests going into 'cache lookup' stage,
  if CacheLookupStatus is HIT_FRESH,
    hash entry will be removed at earliest possible time.

For requests going into 'read server response header' stage,
  if response is not 200 OK,
    hash entry will be removed at earliest possible time.
  if response is public cacheable, (by checking 'Expires' header and 'Cache-Control' header with 'public' & 'max-age=...' values),
    if proxy.config.cache.enable_read_while_writer is enabled,
      hash entry will be removed at earliest possible time.
    else
      hash entry will be removed in TXN_CLOSE hook.
  if response is not public cacheable,
    we will update hash entry with a special value to let successive requests pass collapsed check,
    this special hash entry will be removed in TXN_CLOSE hook if value of keep_pass_record_time is 0,
    else it will be added into a list with timeout and removed by later collapsed requests.

To view full state diagram, please view state.png


CONFIGURATION

To have trafficserver use this plugin, add a line for 'ats_fastcgi.so' in the 'plugin.config' file.
The plugin can be configured with only 1 argument, which is location of its configuration file.

Example plugin.config:
    ats_fastcgi.so conf/ats_fastcgi/ats_fastcgi_XXXNAME.config

This plugin can be added in remap.config as well.
Thus, it can have different configurations or only be enabled/disabled for specific remap rules.
If the only argument for this plugin is "0" or "1", it means just "disable" or "enable" this plugin with default config value.

Example remap.config:
    map http://no-collapse1.www.example.com/ http://www.example.com/ @plugin=ats_fastcgi.so @pparam=0
    map http://no-collapse2.www.example.com/ http://www.example.com/ @plugin=ats_fastcgi.so @pparam=conf/collapsed_connection/disable.config

Its configuration file can have 5 configurable options:
    CONFIG proxy.config.http.fcgi.enabled INT 1
    CONFIG proxy.config.http.fcgi.host.hostname STRING localhost
    CONFIG proxy.config.http.fcgi.host.server_ip  STRING 127.0.0.1
    CONFIG proxy.config.http.fcgi.host.server_port STRING 60000
    CONFIG proxy.config.http.fcgi.host.root_directory STRING /
    CONFIG proxy.config.http.fcgi.host.min_connections INT 2
    CONFIG proxy.config.http.fcgi.host.max_connections INT 16
    CONFIG proxy.config.http.fcgi.host.max_requests INT 1000
    CONFIG proxy.config.http.fcgi.host.request_queue_size INT 250

Meaning of these configurable options:
    enabled
        enable fcgi Server or not, useful in remap rules if we want to disable/enable specific remap rules.
    hostname
        hostname of the fcgi server in string format e.g localhost
    server_ip
        IP of the fcgi server machine in string format e.g 127.0.0.1
    server_port
        fcgi server port number in string format e.g 60000
    root_directory
        root directory path from where fcgi server will server resources/web_contents
    min_connections
        min number of connections plugin will open to the php server
    max_connections
        max number of connections plugin will make to the php server
    max_requests
        max number of requests per connection plugin will allow to the php server
    request_queue_size
        max requests queue size limit



 PHP REQUIREMENTS

  This section outlines build requirements for different OS
  distributions. This may be out of date compared to the on-line
  requirements at

  <https://cwiki.apache.org/confluence/display/TS/Building>.

  As of ATS v7.0.0 and later, gcc 4.8.1 or later is required, since we now use
  and require the C++11 standard.

  a. download libfcgi-dev package :i.e libfcgi-dev_2.4.0-8.4+b1_arm64.deb from https://packages.debian.org/sid/arm64/libfcgi-dev/download

  b. download php7.0-cli php7.0-fpm with :  sudo apt-get install php7.0-cli php7.0-fpm


Starting the php fastcgi server:

$ > ./bin/php-fastcgi start      //this will start the server on port 60000

Note: Place sample scripts from  ./examples/*  files to /var/www/ directory to access php scripts from browser. As php server uses default location as /var/www/html/*.php




Using Profiler:
    1. To use profiler, set the ATS_FCGI_PROFILER flag to true inside ats_fastcgi.h file.

    2. Place  below piece of code inside functions to record profiling.

        #if ATS_FCGI_PROFILER
            ats_plugin::ProfileTaker profile_taker(&profiler, "functinName", (std::size_t)&plugin, "B");
        #endif