Name Date Size #Lines LOC

..23-Jun-2020-

include/H22-Jun-2019-

test/H22-Jun-2019-

README.txtH A D22-Jun-20193.9 KiB133104

TESTPLAN.txtH A D22-Jun-20192.5 KiB7559

psi.cH A D20-Aug-201928.7 KiB991556

thread.cH A D22-Jun-20193.9 KiB179125

thread.hH A D22-Jun-20192.1 KiB8134

README.txt

1
2	Thread pool sample plugin for SDK 3.0
3	-------------------------------------
4
5List of files:
6==============
7 Plugin
8 ------
9 - psi.c : proxy side include plugin
10 - thread.h : thread pool header
11 - thread.c : thread pool implementation
12
13 Tools for testing
14 -----------------
15 - include/gen.c : utility to generate text files of various size
16 - include/gen_inc.sh : script to generate include files for testing
17
18 - test/SDKTest/psi_server.c : SDKTest server plugins to test psi
19 - test/SDKTest/SDKtest_server.config : SDKTest config file
20
21
22Description
23===========
24 The plugin looks for the specific header "X-Psi" in the OS HTTP response.
25 If this header is found, and if the document is of type text/html,
26 the plugin parses the response body to find include tags: "<--include=filename-->".
27
28 When an include tag is found, the plugin substitutes it by the content
29 of the file `filename`.
30
31 Filename must be a simple filename. It can not contain a path (relative or absolute).
32
33 Example:
34 --------
35 The OS sends the following HTTP response:
36	HTTP/1.0 200 OK\r\n
37	Content-Type: text/html\r\n
38	X-Psi: true\r\n
39	\r\n\r\n
40	<HTML>
41	My html source code
42	<!--include=my_include.txt-->
43	Some more html code
44	</HTML>
45
46 The text file 'include.txt' on the proxy filesystem contains:
47	include content line 1
48	include content line 2
49	include content line 3
50
51 The response processed by the proxy and finally sent to the client is:
52	HTTP/1.0 200 OK\r\n
53	Content-Type: text/html\r\n
54	X-Psi: true\r\n
55	\r\n\r\n
56	<HTML>
57	My html source code
58	include content line 1
59	include content line 2
60	include content line 3
61	Some more html code
62	</HTML>
63 Note that the content of the 'include.txt' file is now inserted into
64 the body of the HTML response.
65
66
67Architecture
68============
69
70 Pool of threads
71 ---------------
72 The psi plugin uses a pool of threads to make system blocking calls (access to disk).
73 This is to avoid blocking a TS thread and slowing down the whole TS.
74
75 High level algorithm:
76 --------------------
77 0. At init time, the plugin spawns threads.
78 1. The plugin scans any HTTP response message header for the specific header X-Psi.
79 2. If found, it sets up a transformation.
80 3. The transformation parses the HTML content.
81 4. When an include tag is found, the plugin creates a job and put it into
82    the thread's queue of jobs.
83 5. Then it goes into an inactive mode, waiting for the job to get done by a thread.
84 6. A thread picks up the job. Reads the file from the disk (blocking system call).
85    Then reenables the transformation.
86 7. The transformation insert the content of the file into the HTML body.
87 8. Go to step 8.
88
89
90
91Plugin Installation
92===================
93 Add a line to Traffic Server plugin.config with the name of the plugin: psi.so
94 No arguments required.
95
96 The files to include must be located under the directory <plugin_path>/include
97 <plugin_path> is the path where the psi.so library is located
98 (by default $TS_HOME/etc/trafficserver/plugins)
99
100 Start TS as usual. Now any HTTP response with the X-Psi headers will be processed
101 by the PSI plugin.
102
103
104
105Plugin Testing
106==============
107
108 Sample include file generation
109 ------------------------------
110 A basic utility ('gen')to generate files to be inserted is provided
111 in the directory thread_pool/include.
112 This create text files of various sizes.
113 Compile gen the execute gen_inc.sh to generate files:
114 > cd include
115 > make
116 > gen_inc.sh
117
118 Load
119 ----
120 SDKTest can be used to test this plugin. SDKTest allows to simulate:
121  - synthetic clients sending requests
122  - a synthetic origin server
123
124 The synthetic origin server has to be customized in order to send back
125 responses that contains the specific 'X-Psi' header.
126 This is done through a SDKTest server plugin.
127
128 The rate of responses with X-Psi header is configurable thru a SDKTest config file.
129
130 A SDKTest server plugin as well as a SDKTest configuration file
131 are provided in the directory thread_pool/test/SDKTest.
132 Refer to the SDKTest manual for detailed setup instructions.
133