| .. _ts-lua-plugin: |
| |
| ts-lua 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 module embeds Lua, via the standard Lua 5.1 interpreter, into Apache Traffic Server. With this module, we can |
| implement ATS plugin by writing lua script instead of c code. Lua code executed using this module can be 100% |
| non-blocking because the powerful Lua coroutines had been integrated in to ATS event model. |
| |
| Synopsis |
| ======== |
| **test_hdr.lua** |
| |
| :: |
| |
| function send_response() |
| ts.client_response.header['Rhost'] = ts.ctx['rhost'] |
| return 0 |
| end |
| |
| function do_remap() |
| local req_host = ts.client_request.header.Host |
| ts.ctx['rhost'] = string.reverse(req_host) |
| ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response) |
| return 0 |
| end |
| |
| **sethost.lua** |
| |
| :: |
| |
| local HOSTNAME = '' |
| function __init__(argtb) |
| if (#argtb) < 1 then |
| print(argtb[0], 'hostname parameter required!!') |
| return -1 |
| end |
| HOSTNAME = argtb[1] |
| end |
| |
| function do_remap() |
| ts.client_request.header['Host'] = HOSTNAME |
| return 0 |
| end |
| |
| |
| Installation |
| ============ |
| |
| This plugin is only built if the configure option |
| |
| :: |
| |
| --enable-experimental-plugins |
| |
| is given at build time. |
| |
| Configuration |
| ============= |
| |
| 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=/XXX/tslua.so @pparam=/XXX/test_hdr.lua |
| |
| Sometimes we want to receive parameters and process them in the script, we should realize '__init__' function in the lua |
| script, and we can write this in remap.config: |
| |
| :: |
| |
| map http://a.x.cn/ http://b.x.cn/ @plugin=/X/tslua.so @pparam=/X/sethost.lua @pparam=a.st.cn |
| |
| This module can also act as a global plugin of Traffic Server. In this case we should provide one of these functions in |
| each lua script: |
| |
| - **'do_global_txn_start'** |
| - **'do_global_txn_close'** |
| - **'do_global_os_dns'** |
| - **'do_global_pre_remap'** |
| - **'do_global_post_remap'** |
| - **'do_global_read_request'** |
| - **'do_global_send_request'** |
| - **'do_global_read_response'** |
| - **'do_global_send_response'** |
| - **'do_global_cache_lookup_complete'** |
| - **'do_global_read_cache'** |
| - **'do_global_select_alt'** |
| |
| We can write this in plugin.config: |
| |
| :: |
| |
| tslua.so /etc/trafficserver/script/test_global_hdr.lua |
| |
| |
| 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. This package can be introduced into Lua like this: |
| |
| :: |
| |
| ts.say('Hello World') |
| ts.sleep(10) |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.now |
| ------ |
| **syntax:** *val = ts.now()* |
| |
| **context:** global |
| |
| **description:** This function returns the time since the Epoch (00:00:00 UTC, January 1, 1970), measured in seconds. |
| |
| Here is an example: |
| |
| :: |
| |
| local nt = ts.now() -- 1395221053 |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.debug |
| -------- |
| **syntax:** *ts.debug(MESSAGE)* |
| |
| **context:** global |
| |
| **description**: Log the MESSAGE to traffic.out if debug is enabled. |
| |
| Here is an example: |
| |
| :: |
| |
| ts.debug('I am in do_remap now.') |
| |
| The debug tag is **ts_lua** and we should write this in records.config: |
| |
| ``CONFIG proxy.config.diags.debug.tags STRING ts_lua`` |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| Remap status constants |
| ---------------------- |
| **context:** do_remap |
| |
| :: |
| |
| TS_LUA_REMAP_NO_REMAP (0) |
| TS_LUA_REMAP_DID_REMAP (1) |
| TS_LUA_REMAP_NO_REMAP_STOP (2) |
| TS_LUA_REMAP_DID_REMAP_STOP (3) |
| TS_LUA_REMAP_ERROR (-1) |
| |
| These constants are usually used as return value of do_remap function. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.hook |
| ------- |
| **syntax:** *ts.hook(HOOK_POINT, FUNCTION)* |
| |
| **context:** global or do_remap or do_global_* or later |
| |
| **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 |
| |
| :: |
| |
| function send_response() |
| s.client_response.header['SHE'] = 'belief' |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response) |
| end |
| |
| Then the client will get the response like this: |
| |
| :: |
| |
| HTTP/1.1 200 OK |
| Content-Type: text/html |
| Server: ATS/3.2.0 |
| SHE: belief |
| Connection: Keep-Alive |
| ... |
| |
| You can create global hook as well |
| |
| :: |
| |
| function do_some_work() |
| ts.debug('do_some_work') |
| return 0 |
| end |
| |
| ts.hook(TS_LUA_HOOK_READ_REQUEST_HDR, do_some_work) |
| |
| Or you can do it this way |
| |
| ts.hook(TS_LUA_HOOK_READ_REQUEST_HDR, |
| function() |
| ts.debug('do_some_work') |
| return 0 |
| end |
| ) |
| |
| Also the return value of the function will control how the transaction will be re-enabled. Return value of 0 will cause |
| the transaction to be re-enabled normally (TS_EVENT_HTTP_CONTINUE). Return value of 1 will be using TS_EVENT_HTTP_ERROR |
| instead. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| Hook point constants |
| -------------------- |
| **context:** do_remap or later |
| |
| :: |
| |
| TS_LUA_HOOK_OS_DNS |
| TS_LUA_HOOK_PRE_REMAP |
| TS_LUA_HOOK_READ_CACHE_HDR |
| TS_LUA_HOOK_SELECT_ALT |
| TS_LUA_HOOK_TXN_CLOSE |
| TS_LUA_HOOK_POST_REMAP |
| TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE |
| TS_LUA_HOOK_READ_REQUEST_HDR |
| TS_LUA_HOOK_SEND_REQUEST_HDR |
| TS_LUA_HOOK_READ_RESPONSE_HDR |
| TS_LUA_HOOK_SEND_RESPONSE_HDR |
| TS_LUA_REQUEST_TRANSFORM |
| TS_LUA_RESPONSE_TRANSFORM |
| |
| These constants are usually used in ts.hook method call. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.ctx |
| ------ |
| **syntax:** *ts.ctx[KEY] = VALUE* |
| |
| **syntax:** *VALUE = ts.ctx[KEY]* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **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: |
| |
| :: |
| |
| function send_response() |
| ts.client_response.header['F-Header'] = ts.ctx['hdr'] |
| return 0 |
| end |
| |
| function do_remap() |
| ts.ctx['hdr'] = 'foo' |
| ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response) |
| return 0 |
| end |
| |
| Then the client will get the response like this: |
| |
| :: |
| |
| HTTP/1.1 200 OK |
| Content-Type: text/html |
| Server: ATS/3.2.0 |
| F-Header: foo |
| Connection: Keep-Alive |
| ... |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.get_method |
| ---------------------------- |
| **syntax:** *ts.client_request.get_method()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** This function can be used to retrieve the current client request's method name. String like "GET" or |
| "POST" is returned. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.set_method |
| ---------------------------- |
| **syntax:** *ts.client_request.set_method()* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** This function can be used to override the current client request's method with METHOD_NAME. |
| |
| ts.client_request.get_version |
| ----------------------------- |
| **syntax:** *ver = ts.client_request.get_version()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** Return the http version string of the client request. |
| |
| Current possible values are 1.0, 1.1, and 0.9. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.set_version |
| ----------------------------- |
| **syntax:** *ts.client_request.set_version(VERSION_STR)* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** Set the http version of the client request with the VERSION_STR |
| |
| :: |
| |
| ts.client_request.set_version('1.0') |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.get_uri |
| ------------------------- |
| **syntax:** *ts.client_request.get_uri()* |
| |
| **context:** do_remap or later |
| |
| **description:** This function can be used to retrieve the client request's path. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| local uri = ts.client_request.get_uri() |
| print(uri) |
| end |
| |
| Then ``GET /st?a=1`` will yield the output: |
| |
| ``/st`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.set_uri |
| ------------------------- |
| **syntax:** *ts.client_request.set_uri(PATH)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** This function can be used to override the client request's path. |
| |
| The PATH argument must be a Lua string and starts with ``/`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.get_uri_args |
| ------------------------------ |
| **syntax:** *ts.client_request.get_uri_args()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** This function can be used to retrieve the client request's query string. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| local query = ts.client_request.get_uri_args() |
| print(query) |
| end |
| |
| Then ``GET /st?a=1&b=2`` will yield the output: |
| |
| ``a=1&b=2`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.set_uri_args |
| ------------------------------ |
| **syntax:** *ts.client_request.set_uri_args(QUERY_STRING)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** This function can be used to override the client request's query string. |
| |
| :: |
| |
| ts.client_request.set_uri_args('n=6&p=7') |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.get_url |
| ------------------------- |
| **syntax:** *ts.client_request.get_url()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** This function can be used to retrieve the whole client request's url. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| local url = ts.client_request.get_url() |
| print(url) |
| end |
| |
| Then ``GET /st?a=1&b=2 HTTP/1.1\r\nHost: a.tbcdn.cn\r\n...`` will yield the output: |
| |
| ``http://a.tbcdn.cn/st?a=1&b=2`` |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.header.HEADER |
| ------------------------------- |
| **syntax:** *ts.client_request.header.HEADER = VALUE* |
| |
| **syntax:** *ts.client_request.header[HEADER] = VALUE* |
| |
| **syntax:** *VALUE = ts.client_request.header.HEADER* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** Set, add to, clear or get the current client request's HEADER. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| local ua = ts.client_request.header['User-Agent'] |
| print(ua) |
| ts.client_request.header['Host'] = 'a.tbcdn.cn' |
| end |
| |
| Then ``GET /st HTTP/1.1\r\nHost: b.tb.cn\r\nUser-Agent: Mozilla/5.0\r\n...`` will yield the output: |
| |
| ``Mozilla/5.0`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.get_headers |
| ----------------------------- |
| **syntax:** *ts.client_request.get_headers()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** Returns a Lua table holding all the headers for the current client request. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| hdrs = ts.client_request.get_headers() |
| for k, v in pairs(hdrs) do |
| print(k..': '..v) |
| end |
| end |
| |
| Then ``GET /st HTTP/1.1\r\nHost: b.tb.cn\r\nUser-Aget: Mozilla/5.0\r\nAccept: */*`` will yield the output :: |
| |
| Host: b.tb.cn |
| User-Agent: Mozilla/5.0 |
| Accept: */* |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.client_addr.get_addr |
| -------------------------------------- |
| **syntax:** *ts.client_request.client_addr.get_addr()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description**: This function can be used to get socket address of the client. |
| |
| The ts.client_request.client_addr.get_addr function returns three values, ip is a string, port and family is number. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| ip, port, family = ts.client_request.client_addr.get_addr() |
| print(ip) -- 192.168.231.17 |
| print(port) -- 17786 |
| print(family) -- 2(AF_INET) |
| return 0 |
| end |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.get_url_host |
| ------------------------------ |
| **syntax:** *host = ts.client_request.get_url_host()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** Return the ``host`` field of the request url. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| local url_host = ts.client_request.get_url_host() |
| print(url_host) |
| end |
| |
| Then ``GET /liuyurou.txt HTTP/1.1\r\nHost: 192.168.231.129:8080\r\n...`` will yield the output: |
| |
| ``192.168.231.129`` |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.set_url_host |
| ------------------------------ |
| **syntax:** *ts.client_request.set_url_host(str)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** Set ``host`` field of the request url with ``str``. This function is used to change the address of the |
| origin server, and we should return TS_LUA_REMAP_DID_REMAP(_STOP) in do_remap. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| ts.client_request.set_url_host('192.168.231.130') |
| ts.client_request.set_url_port(80) |
| ts.client_request.set_url_scheme('http') |
| return TS_LUA_REMAP_DID_REMAP |
| end |
| |
| remap.config like this: |
| |
| :: |
| |
| map http://192.168.231.129:8080/ http://192.168.231.129:9999/ |
| |
| Then server request will connect to ``192.168.231.130:80`` |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.get_url_port |
| ------------------------------ |
| **syntax:** *port = ts.client_request.get_url_port()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** Returns the ``port`` field of the request url as a Lua number. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| local url_port = ts.client_request.get_url_port() |
| print(url_port) |
| end |
| |
| Then Then ``GET /liuyurou.txt HTTP/1.1\r\nHost: 192.168.231.129:8080\r\n...`` will yield the output: |
| |
| ``8080`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.set_url_port |
| ------------------------------ |
| **syntax:** *ts.client_request.set_url_port(NUMBER)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** Set ``port`` field of the request url with ``NUMBER``. This function is used to change the address of |
| the origin server, and we should return TS_LUA_REMAP_DID_REMAP(_STOP) in do_remap. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.get_url_scheme |
| -------------------------------- |
| **syntax:** *scheme = ts.client_request.get_url_scheme()* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description:** Return the ``scheme`` field of the request url. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| local url_scheme = ts.client_request.get_url_scheme() |
| print(url_scheme) |
| end |
| |
| Then ``GET /liuyurou.txt HTTP/1.1\r\nHost: 192.168.231.129:8080\r\n...`` will yield the output: |
| |
| ``http`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_request.set_url_scheme |
| -------------------------------- |
| **syntax:** *ts.client_request.set_url_scheme(str)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** Set ``scheme`` field of the request url with ``str``. This function is used to change the scheme of the |
| server request, and we should return TS_LUA_REMAP_DID_REMAP(_STOP) in do_remap. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.set_cache_url |
| --------------------- |
| **syntax:** *ts.http.set_cache_url(KEY_URL)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** This function can be used to modify the cache key for the client request. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| ts.http.set_cache_url('http://a.tbcdn.cn/foo') |
| return 0 |
| end |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.set_resp |
| ---------------- |
| **syntax:** *ts.http.set_resp(CODE, BODY)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** This function can be used to set response for the client with the CODE status and BODY string. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| ts.http.set_resp(403, "Document access failed :)\n") |
| return 0 |
| end |
| |
| We will get the response like this: |
| |
| :: |
| |
| HTTP/1.1 403 Forbidden |
| Date: Thu, 20 Mar 2014 06:12:43 GMT |
| Connection: close |
| Server: ATS/5.0.0 |
| Cache-Control: no-store |
| Content-Type: text/html |
| Content-Language: en |
| Content-Length: 27 |
| |
| Document access failed :) |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| 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: |
| |
| :: |
| |
| function cache_lookup() |
| local cache_status = ts.http.get_cache_lookup_status() |
| if cache_status == TS_LUA_CACHE_LOOKUP_HIT_FRESH then |
| print('hit') |
| else |
| print('not hit') |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE, cache_lookup) |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| Http cache lookup status constants |
| ---------------------------------- |
| **context:** global |
| |
| :: |
| |
| TS_LUA_CACHE_LOOKUP_MISS (0) |
| TS_LUA_CACHE_LOOKUP_HIT_STALE (1) |
| TS_LUA_CACHE_LOOKUP_HIT_FRESH (2) |
| TS_LUA_CACHE_LOOKUP_SKIPPED (3) |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.cached_response.get_status |
| ----------------------------- |
| **syntax:** *status = ts.cached_response.get_status()* |
| |
| **context:** function @ TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE hook point or later |
| |
| **description:** This function can be used to retrieve the status code of the cached response. A Lua number will be |
| returned. |
| |
| Here is an example: |
| |
| :: |
| |
| function cache_lookup() |
| local cache_status = ts.http.get_cache_lookup_status() |
| if cache_status == TS_LUA_CACHE_LOOKUP_HIT_FRESH then |
| code = ts.cached_response.get_status() |
| print(code) -- 200 |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE, cache_lookup) |
| return 0 |
| end |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.cached_response.get_version |
| ------------------------------ |
| **syntax:** *ver = ts.cached_response.get_version()* |
| |
| **context:** function @ TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE hook point or later |
| |
| **description:** Return the http version string of the cached response. |
| |
| Current possible values are 1.0, 1.1, and 0.9. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.cached_response.header.HEADER |
| -------------------------------- |
| **syntax:** *VALUE = ts.cached_response.header.HEADER* |
| |
| **syntax:** *VALUE = ts.cached_response.header[HEADER]* |
| |
| **context:** function @ TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE hook point or later |
| |
| **description:** get the current cached response's HEADER. |
| |
| Here is an example: |
| |
| :: |
| |
| function cache_lookup() |
| local status = ts.http.get_cache_lookup_status() |
| if status == TS_LUA_CACHE_LOOKUP_HIT_FRESH then |
| local ct = ts.cached_response.header['Content-Type'] |
| print(ct) -- text/plain |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE, cache_lookup) |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.cached_response.get_headers |
| ------------------------------ |
| **syntax:** *ts.cached_response.get_headers()* |
| |
| **context:** function @ TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE hook point or later |
| |
| **description:** Returns a Lua table holding all the headers for the current cached response. |
| |
| Here is an example: |
| |
| :: |
| |
| function cache_lookup() |
| local status = ts.http.get_cache_lookup_status() |
| if status == TS_LUA_CACHE_LOOKUP_HIT_FRESH then |
| hdrs = ts.cached_response.get_headers() |
| for k, v in pairs(hdrs) do |
| print(k..': '..v) |
| end |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE, cache_lookup) |
| return 0 |
| end |
| |
| We will get the output: |
| |
| :: |
| |
| Connection: keep-alive |
| Content-Type: text/plain |
| Date: Thu, 20 Mar 2014 06:12:20 GMT |
| Cache-Control: max-age=864000 |
| Last-Modified: Sun, 19 May 2013 13:22:01 GMT |
| Accept-Ranges: bytes |
| Content-Length: 15 |
| Server: ATS/5.0.0 |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| |
| ts.server_request.get_uri |
| ------------------------- |
| **syntax:** *ts.server_request.get_uri()* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_REQUEST_HDR hook point or later |
| |
| **description:** This function can be used to retrieve the server request's path. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_request() |
| local uri = ts.server_request.get_uri() |
| print(uri) |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_REQUEST_HDR, send_request) |
| return 0 |
| end |
| |
| Then ``GET /am.txt?a=1`` will yield the output: |
| |
| ``/am.txt`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_request.set_uri |
| ------------------------- |
| **syntax:** *ts.server_request.set_uri(PATH)* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_REQUEST_HDR hook point |
| |
| **description:** This function can be used to override the server request's path. |
| |
| The PATH argument must be a Lua string and starts with ``/`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_request.get_uri_args |
| ------------------------------ |
| **syntax:** *ts.server_request.get_uri_args()* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_REQUEST_HDR hook point or later |
| |
| **description:** This function can be used to retrieve the server request's query string. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_request() |
| local query = ts.server_request.get_uri_args() |
| print(query) |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_REQUEST_HDR, send_request) |
| return 0 |
| end |
| |
| Then ``GET /st?a=1&b=2`` will yield the output: |
| |
| ``a=1&b=2`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_request.set_uri_args |
| ------------------------------ |
| **syntax:** *ts.server_request.set_uri_args(QUERY_STRING)* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_REQUEST_HDR hook point |
| |
| **description:** This function can be used to override the server request's query string. |
| |
| :: |
| |
| ts.server_request.set_uri_args('n=6&p=7') |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_request.header.HEADER |
| ------------------------------- |
| **syntax:** *ts.server_request.header.HEADER = VALUE* |
| |
| **syntax:** *ts.server_request.header[HEADER] = VALUE* |
| |
| **syntax:** *VALUE = ts.server_request.header.HEADER* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_REQUEST_HDR hook point or later |
| |
| **description:** Set, add to, clear or get the current server request's HEADER. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_request() |
| local ua = ts.server_request.header['User-Agent'] |
| print(ua) |
| ts.server_request.header['Accept-Encoding'] = 'gzip' |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_REQUEST_HDR, send_request) |
| return 0 |
| end |
| |
| Then ``GET /st HTTP/1.1\r\nHost: b.tb.cn\r\nUser-Agent: Mozilla/5.0\r\n...`` will yield the output: |
| |
| ``Mozilla/5.0`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_request.get_headers |
| ----------------------------- |
| **syntax:** *ts.server_request.get_headers()* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_REQUEST_HDR hook point or later |
| |
| **description:** Returns a Lua table holding all the headers for the current server request. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_request() |
| hdrs = ts.cached_response.get_headers() |
| for k, v in pairs(hdrs) do |
| print(k..': '..v) |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_REQUEST_HDR, send_request) |
| return 0 |
| end |
| |
| We will get the output: |
| |
| :: |
| |
| Host: b.tb.cn |
| User-Agent: curl/7.19.7 |
| Accept: */* |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_response.get_status |
| ----------------------------- |
| **syntax:** *status = ts.server_response.get_status()* |
| |
| **context:** function @ TS_LUA_HOOK_READ_RESPONSE_HDR hook point or later |
| |
| **description:** This function can be used to retrieve the status code of the origin server's response. A Lua number |
| will be returned. |
| |
| Here is an example: |
| |
| :: |
| |
| function read_response() |
| local code = ts.server_response.get_status() |
| print(code) -- 200 |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_READ_RESPONSE_HDR, read_response) |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_' |
| |
| ts.server_response.set_status |
| ----------------------------- |
| **syntax:** *ts.server_response.set_status(NUMBER)* |
| |
| **context:** function @ TS_LUA_HOOK_READ_RESPONSE_HDR hook point |
| |
| **description:** This function can be used to set the status code of the origin server's response. |
| |
| Here is an example: |
| |
| :: |
| |
| function read_response() |
| ts.server_response.set_status(404) |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_READ_RESPONSE_HDR, read_response) |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_' |
| |
| ts.server_response.get_version |
| ------------------------------ |
| **syntax:** *ver = ts.server_response.get_version()* |
| |
| **context:** function @ TS_LUA_HOOK_READ_RESPONSE_HDR hook point or later. |
| |
| **description:** Return the http version string of the server response. |
| |
| Current possible values are 1.0, 1.1, and 0.9. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_response.set_version |
| ------------------------------ |
| **syntax:** *ts.server_response.set_version(VERSION_STR)* |
| |
| **context:** function @ TS_LUA_HOOK_READ_RESPONSE_HDR hook point |
| |
| **description:** Set the http version of the server response with the VERSION_STR |
| |
| :: |
| |
| ts.server_response.set_version('1.0') |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_response.header.HEADER |
| -------------------------------- |
| **syntax:** *ts.server_response.header.HEADER = VALUE* |
| |
| **syntax:** *ts.server_response.header[HEADER] = VALUE* |
| |
| **syntax:** *VALUE = ts.server_response.header.HEADER* |
| |
| **context:** function @ TS_LUA_HOOK_READ_RESPONSE_HDR hook point or later. |
| |
| **description:** Set, add to, clear or get the current server response's HEADER. |
| |
| Here is an example: |
| |
| :: |
| |
| function read_response() |
| local ct = ts.server_response.header['Content-Type'] |
| print(ct) |
| ts.server_response.header['Cache-Control'] = 'max-age=14400' |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_READ_RESPONSE_HDR, read_response) |
| return 0 |
| end |
| |
| We will get the output: |
| |
| ``text/html`` |
| |
| |
| `TOP <#ts-lua-plugin>`_' |
| |
| ts.server_response.get_headers |
| ------------------------------ |
| **syntax:** *ts.server_response.get_headers()* |
| |
| **context:** function @ TS_LUA_HOOK_READ_RESPONSE_HDR hook point or later |
| |
| **description:** Returns a Lua table holding all the headers for the current server response. |
| |
| Here is an example: |
| |
| :: |
| |
| function read_response() |
| hdrs = ts.server_response.get_headers() |
| for k, v in pairs(hdrs) do |
| print(k..': '..v) |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_READ_RESPONSE_HDR, read_response) |
| return 0 |
| end |
| |
| We will get the output: |
| |
| :: |
| |
| Server: nginx/1.5.9 |
| Date: Tue, 18 Mar 2014 10:12:25 GMT |
| Content-Type: text/html |
| Content-Length: 555 |
| Last-Modified: Mon, 19 Aug 2013 14:25:55 GMT |
| Connection: keep-alive |
| ETag: "52122af3-22b" |
| Cache-Control: max-age=14400 |
| Accept-Ranges: bytes |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_response.get_status |
| ----------------------------- |
| **syntax:** *status = ts.client_response.get_status()* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_RESPONSE_HDR hook point |
| |
| **description:** This function can be used to retrieve the status code of the response to the client. A Lua number will |
| be returned. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_response() |
| local code = ts.client_response.get_status() |
| print(code) -- 200 |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response) |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_response.set_status |
| ----------------------------- |
| **syntax:** *ts.client_response.set_status(NUMBER)* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_RESPONSE_HDR hook point |
| |
| **description:** This function can be used to set the status code of the response to the client. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_response() |
| ts.client_response.set_status(404) |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response) |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_response.get_version |
| ------------------------------ |
| **syntax:** *ver = ts.client_response.get_version()* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_RESPONSE_HDR hook point. |
| |
| **description:** Return the http version string of the response to the client. |
| |
| Current possible values are 1.0, 1.1, and 0.9. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_response.set_version |
| ------------------------------ |
| **syntax:** *ts.client_response.set_version(VERSION_STR)* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_RESPONSE_HDR hook point |
| |
| **description:** Set the http version of the response to the client with the VERSION_STR |
| |
| :: |
| |
| ts.client_response.set_version('1.0') |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_response.header.HEADER |
| -------------------------------- |
| **syntax:** *ts.client_response.header.HEADER = VALUE* |
| |
| **syntax:** *ts.client_response.header[HEADER] = VALUE* |
| |
| **syntax:** *VALUE = ts.client_response.header.HEADER* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_RESPONSE_HDR hook point. |
| |
| **description:** Set, add to, clear or get the current client response's HEADER. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_response() |
| local ct = ts.client_response.header['Content-Type'] |
| print(ct) |
| ts.client_response.header['Cache-Control'] = 'max-age=3600' |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response) |
| return 0 |
| end |
| |
| We will get the output: |
| |
| ``text/html`` |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_response.get_headers |
| ------------------------------ |
| **syntax:** *ts.client_response.get_headers()* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_RESPONSE_HDR hook point. |
| |
| **description:** Returns a Lua table holding all the headers for the current client response. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_response() |
| hdrs = ts.client_response.get_headers() |
| for k, v in pairs(hdrs) do |
| print(k..': '..v) |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response) |
| return 0 |
| end |
| |
| We will get the output: |
| |
| :: |
| |
| Server: ATS/5.0.0 |
| Date: Tue, 18 Mar 2014 10:12:25 GMT |
| Content-Type: text/html |
| Transfer-Encoding: chunked |
| Last-Modified: Mon, 19 Aug 2013 14:25:55 GMT |
| Connection: keep-alive |
| Cache-Control: max-age=14400 |
| Age: 2641 |
| Accept-Ranges: bytes |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.client_response.set_error_resp |
| --------------------------------- |
| **syntax:** *ts.client_response.set_error_resp(CODE, BODY)* |
| |
| **context:** function @ TS_LUA_HOOK_SEND_RESPONSE_HDR hook point. |
| |
| **description:** This function can be used to set the error response to the client. |
| |
| With this function we can jump to send error response to the client if exception exists, meanwhile we should return `-1` |
| from the function where exception raises. |
| |
| Here is an example: |
| |
| :: |
| |
| function send_response() |
| ts.client_response.set_error_resp(404, 'bad luck :(\n') |
| end |
| |
| function cache_lookup() |
| return -1 |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE, cache_lookup) |
| ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response) |
| return 0 |
| end |
| |
| We will get the response like this: |
| |
| :: |
| |
| HTTP/1.1 404 Not Found |
| Date: Tue, 18 Mar 2014 11:16:00 GMT |
| Connection: keep-alive |
| Server: ATS/5.0.0 |
| Content-Length: 12 |
| |
| bad luck :( |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.resp_cache_transformed |
| ------------------------------ |
| **syntax:** *ts.http.resp_cache_transformed(BOOL)* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description**: This function can be used to tell trafficserver whether to cache the transformed data. |
| |
| Here is an example: |
| |
| :: |
| |
| function upper_transform(data, eos) |
| if eos == 1 then |
| return string.upper(data)..'S.H.E.\n', eos |
| else |
| return string.upper(data), eos |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_RESPONSE_TRANSFORM, upper_transform) |
| ts.http.resp_cache_transformed(0) |
| return 0 |
| end |
| |
| This function is usually called after we hook TS_LUA_RESPONSE_TRANSFORM. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.resp_cache_untransformed |
| -------------------------------- |
| **syntax:** *ts.http.resp_cache_untransformed(BOOL)* |
| |
| **context:** do_remap or do_global_* or later |
| |
| **description**: This function can be used to tell trafficserver whether to cache the untransformed data. |
| |
| Here is an example: |
| |
| :: |
| |
| function upper_transform(data, eos) |
| if eos == 1 then |
| return string.upper(data)..'S.H.E.\n', eos |
| else |
| return string.upper(data), eos |
| end |
| end |
| |
| function do_remap() |
| ts.hook(TS_LUA_RESPONSE_TRANSFORM, upper_transform) |
| ts.http.resp_cache_untransformed(1) |
| return 0 |
| end |
| |
| This function is usually called after we hook TS_LUA_RESPONSE_TRANSFORM. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.skip_remapping_set |
| ------------------------- |
| **syntax:** *ts.http.skip_remapping_set(BOOL)* |
| |
| **context:** do_global_read_request |
| |
| **description**: This function can be used to tell trafficserver to skip doing remapping |
| |
| Here is an example: |
| |
| :: |
| |
| function do_global_read_request() |
| ts.http.skip_remapping_set(1); |
| ts.client_request.header['Host'] = 'www.yahoo.com' |
| return 0 |
| end |
| |
| This function is usually called in do_global_read_request function |
| |
| ts.http.is_internal_request |
| --------------------------- |
| **syntax:** *ts.http.is_internal_request()* |
| |
| ** context:** do_remap or do_global_* or later |
| |
| ** description**: This function can be used to tell is a request is internal or not |
| |
| Here is an example: |
| |
| :: |
| |
| function do_global_read_request() |
| local internal = ts.http.is_internal_request() |
| ts.debug(internal) |
| return 0 |
| end |
| |
| ts.add_package_path |
| ------------------- |
| **syntax:** *ts.add_package_path(lua-style-path-str)* |
| |
| **context:** init stage of the lua script |
| |
| **description:** Adds the Lua module search path used by scripts. |
| |
| The path string is in standard Lua path form. |
| |
| Here is an example: |
| |
| :: |
| |
| ts.add_package_path('/home/a/test/lua/pac/?.lua') |
| local nt = require("nt") |
| function do_remap() |
| print(nt.t9(7979)) |
| return 0 |
| end |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| |
| ts.add_package_cpath |
| -------------------- |
| **syntax:** *ts.add_package_cpath(lua-style-cpath-str)* |
| |
| **context:** init stage of the lua script |
| |
| **description:** Adds the Lua C-module search path used by scripts. |
| |
| The cpath string is in standard Lua cpath form. |
| |
| Here is an example: |
| |
| :: |
| |
| ts.add_package_cpath('/home/a/test/c/module/?.so') |
| local ma = require("ma") |
| function do_remap() |
| print(ma.ft()) |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| |
| ts.md5 |
| ------ |
| **syntax:** *digest = ts.md5(str)* |
| |
| **context:** global |
| |
| **description:** Returns the hexadecimal representation of the MD5 digest of the ``str`` argument. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| uri = ts.client_request.get_uri() |
| print(uri) -- /foo |
| print(ts.md5(uri)) -- 1effb2475fcfba4f9e8b8a1dbc8f3caf |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.md5_bin |
| ---------- |
| **syntax:** *digest = ts.md5_bin(str)* |
| |
| **context:** global |
| |
| **description:** Returns the binary form of the MD5 digest of the ``str`` argument. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| uri = ts.client_request.get_uri() |
| bin = ts.md5_bin(uri) |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.sha1 |
| ------- |
| **syntax:** *digest = ts.sha1(str)* |
| |
| **context:** global |
| |
| **description:** Returns the hexadecimal representation of the SHA-1 digest of the ``str`` argument. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| uri = ts.client_request.get_uri() |
| print(uri) -- /foo |
| print(ts.sha1(uri)) -- 6dbd548cc03e44b8b44b6e68e56255ce4273ae49 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.sha1_bin |
| ----------- |
| **syntax:** *digest = ts.sha1_bin(str)* |
| |
| **context:** global |
| |
| **description:** Returns the binary form of the SHA-1 digest of the ``str`` argument. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| uri = ts.client_request.get_uri() |
| bin = ts.sha1_bin(uri) |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.intercept |
| ------------ |
| **syntax:** *ts.intercept(FUNCTION)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** Intercepts the client request and processes it in FUNCTION. |
| |
| We should construct the response for the client request, and the request will not be processed by other modules, like |
| hostdb, cache, origin server... |
| |
| Here is an example: |
| |
| :: |
| |
| require 'os' |
| |
| function send_data() |
| local nt = os.time()..' Zheng.\n' |
| local resp = 'HTTP/1.0 200 OK\r\n' .. |
| 'Server: ATS/3.2.0\r\n' .. |
| 'Content-Type: text/plain\r\n' .. |
| 'Content-Length: ' .. string.format('%d', string.len(nt)) .. '\r\n' .. |
| 'Last-Modified: ' .. os.date("%a, %d %b %Y %H:%M:%S GMT", os.time()) .. '\r\n' .. |
| 'Connection: keep-alive\r\n' .. |
| 'Cache-Control: max-age=7200\r\n' .. |
| 'Accept-Ranges: bytes\r\n\r\n' .. |
| nt |
| ts.say(resp) |
| end |
| |
| function do_remap() |
| ts.http.intercept(send_data) |
| return 0 |
| end |
| |
| Then we will get the response like this: |
| |
| :: |
| |
| HTTP/1.1 200 OK |
| Server: ATS/5.0.0 |
| Content-Type: text/plain |
| Content-Length: 18 |
| Last-Modified: Tue, 18 Mar 2014 08:23:12 GMT |
| Cache-Control: max-age=7200 |
| Accept-Ranges: bytes |
| Date: Tue, 18 Mar 2014 12:23:12 GMT |
| Age: 0 |
| Connection: keep-alive |
| |
| 1395145392 Zheng. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.say |
| ------ |
| **syntax:** *ts.say(data)* |
| |
| **context:** *intercept or server_intercept* |
| |
| **description:** Write response to ATS within intercept or server_intercept. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.flush |
| -------- |
| **syntax:** *ts.flush()* |
| |
| **context:** *intercept or server_intercept* |
| |
| **description:** Flushes the output to ATS within intercept or server_intercept. |
| |
| In synchronous mode, the function will not return until all output data has been written into the system send buffer. |
| Note that using the Lua coroutine mechanism means that this function does not block the ATS event loop even in the |
| synchronous mode. |
| |
| Here is an example: |
| |
| :: |
| |
| require 'os' |
| |
| function send_data() |
| ss = 'wo ai yu ye hua\n' |
| local resp = 'HTTP/1.0 200 OK\r\n' .. |
| 'Server: ATS/3.2.0\r\n' .. |
| 'Content-Type: text/plain\r\n' .. |
| 'Content-Length: ' .. string.format('%d', 5*string.len(ss)) .. '\r\n' .. |
| 'Last-Modified: ' .. os.date("%a, %d %b %Y %H:%M:%S GMT", os.time()) .. '\r\n' .. |
| 'Connection: keep-alive\r\n' .. |
| 'Cache-Control: max-age=7200\r\n' .. |
| 'Accept-Ranges: bytes\r\n\r\n' |
| ts.say(resp) |
| for i=1, 5 do |
| ts.say(ss) |
| ts.flush() |
| end |
| end |
| |
| function do_remap() |
| ts.http.intercept(send_data) |
| return 0 |
| end |
| |
| We will get the response like this: |
| |
| :: |
| |
| HTTP/1.1 200 OK |
| Server: ATS/5.0.0 |
| Content-Type: text/plain |
| Content-Length: 80 |
| Last-Modified: Tue, 18 Mar 2014 08:38:29 GMT |
| Cache-Control: max-age=7200 |
| Accept-Ranges: bytes |
| Date: Tue, 18 Mar 2014 12:38:29 GMT |
| Age: 0 |
| Connection: keep-alive |
| |
| wo ai yu ye hua |
| wo ai yu ye hua |
| wo ai yu ye hua |
| wo ai yu ye hua |
| wo ai yu ye hua |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.sleep |
| -------- |
| **syntax:** *ts.sleep(sec)* |
| |
| **context:** *intercept or server_intercept* |
| |
| **description:** Sleeps for the specified seconds without blocking. |
| |
| Behind the scene, this method makes use of the ATS event model. |
| |
| Here is an example: |
| |
| :: |
| |
| require 'os' |
| |
| function send_data() |
| local nt = os.time()..' Zheng.\n' |
| local resp = 'HTTP/1.0 200 OK\r\n' .. |
| 'Server: ATS/3.2.0\r\n' .. |
| 'Content-Type: text/plain\r\n' .. |
| 'Content-Length: ' .. string.format('%d', string.len(nt)) .. '\r\n\r\n' .. |
| nt |
| ts.sleep(3) |
| ts.say(resp) |
| end |
| |
| function do_remap() |
| ts.http.intercept(send_data) |
| return 0 |
| end |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.server_intercept |
| ------------------- |
| **syntax:** *ts.server_intercept(FUNCTION)* |
| |
| **context:** do_remap or do_global_* |
| |
| **description:** Intercepts the server request and acts as the origin server. |
| |
| We should construct the response for the server request, so the request will be processed within FUNCTION in case of |
| miss for the cache lookup. |
| |
| Here is an example: |
| |
| :: |
| |
| require 'os' |
| |
| function send_data() |
| local nt = os.time()..' Zheng.\n' |
| local resp = 'HTTP/1.0 200 OK\r\n' .. |
| 'Server: ATS/3.2.0\r\n' .. |
| 'Content-Type: text/plain\r\n' .. |
| 'Content-Length: ' .. string.format('%d', string.len(nt)) .. '\r\n' .. |
| 'Last-Modified: ' .. os.date("%a, %d %b %Y %H:%M:%S GMT", os.time()) .. '\r\n' .. |
| 'Connection: keep-alive\r\n' .. |
| 'Cache-Control: max-age=7200\r\n' .. |
| 'Accept-Ranges: bytes\r\n\r\n' .. |
| nt |
| ts.say(resp) |
| end |
| |
| function do_remap() |
| ts.http.server_intercept(send_data) |
| return 0 |
| end |
| |
| Then we will get the response like this: |
| |
| :: |
| |
| HTTP/1.1 200 OK |
| Server: ATS/5.0.0 |
| Content-Type: text/plain |
| Content-Length: 18 |
| Last-Modified: Tue, 18 Mar 2014 08:23:12 GMT |
| Cache-Control: max-age=7200 |
| Accept-Ranges: bytes |
| Date: Tue, 18 Mar 2014 12:23:12 GMT |
| Age: 1890 |
| Connection: keep-alive |
| |
| 1395145392 Zheng. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.config_int_get |
| ---------------------- |
| **syntax:** *val = ts.http.config_int_get(CONFIG)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** Configuration option which has a int value can be retrieved with this function. |
| |
| :: |
| |
| val = ts.http.config_int_get(TS_LUA_CONFIG_HTTP_CACHE_HTTP) |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.config_int_set |
| ---------------------- |
| **syntax:** *ts.http.config_int_set(CONFIG, NUMBER)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to overwrite the configuration options. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| ts.http.config_int_set(TS_LUA_CONFIG_HTTP_CACHE_HTTP, 0) -- bypass the cache processor |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.config_float_get |
| ------------------------ |
| **syntax:** *val = ts.http.config_float_get(CONFIG)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** Configuration option which has a float value can be retrieved with this function. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.config_float_set |
| ------------------------ |
| **syntax:** *ts.http.config_float_set(CONFIG, NUMBER)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to overwrite the configuration options. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.config_string_get |
| ------------------------- |
| **syntax:** *val = ts.http.config_string_get(CONFIG)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** Configuration option which has a string value can be retrieved with this function. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.config_string_set |
| ------------------------- |
| **syntax:** *ts.http.config_string_set(CONFIG, NUMBER)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to overwrite the configuration options. |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| Http config constants |
| --------------------- |
| **context:** do_remap or do_global_* or later |
| |
| :: |
| |
| TS_LUA_CONFIG_URL_REMAP_PRISTINE_HOST_HDR |
| TS_LUA_CONFIG_HTTP_CHUNKING_ENABLED |
| TS_LUA_CONFIG_HTTP_NEGATIVE_CACHING_ENABLED |
| TS_LUA_CONFIG_HTTP_NEGATIVE_CACHING_LIFETIME |
| TS_LUA_CONFIG_HTTP_CACHE_WHEN_TO_REVALIDATE |
| TS_LUA_CONFIG_HTTP_KEEP_ALIVE_ENABLED_IN |
| TS_LUA_CONFIG_HTTP_KEEP_ALIVE_ENABLED_OUT |
| TS_LUA_CONFIG_HTTP_KEEP_ALIVE_POST_OUT |
| TS_LUA_CONFIG_HTTP_SHARE_SERVER_SESSIONS |
| TS_LUA_CONFIG_NET_SOCK_RECV_BUFFER_SIZE_OUT |
| TS_LUA_CONFIG_NET_SOCK_SEND_BUFFER_SIZE_OUT |
| TS_LUA_CONFIG_NET_SOCK_OPTION_FLAG_OUT |
| TS_LUA_CONFIG_HTTP_FORWARD_PROXY_AUTH_TO_PARENT |
| TS_LUA_CONFIG_HTTP_ANONYMIZE_REMOVE_FROM |
| TS_LUA_CONFIG_HTTP_ANONYMIZE_REMOVE_REFERER |
| TS_LUA_CONFIG_HTTP_ANONYMIZE_REMOVE_USER_AGENT |
| TS_LUA_CONFIG_HTTP_ANONYMIZE_REMOVE_COOKIE |
| TS_LUA_CONFIG_HTTP_ANONYMIZE_REMOVE_CLIENT_IP |
| TS_LUA_CONFIG_HTTP_ANONYMIZE_INSERT_CLIENT_IP |
| TS_LUA_CONFIG_HTTP_RESPONSE_SERVER_ENABLED |
| TS_LUA_CONFIG_HTTP_INSERT_SQUID_X_FORWARDED_FOR |
| TS_LUA_CONFIG_HTTP_SERVER_TCP_INIT_CWND |
| TS_LUA_CONFIG_HTTP_SEND_HTTP11_REQUESTS |
| TS_LUA_CONFIG_HTTP_CACHE_HTTP |
| TS_LUA_CONFIG_HTTP_CACHE_CLUSTER_CACHE_LOCAL |
| TS_LUA_CONFIG_HTTP_CACHE_IGNORE_CLIENT_NO_CACHE |
| TS_LUA_CONFIG_HTTP_CACHE_IGNORE_CLIENT_CC_MAX_AGE |
| TS_LUA_CONFIG_HTTP_CACHE_IMS_ON_CLIENT_NO_CACHE |
| TS_LUA_CONFIG_HTTP_CACHE_IGNORE_SERVER_NO_CACHE |
| TS_LUA_CONFIG_HTTP_CACHE_CACHE_RESPONSES_TO_COOKIES |
| TS_LUA_CONFIG_HTTP_CACHE_IGNORE_AUTHENTICATION |
| TS_LUA_CONFIG_HTTP_CACHE_CACHE_URLS_THAT_LOOK_DYNAMIC |
| TS_LUA_CONFIG_HTTP_CACHE_REQUIRED_HEADERS |
| TS_LUA_CONFIG_HTTP_INSERT_REQUEST_VIA_STR |
| TS_LUA_CONFIG_HTTP_INSERT_RESPONSE_VIA_STR |
| TS_LUA_CONFIG_HTTP_CACHE_HEURISTIC_MIN_LIFETIME |
| TS_LUA_CONFIG_HTTP_CACHE_HEURISTIC_MAX_LIFETIME |
| TS_LUA_CONFIG_HTTP_CACHE_GUARANTEED_MIN_LIFETIME |
| TS_LUA_CONFIG_HTTP_CACHE_GUARANTEED_MAX_LIFETIME |
| TS_LUA_CONFIG_HTTP_CACHE_MAX_STALE_AGE |
| TS_LUA_CONFIG_HTTP_KEEP_ALIVE_NO_ACTIVITY_TIMEOUT_IN |
| TS_LUA_CONFIG_HTTP_KEEP_ALIVE_NO_ACTIVITY_TIMEOUT_OUT |
| TS_LUA_CONFIG_HTTP_TRANSACTION_NO_ACTIVITY_TIMEOUT_IN |
| TS_LUA_CONFIG_HTTP_TRANSACTION_NO_ACTIVITY_TIMEOUT_OUT |
| TS_LUA_CONFIG_HTTP_TRANSACTION_ACTIVE_TIMEOUT_OUT |
| TS_LUA_CONFIG_HTTP_ORIGIN_MAX_CONNECTIONS |
| TS_LUA_CONFIG_HTTP_CONNECT_ATTEMPTS_MAX_RETRIES |
| TS_LUA_CONFIG_HTTP_CONNECT_ATTEMPTS_MAX_RETRIES_DEAD_SERVER |
| TS_LUA_CONFIG_HTTP_CONNECT_ATTEMPTS_RR_RETRIES |
| TS_LUA_CONFIG_HTTP_CONNECT_ATTEMPTS_TIMEOUT |
| TS_LUA_CONFIG_HTTP_POST_CONNECT_ATTEMPTS_TIMEOUT |
| TS_LUA_CONFIG_HTTP_DOWN_SERVER_CACHE_TIME |
| TS_LUA_CONFIG_HTTP_DOWN_SERVER_ABORT_THRESHOLD |
| TS_LUA_CONFIG_HTTP_CACHE_FUZZ_TIME |
| TS_LUA_CONFIG_HTTP_CACHE_FUZZ_MIN_TIME |
| TS_LUA_CONFIG_HTTP_DOC_IN_CACHE_SKIP_DNS |
| TS_LUA_CONFIG_HTTP_RESPONSE_SERVER_STR |
| TS_LUA_CONFIG_HTTP_CACHE_HEURISTIC_LM_FACTOR |
| TS_LUA_CONFIG_HTTP_CACHE_FUZZ_PROBABILITY |
| TS_LUA_CONFIG_NET_SOCK_PACKET_MARK_OUT |
| TS_LUA_CONFIG_NET_SOCK_PACKET_TOS_OUT |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.cntl_get |
| ---------------- |
| **syntax:** *val = ts.http.cntl_get(CNTL_TYPE)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to retireve the value of control channel. |
| |
| :: |
| |
| val = ts.http.cntl_get(TS_LUA_HTTP_CNTL_GET_LOGGING_MODE) |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.http.cntl_set |
| ---------------- |
| **syntax:** *ts.http.cntl_set(CNTL_TYPE, BOOL)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to set the value of control channel. |
| |
| Here is an example: |
| |
| :: |
| |
| function do_remap() |
| ts.http.cntl_set(TS_LUA_HTTP_CNTL_SET_LOGGING_MODE, 0) -- do not log the request |
| return 0 |
| end |
| |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| Http control channel constants |
| ------------------------------ |
| **context:** do_remap or do_global_* or later |
| |
| :: |
| |
| TS_LUA_HTTP_CNTL_GET_LOGGING_MODE |
| TS_LUA_HTTP_CNTL_SET_LOGGING_MODE |
| TS_LUA_HTTP_CNTL_GET_INTERCEPT_RETRY_MODE |
| TS_LUA_HTTP_CNTL_SET_INTERCEPT_RETRY_MODE |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.mgmt.get_counter |
| ------------------- |
| **syntax:** *val = ts.mgmt.get_counter(RECORD_NAME)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to retrieve the record value which has a counter type. |
| |
| :: |
| |
| n = ts.mgmt.get_counter('proxy.process.http.incoming_requests') |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.mgmt.get_int |
| --------------- |
| **syntax:** *val = ts.mgmt.get_int(RECORD_NAME)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to retrieve the record value which has a int type. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.mgmt.get_float |
| ----------------- |
| **syntax:** *val = ts.mgmt.get_float(RECORD_NAME)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to retrieve the record value which has a float type. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| ts.mgmt.get_string |
| ------------------ |
| **syntax:** *val = ts.mgmt.get_string(RECORD_NAME)* |
| |
| **context:** do_remap or do_global_* or later. |
| |
| **description:** This function can be used to retrieve the record value which has a string type. |
| |
| :: |
| |
| name = ts.mgmt.get_string('proxy.config.product_name') |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| Todo |
| ==== |
| * ts.fetch |
| * ts.cache_xxx |
| * `support lua-5.2 <https://github.com/portl4t/ts-lua/wiki/support-Lua-5.2>`_ |
| |
| Currently when we use ts_lua as a global plugin, each global hook is using a separate lua state for the same |
| transaction. This can be wasteful. Also the state cannot be reused for the same transaction across the global hooks. The |
| alternative will be to use a TXN_START hook to create a lua state first and then add each global hook in the lua script |
| as transaction hook instead. But this will have problem down the road when we need to have multiple plugins to work |
| together in some proper orderings. In the future, we should consider different approach, such as creating and |
| maintaining the lua state in the ATS core. |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
| More docs |
| ========= |
| |
| * https://github.com/portl4t/ts-lua |
| |
| `TOP <#ts-lua-plugin>`_ |
| |
