This is an automated email from the ASF dual-hosted git repository.
wkaras 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 e226cc7fd1 Add Sphinx documentation for statichit plugin. (#11389)
e226cc7fd1 is described below
commit e226cc7fd16fb3c63143cb16c0f2010ddd8e25fd
Author: Walt Karas <[email protected]>
AuthorDate: Mon Jun 24 19:00:51 2024 -0400
Add Sphinx documentation for statichit plugin. (#11389)
* Add Sphinx documentation for statichit plugin.
Also remove obsolete readme file for statichit.
* Improve Au test for statichit plugin.
---
doc/admin-guide/plugins/index.en.rst | 4 +
doc/admin-guide/plugins/statichit.en.rst | 117 +++++++++++++++++++++
plugins/statichit/README.md | 38 -------
.../pluginTest/statichit/statichit.replay.yaml | 69 ++++++++++++
.../pluginTest/statichit/statichit.test.py | 43 ++++++--
5 files changed, 223 insertions(+), 48 deletions(-)
diff --git a/doc/admin-guide/plugins/index.en.rst
b/doc/admin-guide/plugins/index.en.rst
index 5e33fcf722..6254c4a309 100644
--- a/doc/admin-guide/plugins/index.en.rst
+++ b/doc/admin-guide/plugins/index.en.rst
@@ -67,6 +67,7 @@ Plugins that are considered stable are installed by default
in |TS| releases.
Regex Revalidate <regex_revalidate.en>
Remap Purge <remap_purge.en>
Remap Stats <remap_stats.en>
+ Static Hit <statichit.en>
Stats over HTTP <stats_over_http.en>
TCPInfo <tcpinfo.en>
Traffic Dump <traffic_dump.en>
@@ -136,6 +137,9 @@ Plugins that are considered stable are installed by default
in |TS| releases.
:doc:`Remap Stats <remap_stats.en>`
This global plugin adds remap stats to the stats.
+:doc:`Static Hit <statichit.en>`
+ Serve static content from proxy's local filesystem.
+
:doc:`Stats over HTTP <stats_over_http.en>`
Provide an HTTP interface to all |TS| statistics.
diff --git a/doc/admin-guide/plugins/statichit.en.rst
b/doc/admin-guide/plugins/statichit.en.rst
new file mode 100644
index 0000000000..f673fc9d15
--- /dev/null
+++ b/doc/admin-guide/plugins/statichit.en.rst
@@ -0,0 +1,117 @@
+.. _admin-plugins-statichit:
+.. include:: ../../common.defs
+
+Static Hit Plugin
+*****************
+
+.. 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.
+
+This is a simple plugin to serve static content from the proxy's local
filesystem. It shares some
+of the same functionality as the `healthchecks` plugin, but is a remap plugin
(thereby making it
+reloadable). When an object is served by the plugin (not from HTTP cache),
the plugin re-reads the
+current contents of the file containing the object data.
+
+When the plugin is invoked during remapping, if the transaction already has a
status other than OK, the plugin
+will ignore the transaction.
+
+These are the available options for the plugin:
+
+================= ======= ========= ====== ==============
+Long Name One Required? Has Description
+ Letter Value?
+ Name
+================= ======= ========= ====== ==============
+\-\-file-path -f Yes Yes File path. If the given path is
relative, it is relative to the |TS|
+ configuration directory. If
the specified file is a directory, it implies
+ \-\-disable-exact, and URL path
is appended to this directory path to get
+ the path for the file
containing the body. If the specified file is not a
+ directory, it should contain
the body.
+\-\-mime-type -m No Yes Defaults to "text/plain".
+\-\-max-age -a No Yes Defaults to "0". If the value
is not 0, it gives the number of seconds the
+ static body will remain fresh
when cache. (Including in the proxy's cache, if
+ enabled.)
+\-\-failure-code -c No Yes Defaults to "404" (NOT FOUND).
This response status will be returned if the
+ file which should contain the
body does not exist. This option is
+ particularly useful when
\-\-file-path specifies a directory.
+\-\-success-code -s No Yes Defaults to "200" (OK). This is
the response status when the static object is
+ successfully returned in the
transaction response.
+\-\-disable-exact -d No No Disable "exact" URL match.
"Exact" match, for this plugin, means the URL must
+ not include a path.
+================= ======= ========= ====== ==============
+
+When using long option names, the value can be specified by appending = and
then the value. `@pparam=\-\-max-age=5` for
+example. Otherwise, the value must be specified as the next pparam.
`@pparam=-a @pparam=5` for example.
+
+When exact match is enabled, if the request URL has a path, a response with
NOT FOUND status will be sent.
+
+Mime Headers in Responses with OK/200 Status
+============================================
+
+#. Content-Type. The value given with the \-\-mime-type parameter, or its
default value.
+#. Content-Length.
+#. Cache-Control. If \-\-max-age is 0, the value will be "no-cache".
Otherwise, the value will be "max-age=d", where
+ d stands for the value given with the \-\-max-age parameter.
+#. if \-\-max-age is not 0, Last-Modified is present, and gives the time the
static body was last cached.
+
+Metrics
+=======
+
+The plugin publishes the following metrics:
+
+======================== ====================================================
+Name Description
+======================== ====================================================
+statichit.response_bytes The total number of bytes emitted
+statichit.response_count The number of HTTP responses generated by the plugin
+======================== ====================================================
+
+remap.config Examples:
+======================
+
+Serve a request for /internal/healthcheck with the contents of the file
located at /var/run/trafficserver/healthcheck.txt.
+If the file is present, send with a Mime-type of text/plain. Also set the
Cache-Control: header to no-cache.
+
+| map /internal/healthcheck \\
+| \http://127.0.0.1 \\
+| @plugin=statichit.so
@pparam=\-\-file-path=/var/run/trafficserver/healthcheck.txt \\
+| @pparam=\-\-mime-type=text/plain \\
+| @pparam=\-\-success-code=200 \\
+| @pparam=\-\-failure-code=403 \\
+| @pparam=\-\-max-age=0 \\
+| @pparam=\-\-disable-exact
+
+Serve a request for content.example.com/content_xyz.txt with the contents of
the file content_bodies/content_xyz.txt
+under the |TS| configuration file directory (as content_bodies is meant to
imply a directory in this example).
+
+| map \http://content.example.com/content_xyz.txt \\
+| \http://127.0.0.1 \\
+| @plugin=statichit.so @pparam=\-\-file-path=content_bodies \\
+| @pparam=\-\-failure-code=404 \\
+| @pparam=\-\-max-age=604800
+
+Serve a request for content.example.com/content_abc.json with the contents of
the file content_bodies/content_xyz.txt
+under the |TS| configuration file directory (as content_bodies is meant to
imply a directory in this example)
+with a mime-type of application/json. Set cache-control to have a max-age of 7
days (604800 seconds).
+
+| map \http://content.example.com/content_abc.json \\
+| \http://127.0.0.1 \\
+| @plugin=statichit.so @pparam=\-\-file-path=content_bodies \\
+| @pparam=\-\-mime-type=application/json \\
+| @pparam=\-\-max-age=604800
+
+NOTE: The remap origin is never contacted because this plugin intercepts the
request and acts as the origin server. For that reason, the origin
specification must be syntactically valid and resolvable in DNS.
diff --git a/plugins/statichit/README.md b/plugins/statichit/README.md
deleted file mode 100644
index cb7001d525..0000000000
--- a/plugins/statichit/README.md
+++ /dev/null
@@ -1,38 +0,0 @@
-This is a simple plugin to serve static content from a local filesystem. It
shares some of the same functionality as the `healthchecks` plugin, but can be
used in the remap context(thereby making it reloadable). It does not use
fsnotify for watching the source files.
-
-If the file specified by the `--file-path` parameter is not found, the plugin
will return the status code specified
-by the `--failure-code` parameter, defaulting to a 404. If the file is found,
it will return the contents of the file
-setting the `Content-Type` header to the value specified on the `--mime-type`
parameter.
-
-Metrics
---------
-
-The plugin publishes the following metrics:
-
-statichit.response_bytes:
- The total number of bytes emitted
-statichit.response_count:
- The number of HTTP responses generated by the plugin
-
-Examples:
------------
-
-remap.config:
-```
-map /internal/healthcheck \
- http://127.0.0.1 \
- @plugin=statichit.so
@pparam=--file-path=/var/run/trafficserver/healthcheck.txt \
- @pparam=--mime-type=text/plain \
- @pparam=--success-code=200 \
- @pparam=--failure-code=403 \
- @pparam=--max-age=0
-
-map http://content.example.com/content.txt \
- http://127.0.0.1 \
- @plugin=statichit.so
@pparam=--file-path=/opt/ats/etc/trafficserver/static/content_source.txt \
- @pparam=--failure-code=404 \
- @pparam=--max-age=604800
-
-```
-
-NOTE: The remap origin is never contacted because this plugin intercepts the
request and acts as the origin server. For that reason, the origin
specification must be syntactically valid and resolvable in DNS.
diff --git a/tests/gold_tests/pluginTest/statichit/statichit.replay.yaml
b/tests/gold_tests/pluginTest/statichit/statichit.replay.yaml
index 175435ae48..4dbb3b10de 100644
--- a/tests/gold_tests/pluginTest/statichit/statichit.replay.yaml
+++ b/tests/gold_tests/pluginTest/statichit/statichit.replay.yaml
@@ -166,3 +166,72 @@ sessions:
- [ Cache-Control, { value: no-cache, as: equal } ]
- [ Content-Type, { value: text/plain, as: equal } ]
- [ Server, { value: ATS, as: contains } ]
+
+ - client-request:
+ method: GET
+ url: /path
+ version: '1.1'
+ headers:
+ fields:
+ - [ Host, fqdn7 ]
+ - [ uuid, 8 ]
+
+ proxy-response:
+ status: 200
+ headers:
+ fields:
+ - [ Content-Length, { value: 19, as: equal } ]
+ - [ Cache-Control, { value: no-cache, as: equal } ]
+ - [ Content-Type, { value: text/plain, as: equal } ]
+ - [ Server, { value: ATS, as: contains } ]
+ content:
+ encoding: plain
+ data: |
+ small body content
+ verify: { as: equal }
+
+ - client-request:
+ method: GET
+ url: /path
+ version: '1.1'
+ headers:
+ fields:
+ - [ Host, fqdn8 ]
+ - [ uuid, 8 ]
+
+ proxy-response:
+ status: 200
+ headers:
+ fields:
+ - [ Content-Length, { value: 19, as: equal } ]
+ - [ Cache-Control, { value: no-cache, as: equal } ]
+ - [ Content-Type, { value: text/plain, as: equal } ]
+ - [ Server, { value: ATS, as: contains } ]
+ content:
+ encoding: plain
+ data: |
+ small body content
+ verify: { as: equal }
+
+ - client-request:
+ method: GET
+ url: /small_body.txt
+ version: '1.1'
+ headers:
+ fields:
+ - [ Host, fqdn9 ]
+ - [ uuid, 9 ]
+
+ proxy-response:
+ status: 200
+ headers:
+ fields:
+ - [ Content-Length, { value: 19, as: equal } ]
+ - [ Cache-Control, { value: no-cache, as: equal } ]
+ - [ Content-Type, { value: text/plain, as: equal } ]
+ - [ Server, { value: ATS, as: contains } ]
+ content:
+ encoding: plain
+ data: |
+ small body content
+ verify: { as: equal }
diff --git a/tests/gold_tests/pluginTest/statichit/statichit.test.py
b/tests/gold_tests/pluginTest/statichit/statichit.test.py
index 35552d9976..c82d498907 100644
--- a/tests/gold_tests/pluginTest/statichit/statichit.test.py
+++ b/tests/gold_tests/pluginTest/statichit/statichit.test.py
@@ -31,8 +31,9 @@ class RemapData:
@staticmethod
def setup():
- Test.Setup.Copy('small_body.txt', Test.RunDirectory)
- RemapData.small_body_path = os.path.join(Test.RunDirectory,
'small_body.txt')
+ # Path relative to config directory. The statichit directory will be
created, and small_body.txt copied to it,
+ # by the 2nd (dummy) test run.
+ RemapData.small_body_path = os.path.join('statichit', 'small_body.txt')
Test.Setup.Copy('story_16.json', Test.RunDirectory)
RemapData.json_body_path = os.path.join(Test.RunDirectory,
'story_16.json')
@@ -40,6 +41,9 @@ class RemapData:
Test.Setup.Copy('empty.txt', Test.RunDirectory)
RemapData.empty_body_path = os.path.join(Test.RunDirectory,
'empty.txt')
+ # This directory will be created, and a file copied to it, by the 1st
(dummy) test run.
+ RemapData.dir_path = os.path.join(Test.RunDirectory, 'body_dir')
+
def __init__(self, from_url, *args) -> None:
self.remap_from = from_url
self.plugin_args = args
@@ -57,32 +61,51 @@ class RemapData:
self.body = RemapData.empty_body_path
return self
+ def dir(self):
+ self.body = RemapData.dir_path
+ return self
+
RemapData.setup()
remap_data = [
RemapData('http://fqdn1'),
- RemapData('http://fqdn2', 'max-age=123'),
- RemapData('http://fqdn3', 'success-code=200', 'disable-exact',
'failure-code=222'),
- RemapData('http://fqdn4', 'success-code=200',
'failure-code=412').bad_body(),
- RemapData('http://fqdn5', 'success-code=200', 'failure-code=412',
"mime-type=application/json").json_body(),
- RemapData('http://fqdn6', 'success-code=200',
'failure-code=222').empty_body()
+ RemapData('http://fqdn2', '--max-age=123'),
+ RemapData('http://fqdn3', '--success-code=200', '--disable-exact',
'--failure-code=222'),
+ RemapData('http://fqdn4', '--success-code=200',
'--failure-code=412').bad_body(),
+ RemapData('http://fqdn5', '--success-code=200', '--failure-code=412',
"--mime-type=application/json").json_body(),
+ RemapData('http://fqdn6', '--success-code=200',
'--failure-code=222').empty_body(),
+ RemapData('http://fqdn7', '--success-code', '200', '--disable-exact',
'--failure-code', '222'),
+ RemapData('http://fqdn8', '-s', '200', '-d', '-c', '222'),
+ RemapData('http://fqdn9').dir(),
]
ts = Test.MakeATSProcess('ts')
ts.Disk.records_config.update({
"proxy.config.diags.debug.enabled": 1,
- "proxy.config.diags.debug.tags": "statichit",
+ "proxy.config.diags.debug.tags": "http|statichit",
})
for d in remap_data:
arg_str = ''
for arg in d.plugin_args:
- arg_str += ' @pparam=--' + arg
+ arg_str += ' @pparam=' + arg
ts.Disk.remap_config.AddLine(f'map {d.remap_from} http://127.0.0.1/
@plugin=statichit.so @pparam=--file-path={d.body}{arg_str}')
+# Dummy test run for copying a file.
tr = Test.AddTestRun()
-p = tr.AddVerifierClientProcess('client', 'statichit.replay.yaml',
http_ports=[ts.Variables.port], other_args='--thread-limit 1')
+p = tr.Processes.Default
+p.Command = (f'mkdir {Test.RunDirectory}/body_dir ; ' + f'cp
{Test.TestDirectory}/small_body.txt {Test.RunDirectory}/body_dir/.')
+
+# Dummy test run for copying a file.
+tr = Test.AddTestRun()
+p = tr.Processes.Default
+p.Command = (
+ f'mkdir {ts.Variables.CONFIGDIR}/statichit ; ' + f'cp
{Test.TestDirectory}/small_body.txt {ts.Variables.CONFIGDIR}/statichit/.')
p.StartBefore(ts)
p.StillRunningAfter = ts
+
+tr = Test.AddTestRun()
+p = tr.AddVerifierClientProcess('client', 'statichit.replay.yaml',
http_ports=[ts.Variables.port], other_args='--thread-limit 1')
+p.StillRunningAfter = ts
