You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2013/12/03 15:04:52 UTC
git commit: docs: Fix ts-lua docs style & formatting
Updated Branches:
refs/heads/master d47def14f -> 7264e9ce3
docs: Fix ts-lua docs style & formatting
Add a license, fix the headers and add formatting for code.
outstanding: document configuration
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/7264e9ce
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/7264e9ce
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/7264e9ce
Branch: refs/heads/master
Commit: 7264e9ce3ed58f1a9db96b5f609d3e394b23f08b
Parents: d47def1
Author: Igor Galić <i....@brainsware.org>
Authored: Tue Dec 3 15:01:49 2013 +0100
Committer: Igor Galić <i....@brainsware.org>
Committed: Tue Dec 3 15:03:54 2013 +0100
----------------------------------------------------------------------
doc/reference/plugins/ts_lua.en.rst | 121 ++++++++++++++++++++-----------
1 file changed, 78 insertions(+), 43 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/7264e9ce/doc/reference/plugins/ts_lua.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/plugins/ts_lua.en.rst b/doc/reference/plugins/ts_lua.en.rst
index f969a61..c5015be 100644
--- a/doc/reference/plugins/ts_lua.en.rst
+++ b/doc/reference/plugins/ts_lua.en.rst
@@ -1,24 +1,43 @@
ts-lua Plugin
*************
-Name
-======
-
-ts-lua - Embed the Power of Lua into TrafficServer.
+.. 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.
+
+
+Embed the Power of Lua into TrafficServer.
Status
======
+
This module is being tested under our production environment.
Version
-======
+=======
+
ts-lua has not been released yet.
Synopsis
-======
+========
**test_hdr.lua**
+::
+
function send_response()
ts.client_response.header['Rhost'] = ts.ctx['rhost']
return 0
@@ -43,6 +62,8 @@ Synopsis
**test_transform.lua**
+::
+
function upper_transform(data, eos)
if eos == 1 then
return string.upper(data)..'S.H.E.\n', eos
@@ -79,6 +100,8 @@ Synopsis
**test_cache_lookup.lua**
+::
+
function send_response()
ts.client_response.header['Rhost'] = ts.ctx['rhost']
ts.client_response.header['CStatus'] = ts.ctx['cstatus']
@@ -110,6 +133,8 @@ Synopsis
**test_ret_403.lua**
+::
+
function send_response()
ts.client_response.header['Now'] = ts.now()
return 0
@@ -135,6 +160,8 @@ Synopsis
**sethost.lua**
+::
+
HOSTNAME = ''
function __init__(argtb)
@@ -162,6 +189,8 @@ Synopsis
**test_intercept.lua**
+::
+
require 'os'
function send_data()
@@ -188,6 +217,7 @@ Synopsis
**test_server_intercept.lua**
+::
require 'os'
function send_data()
@@ -211,21 +241,24 @@ Synopsis
Description
-======
-This module embeds Lua, via the standard Lua 5.1 interpreter, into Apache Traffic Server. This module acts as remap plugin of Traffic Server, so we should realize **'do_remap'** function in each lua script. We can write this in remap.config:
+===========
+
+This module embeds Lua, via the standard Lua 5.1 interpreter, into Apache Traffic Server. This module acts as remap plugin of Traffic Server, so we should realize **'do_remap'** function in each lua script. We can write this in remap.config:::
-map http://a.tbcdn.cn/ http://inner.tbcdn.cn/ @plugin=/usr/lib64/trafficserver/plugins/libtslua.so @pparam=/etc/trafficserver/script/test_hdr.lua
+ map http://a.tbcdn.cn/ http://inner.tbcdn.cn/ @plugin=/usr/lib64/trafficserver/plugins/libtslua.so @pparam=/etc/trafficserver/script/test_hdr.lua
-Sometimes we want to receive parameters and process them in the script, we should realize **'\__init__'** function in the lua script(sethost.lua is a reference), and we can write this in remap.config:
+Sometimes we want to receive parameters and process them in the script, we should realize **'\__init__'** function in the lua script(sethost.lua is a reference), and we can write this in remap.config:::
-map http://a.tbcdn.cn/ http://inner.tbcdn.cn/ @plugin=/usr/lib64/trafficserver/plugins/libtslua.so @pparam=/etc/trafficserver/script/sethost.lua @pparam=img03.tbcdn.cn
+ map http://a.tbcdn.cn/ http://inner.tbcdn.cn/ @plugin=/usr/lib64/trafficserver/plugins/libtslua.so @pparam=/etc/trafficserver/script/sethost.lua @pparam=img03.tbcdn.cn
TS API for Lua
-======
+==============
+
Introduction
-------
+------------
+
The API is exposed to Lua in the form of one standard packages ts. This package is in the default global scope and is always available within lua script.
@@ -238,7 +271,7 @@ ts.now
**description**: This function returns the time since the Epoch (00:00:00 UTC, January 1, 1970), measured in seconds.
-Here is an example:
+Here is an example:::
function send_response()
ts.client_response.header['Now'] = ts.now()
@@ -247,27 +280,27 @@ Here is an example:
ts.debug
-------
+--------
**syntax**: *ts.debug(MESSAGE)*
**context**: global
**description**: Log the MESSAGE to traffic.out if debug is enabled.
-Here is an example:
+Here is an example:::
function do_remap()
ts.debug('I am in do_remap now.')
return 0
end
-The debug tag is ts_lua and we should write this in records.config:
+The debug tag is ts_lua and we should write this in records.config:::
CONFIG proxy.config.diags.debug.tags STRING ts_lua
ts.hook
-------
+-------
**syntax**: *ts.hook(HOOK_POINT, FUNCTION)*
**context**: do_remap or later
@@ -275,7 +308,7 @@ ts.hook
**description**: Hooks are points in http transaction processing where we can step in and do some work.
FUNCTION will be called when the http transaction steps in to HOOK_POINT.
-Here is an example:
+Here is an example:::
function send_response()
s.client_response.header['SHE'] = 'belief'
@@ -286,7 +319,7 @@ Here is an example:
end
Hook point constants
-------
+--------------------
**context**: do_remap or later
TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE
@@ -307,7 +340,7 @@ ts.ctx
**description**: This table can be used to store per-request Lua context data and has a life time identical to the current request.
-Here is an example:
+Here is an example:::
function send_response()
ts.client_response.header['RR'] = ts.ctx['rhost']
@@ -323,14 +356,14 @@ Here is an example:
ts.http.get_cache_lookup_status
-------
+-------------------------------
**syntax**: *ts.http.get_cache_lookup_status()*
**context**: function @ TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE hook point
**description**: This function can be used to get cache lookup status.
-Here is an example:
+Here is an example:::
function send_response()
ts.client_response.header['CStatus'] = ts.ctx['cstatus']
@@ -353,7 +386,7 @@ Here is an example:
Http cache lookup status constants
-------
+----------------------------------
**context**: global
TS_LUA_CACHE_LOOKUP_MISS (0)
@@ -363,14 +396,14 @@ Http cache lookup status constants
ts.http.set_cache_url
-------
+---------------------
**syntax**: *ts.http.set_cache_url(KEY_URL)*
**context**: do_remap
**description**: This function can be used to modify the cache key for the request.
-Here is an example:
+Here is an example:::
function do_remap()
ts.http.set_cache_url('http://127.0.0.1:8080/abc/')
@@ -379,14 +412,14 @@ Here is an example:
ts.http.resp_cache_transformed
-------
+------------------------------
**syntax**: *ts.http.resp_cache_transformed(BOOL)*
**context**: do_remap or later
**description**: This function can be used to tell trafficserver whether to cache the transformed data.
-Here is an example:
+Here is an example:::
function upper_transform(data, eos)
if eos == 1 then
@@ -407,14 +440,14 @@ This function is usually called after we hook TS_LUA_RESPONSE_TRANSFORM.
ts.http.resp_cache_untransformed
-------
+--------------------------------
**syntax**: *ts.http.resp_cache_untransformed(BOOL)*
**context**: do_remap or later
**description**: This function can be used to tell trafficserver whether to cache the untransformed data.
-Here is an example:
+Here is an example:::
function upper_transform(data, eos)
if eos == 1 then
@@ -435,14 +468,14 @@ This function is usually called after we hook TS_LUA_RESPONSE_TRANSFORM.
ts.client_request.client_addr.get_addr
-------
+--------------------------------------
**syntax**: *ts.client_request.client_addr.get_addr()*
**context**: do_remap or later
**description**: This function can be used to get socket address of the client.
-Here is an example:
+Here is an example:::
function do_remap
ip, port, family = ts.client_request.client_addr.get_addr()
@@ -453,7 +486,7 @@ The ts.client_request.client_addr.get_addr function returns three values, ip is
ts.client_request.get_method
-------
+----------------------------
**syntax**: *ts.client_request.get_method()*
**context**: do_remap or later
@@ -463,7 +496,7 @@ ts.client_request.get_method
ts.client_request.set_method
-------
+----------------------------
**syntax**: *ts.client_request.set_method(METHOD_NAME)*
**context**: do_remap
@@ -472,7 +505,7 @@ ts.client_request.set_method
ts.client_request.get_url
-------
+-------------------------
**syntax**: *ts.client_request.get_url()*
**context**: do_remap or later
@@ -481,7 +514,7 @@ ts.client_request.get_url
ts.client_request.get_uri
-------
+-------------------------
**syntax**: *ts.client_request.get_uri()*
**context**: do_remap or later
@@ -490,7 +523,7 @@ ts.client_request.get_uri
ts.client_request.set_uri
-------
+-------------------------
**syntax**: *ts.client_request.set_uri(PATH)*
**context**: do_remap
@@ -499,7 +532,7 @@ ts.client_request.set_uri
ts.client_request.get_uri_args
-------
+------------------------------
**syntax**: *ts.client_request.get_uri_args()*
**context**: do_remap or later
@@ -508,7 +541,7 @@ ts.client_request.get_uri_args
ts.client_request.set_uri_args
-------
+------------------------------
**syntax**: *ts.client_request.set_uri_args(QUERY_STRING)*
**context**: do_remap
@@ -517,7 +550,7 @@ ts.client_request.set_uri_args
ts.client_request.header.HEADER
-------
+-------------------------------
**syntax**: *ts.client_request.header.HEADER = VALUE*
**syntax**: *ts.client_request.header[HEADER] = VALUE*
@@ -537,13 +570,15 @@ Here is an example:
TODO
-=======
+====
+
Short Term
-------
+----------
+* document configuration
* non-blocking I/O operation
* ts.fetch
Long Term
-------
+---------
* ts.regex