Doc

Jump to bottom Edit New page

clyang edited this page Apr 17, 2016 · 84 revisions

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.

Table of Contents

Status
Version
Synopsis
remap.config
TS API for Lua
Todo
See Also

Status

This module is under active development and is production ready.

Version

This document describes ts-lua v0.1.6 released on 13 March 2015.

Synopsis

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

test_sleep.lua

function send_response()
    ts.client_response.header['Hello'] = ts.ctx['hello']
    ts.sleep(3)
end

function read_response()
    ts.sleep(3)
end

function do_remap()
    ts.hook(TS_LUA_HOOK_READ_RESPONSE_HDR, read_response)
    ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response)
end

test_ransform.lua

function upper_transform(data, eos)
    return string.upper(data), eos
end

function do_remap()
    ts.hook(TS_LUA_RESPONSE_TRANSFORM, upper_transform)
    ts.http.resp_cache_transformed(0)
    ts.http.resp_cache_untransformed(1)
    return 0
end

test_cache_lookup.lua

function send_response()
    ts.client_response.header['CStatus'] = ts.ctx['cstatus']
end

function cache_lookup()
    local cache_status = ts.http.get_cache_lookup_status()
    ts.ctx['cstatus'] = cache_status
end

function do_remap()
    ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response)
    ts.hook(TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE, cache_lookup)
    return 0
end

test_intercept.lua

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

remap.config

This module acts as remap plugin of Apache Traffic Server, and 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/libtslua.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(sethost.lua is a reference), and we can write this in remap.config:

map http://a.t.cn/ http://b.t.cn/ @plugin=/X/libtslua.so @pparam=/X/sethost.lua @pparam=a.st.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. This package can be introduced into Lua like this:

ts.say('Hello World')
ts.sleep(10)

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

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

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.

See also ts.client_request.set_url_host

ts.hook

syntax: ts.hook(HOOK_POINT, FUNCTION)

context: do_remap 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()
    ts.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
...

Hook point constants

context: do_remap or later

TS_LUA_HOOK_POST_REMAP
TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE
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.

ts.ctx

syntax: ts.ctx[KEY] = VALUE

syntax: VALUE = ts.ctx[KEY]

context: do_remap 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
...

ts.client_request.get_method

syntax: ts.client_request.get_method()

context: do_remap or later

description: This function can be used to retrieve the current client request's method name. String like "GET" or "POST" is returned.

See also ts.client_request.set_method

ts.client_request.set_method

syntax: ts.client_request.set_method()

context: do_remap

description: This function can be used to override the current client request's method with METHOD_NAME.

See also ts.client_request.get_method

ts.client_request.get_version

syntax: ver = ts.client_request.get_version()

context: do_remap or later

description: Return the http version string of the client request.

Current possible values are 1.0, 1.1, and 0.9.

ts.client_request.set_version

syntax: ts.client_request.set_version(VERSION_STR)

context: do_remap or later

description: Set the http version of the client request with the VERSION_STR

ts.client_request.set_version('1.0')

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

See also ts.client_request.set_uri

ts.client_request.set_uri

syntax: ts.client_request.set_uri(PATH)

context: do_remap

description: This function can be used to override the client request's path.

The PATH argument must be a Lua string and starts with /

See also ts.client_request.get_uri

ts.client_request.get_uri_args

syntax: ts.client_request.get_uri_args()

context: do_remap 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

See also ts.client_request.set_uri_args

ts.client_request.set_uri_args

syntax: ts.client_request.set_uri_args(QUERY_STRING)

context: do_remap

description: This function can be used to override the client request's query string.

ts.client_request.set_uri_args('n=6&p=7')

See also ts.client_request.get_uri_args

ts.client_request.get_url

syntax: ts.client_request.get_url()

context: do_remap 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

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 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

See also ts.client_request.get_headers

ts.client_request.get_headers

syntax: ts.client_request.get_headers()

context: do_remap 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: */*

See also ts.client_request.header.HEADER

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.

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

ts.client_request.get_url_host

syntax: host = ts.client_request.get_url_host()

context: do_remap 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

ts.client_request.set_url_host

syntax: ts.client_request.set_url_host(str)

context: do_remap

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

ts.client_request.get_url_port

syntax: port = ts.client_request.get_url_port()

context: do_remap 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

See also ts.client_request.set_url_port, ts.client_request.get_url_host

ts.client_request.set_url_port

syntax: ts.client_request.set_url_port(NUMBER)

context: do_remap

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.

See also ts.client_request.get_url_host, ts.client_request.set_url_host

ts.client_request.get_url_scheme

syntax: scheme = ts.client_request.get_url_scheme()

context: do_remap 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

See also ts.client_request.set_url_scheme

ts.client_request.set_url_scheme

syntax: ts.client_request.set_url_scheme(str)

context: do_remap

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.

See also ts.client_request.get_url_scheme, ts.client_request.set_url_host

ts.client_request.get_pristine_url

syntax: ts.client_request.get_pristine_url()

context: do_remap or later

description: Get the pristine url of the client request.

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 client request.

Here is an example:

function do_remap()
    ts.http.set_cache_url('http://a.tbcdn.cn/foo')
    return 0
end

ts.http.set_resp

syntax: ts.http.set_resp(CODE, BODY)

context: do_remap

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 :)

See also ts.http.redirect

ts.http.redirect

syntax: ts.http.redirect(URL)

context: do_remap

description: This function can be used to issue an HTTP 302 redirection to URL and we should return TS_LUA_REMAP_DID_REMAP_STOP in do_remap.

Here is an example:

function do_remap()
    ts.http.redirect('http://www.taobao.com/')
    return TS_LUA_REMAP_DID_REMAP_STOP
end

We will get the response like this:

HTTP/1.1 302 Redirect
Date: Thu, 20 Mar 2014 06:20:07 GMT
Connection: close
Server: ATS/5.0.0
Cache-Control: no-store
Content-Type: text/html; charset=utf-8
Content-Language: en
Location: http://www.taobao.com/
...

See also ts.http.set_resp

ts.http.is_internal_request

syntax: ts.http.is_internal_request()

context: do_remap or later

description: This function can be used to indicate whether current request is an internal request(issued by fetch or sth). 1 means true, otherwise 0.

Here is an example:

function do_remap()
    local inner = ts.http.is_internal_request()
    if inner ~= 0 then
        print('Internal request.')
    else
        print('Not internal request.')
    end
end

See also ts.fetch ts.fetch_multi

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

See also ts.http.set_cache_lookup_status and Http cache lookup status constants

ts.http.set_cache_lookup_status

syntax: ts.http.set_cache_lookup_status(status)

context: function @ TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE hook point

description: This function can be used to set 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')
        ts.http.set_cache_lookup_status(TS_LUA_CACHE_LOOKUP_MISS)
    end
end

function do_remap()
    ts.hook(TS_LUA_HOOK_CACHE_LOOKUP_COMPLETE, cache_lookup)
    return 0
end

See also ts.http.get_cache_lookup_status and Http cache lookup status constants

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)

See also ts.http.get_cache_lookup_status and ts.http.set_cache_lookup_status

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

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.

See also ts.client_request.get_version

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

See also ts.cached_response.get_headers

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

See also ts.cached_response.header.HEADER

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

See also ts.server_request.set_uri

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 /

See also ts.server_request.get_uri

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

See also ts.server_request.set_uri_args

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')

See also ts.server_request.get_uri_args

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

See also ts.server_request.get_headers

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: */*

See also ts.server_request.header.HEADER

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

See also ts.server_response.set_status

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

See also ts.server_response.get_status

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.

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')

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

See also ts.server_response.get_headers

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

See also ts.server_response.header.HEADER

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

See also ts.client_response.set_status

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

See also ts.client_response.get_status

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.

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')

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

See also ts.client_response.get_headers

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

See also ts.client_response.header.HEADER

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 :(

See also ts.http.set_resp

Number constants

context: global

TS_LUA_INT64_MAX
TS_LUA_INT64_MIN
TS_LUA_INT32_MAX
TS_LUA_INT32_MIN
TS_LUA_UINT32_MAX

These constants are usually used in transform handler.

These constants were first introduced in the v0.1.5 release.

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.

This function is usually called after we hook TS_LUA_RESPONSE_TRANSFORM.

See also ts.http.resp_cache_untransformed

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.

This function is usually called after we hook TS_LUA_RESPONSE_TRANSFORM.

See also ts.http.resp_cache_transformed

ts.http.resp_transform.get_upstream_bytes

syntax: ts.http.resp_transform.get_upstream_bytes()

context: transform handler

description: This function can be used to retrive the total bytes to be received from the upstream. If we got chunked response body from origin server, TS_LUA_INT64_MAX will be returned.

Here is an example:

local APPEND_DATA = 'TAIL\n'
local APPEND_SIZE = string.len(APPEND_DATA)

function append_transform(data, eos)
    if ts.ctx['len_set'] == nil then
        local sz = ts.http.resp_transform.get_upstream_bytes()
        if sz ~= TS_LUA_INT64_MAX then
            ts.http.resp_transform.set_downstream_bytes(sz + APPEND_SIZE)
        end
        ts.ctx['len_set'] = true
    end
    if eos == 1 then
        return data .. APPEND_DATA, eos
    else
        return data, eos
    end
end

function do_remap()
    ts.hook(TS_LUA_RESPONSE_TRANSFORM, append_transform)
    ts.http.resp_cache_transformed(0)
    ts.http.resp_cache_untransformed(1)
    return 0
end

This feature was first introduced in the v0.1.5 release.

See also ts.http.resp_transform.set_downstream_bytes

ts.http.resp_transform.set_downstream_bytes

syntax: ts.http.resp_transform.set_downstream_bytes(NUMBER)

context: transform handler

description: This function can be used to set the total bytes to be sent to the downstream.

Sometimes we want to set Content-Length header in client_response, and this function should be called before any real data is returned from the transform handler.

This feature was first introduced in the v0.1.5 release.

See also ts.http.resp_transform.get_upstream_bytes

ts.re.match

syntax: captures = ts.re.match(subject, regex, options?)

context: do_remap or later

description: Matches a compiled regular expression regex against a given subject string. When a match is found, a Lua table captures is returned. If no match is found, nil will be returned.

Here is an example:

function do_remap()
    local captures = ts.re.match('<name>ZhanNaiZhen</name>', '<(.*)>(.*)<(.*)>')
    if captures then
        -- captures[0] == "name"
        -- captures[1] == "ZhanNaiZhen"
        -- captures[2] == "/name"
    end
end

Specify "options" to control how the match operation will be performed. The following option characters are supported:

a             anchored mode

i             Do caseless matching

m             multi-line mode (^ and $ match newlines within data)

u             Invert greediness of quantifiers

s             . matches anything including NL

x             Ignore white space and # comments

d             $ not to match newline at 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

This method was first introduced in the v0.1.2 release.

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

This method was first introduced in the v0.1.2 release.

ts.base64_encode

syntax: newstr = ts.base64_encode(str)

context: global

description: Encode a string using Base64.

Here is an example:

function do_remap()
    uri = ts.client_request.get_uri()
    print(uri)                      -- /foo
    print(ts.base64_encode(uri))    -- L2Zvbw==
end

See also ts.base64_decode

ts.base64_decode

syntax: newstr = ts.base64_decode(str)

context: global

description: Decode a Base64 encoded string.

Here is an example:

function do_remap()
    print(ts.base64_decode('L2Zvbw=='))     -- /foo
end

See also ts.base64_encode

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

See also ts.md5_bin

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

See also ts.md5

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

See also ts.sha1_bin

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

See also ts.sha1

ts.escape_uri

syntax: newstr = ts.escape_uri(str)

context: global

description: Escape str as a URI component.

Here is an example:

function do_remap()
    uri = 'https://github.com/portl4t/ts-lua'
    escape = ts.escape_uri(uri)     -- https%3a%2f%2fgithub.com%2fportl4t%2fts-lua
end

This method was first introduced in the v0.1.4 release.

See also ts.unescape_uri

ts.unescape_uri

syntax: newstr = ts.unescape_uri(str)

context: global

description: Unescape str as an escaped URI component.

Here is an example:

function do_remap()
    str = 'https%3a%2f%2fgithub.com%2fportl4t%2fts-lua'
    unescape = ts.unescape_uri(str)     -- https://github.com/portl4t/ts-lua
end

This method was first introduced in the v0.1.4 release.

See also ts.escape_uri

ts.fetch

syntax: res = ts.fetch(url, table?)

context: after do_remap

description: Issues a synchronous but still non-block http request with the url and the optional table.

Returns a Lua table with serveral slots (res.status, res.header, res.body, and res.truncated).

res.status holds the response status code.

res.header holds the response header table.

res.body holds the response body which may be truncated, you need to check res.truncated to see if the data is truncated.

Here is a basic example:

function post_remap()
    local url = string.format('http://%s/foo.txt', ts.ctx['host'])
    local res = ts.fetch(url)
    if res.status == 200 then
        print(res.body)
    end
end

function do_remap()
    local inner = ts.http.is_internal_request()
    if inner ~= 0 then
        return 0
    end
    local host = ts.client_request.header['Host']
    ts.ctx['host'] = host
    ts.hook(TS_LUA_HOOK_POST_REMAP, post_remap)
end

We can set the optional table with serveral members:

header holds the request header table.

method holds the request method. The default method is 'GET'.

body holds the request body.

cliaddr holds the request client address in ip:port form. The default cliaddr is '127.0.0.1:33333'

Issuing a post request:

res = ts.fetch('http://xx.com/foo', {method = 'POST', body = 'hello world'})

This method was first introduced in the v0.1.6 release.

See also ts.fetch_multi ts.http.is_internal_request

ts.fetch_multi

syntax: vec = ts.fetch_multi({{url, table?}, {url, table?}, ...})

context: after do_remap

Just like ts.fetch, but supports multiple http requests running in parallel.

This function will fetch all the urls specified by the input table and return a table which contain all the results in the same order.

Here is an example:

local vec = ts.fetch_multi({
                {'http://xx.com/slayer'},
                {'http://xx.com/am', {cliaddr = '192.168.1.19:35423'}},
                {'http://xx.com/naga', {method = 'POST', body = 'hello world'}},
            })

for i = 1, #(vec) do
    print(vec[i].status)
end

This method was first introduced in the v0.1.6 release.

See also ts.fetch ts.http.is_internal_request

ts.http.intercept

syntax: ts.http.intercept(FUNCTION, param1?, param2?, ...)

context: do_remap

description: Intercepts the client request and processes it in FUNCTION with optional params.

We should construct the response for the client request, and the request will not be processed by other modules, like hostdb, cache, origin server...

Intercept FUNCTION will be executed in a new lua_thread, so we can delivery optional params from old lua_thread to new lua_thread if needed.

Here is an example:

require 'os'

function send_data(dstr)
    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

    print(dstr)
    ts.say(resp)
end

function do_remap()
    ts.http.intercept(send_data, 'hello world')
    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.

See also ts.http.server_intercept

ts.http.server_intercept

syntax: ts.http.server_intercept(FUNCTION, param1?, param2?, ...)

context: do_remap

description: Intercepts the server request and acts as the origin server.

Just like ts.http.intercept, but this function will intercept the server request, and we can acts as the origin server in FUNCTION.

See also ts.http.intercept

ts.say

syntax: ts.say(data)

context: intercept or server_intercept

description: Write response to ATS within intercept or server_intercept.

See also ts.http.intercept

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

ts.sleep

syntax: ts.sleep(sec)

context: after do_remap

description: Sleeps for the specified seconds without blocking.

Behind the scene, this method makes use of the ATS event model.

Here is an example:

function send_response()
    ts.sleep(1)
end

function read_response()
    ts.sleep(1)
end

function do_remap()
    ts.hook(TS_LUA_HOOK_READ_RESPONSE_HDR, read_response)
    ts.hook(TS_LUA_HOOK_SEND_RESPONSE_HDR, send_response)
end

Cache operation constants

context: global

TS_LUA_CACHE_READ (1)
TS_LUA_CACHE_WRITE (2)

These constants are usually used in ts.cache_open.

These constants were first introduced in the v0.1.7 release.

See also ts.cache_open

ts.cache_open

syntax: fdt = ts.cache_open(keystr, OPERATION_MODE, option?)

context: after do_remap

description: This function opens the cachevc whose name is the keystr and associateds a stream with it.

The param OPERATION_MODE indicates the cache operation type, can be TS_LUA_CACHE_READ or TS_LUA_CACHE_WRITE.

The param option is a string, each character has a meaning:

u      regard keystr as an url

h      regard the cache object as http data

Returns a descriptor table with serveral slots.

fdt.hit indicates whether the cache object is hit(only for TS_LUA_CACHE_READ).

fdt.size indicates the cache object size(only for TS_LUA_CACHE_READ).

Here is an example:

local rfd = ts.cache_open('transformer.txt', TS_LUA_CACHE_READ)
if ts.cache_err(rfd) ~= true and rfd.hit
then
    d = ts.cache_read(rfd)
    ts.cache_close(rfd)
    print(d)
else
    print('miss')
end

See also ts.cache_read ts.cache_write ts.cache_err

ts.cache_read

syntax: datastr = ts.cache_read(fdt, size?)

context: after do_remap

description: This function reads cache data from descriptor table fdt.

The param size indicates how many bytes to read.

The function will return if enough data has been read. If an error occurs or the end-of-file is reached, the function also returns.

See also ts.cache_write ts.cache_err

ts.cache_write

syntax: num = ts.cache_write(fdt, datastr, size?)

context: after do_remap

description: This function writes datastr to the descriptor table fdt.

The param size indicates how many bytes to write.

Returns a number represents how many bytes have been writen.

The function will return if enough data has been writen. If an error occurs, the function also returns.

Here is an example:

local fd = ts.cache_open('transformer.txt', TS_LUA_CACHE_WRITE)
local n = ts.cache_write(fd, 'Optimus Prime.')
print(string.format('write %d bytes', n))
ts.cache_close(fd)

See also ts.cache_read ts.cache_err

ts.cache_close

syntax: ts.cache_close(fdt)

context: after do_remap

description: This function close the descriptor table fdt.

See also ts.cache_open

ts.cache_eof

syntax: res = ts.cache_eof(fdt)

context: after do_remap

description: This function indicates whether end-of-file is reached. The descriptor table fdt should be opened for read.

Returns true if end-of-file is reached, otherwise false.

Here is an example:

local rfd = ts.cache_open('http://foo.com/large.pdf', TS_LUA_CACHE_READ, 'uh')
if rfd.hit then
    while ts.cache_eof(rfd) ~= true do
        d = ts.cache_read(rfd, 1024*1024*5)
        if ts.cache_err(rfd) then
            break
        end
        print(string.len(d))
    end
    ts.cache_close(rfd)
else
    print('miss')
end

See also ts.cache_open

ts.cache_err

syntax: res = ts.cache_err(fdt)

context: after do_remap

description: This function indicates whether error exists.

Returns true if an error occurs, otherwise false.

See also ts.cache_open

ts.http.config_int_get

syntax: val = ts.http.config_int_get(CONFIG)

context: do_remap 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)

See also ts.http.config_int_set

ts.http.config_int_set

syntax: ts.http.config_int_set(CONFIG, NUMBER)

context: do_remap 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

See also ts.http.config_int_get

ts.http.config_float_get

syntax: val = ts.http.config_float_get(CONFIG)

context: do_remap or later.

description: Configuration option which has a float value can be retrieved with this function.

See also ts.http.config_float_set

ts.http.config_float_set

syntax: ts.http.config_float_set(CONFIG, NUMBER)

context: do_remap or later.

description: This function can be used to overwrite the configuration options.

See also ts.http.config_float_get

ts.http.config_string_get

syntax: val = ts.http.config_string_get(CONFIG)

context: do_remap or later.

description: Configuration option which has a string value can be retrieved with this function.

See also ts.http.config_string_set

ts.http.config_string_set

syntax: ts.http.config_string_set(CONFIG, NUMBER)

context: do_remap or later.

description: This function can be used to overwrite the configuration options.

See also ts.http.config_string_get

Http config constants

context: do_remap 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

ts.http.cntl_get

syntax: val = ts.http.cntl_get(CNTL_TYPE)

context: do_remap 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)

See also ts.http.cntl_set

ts.http.cntl_set

syntax: ts.http.cntl_set(CNTL_TYPE, BOOL)

context: do_remap 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

See also ts.http.cntl_get

Http control channel constants

context: do_remap 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

ts.mgmt.get_counter

syntax: val = ts.mgmt.get_counter(RECORD_NAME)

context: do_remap 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')

ts.mgmt.get_int

syntax: val = ts.mgmt.get_int(RECORD_NAME)

context: do_remap or later.

description: This function can be used to retrieve the record value which has a int type.

ts.mgmt.get_float

syntax: val = ts.mgmt.get_float(RECORD_NAME)

context: do_remap or later.

description: This function can be used to retrieve the record value which has a float type.

ts.mgmt.get_string

syntax: val = ts.mgmt.get_string(RECORD_NAME)

context: do_remap 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')

ts.shared.DICT

syntax: dict = ts.shared.DICT(name, opt_table?)

context: init stage of the lua script

description: Create a shared dictionary which can be accessed by all lua_States.

Here is an example:

local ft = ts.shared.DICT('fruit',
                                {
                                    ['quota'] = 1024 * 1024 * 90,
                                    ['options'] = 's'
                                })

function do_remap()
    ft:set('apple', 5)
    ft:set('banana', 'hello')
    print(ft:get('apple'))
    return 0
end

We will get the output:

5

Specify opt_table to control how the dictionary will be created. The following fields are supported:

quota         the max bytes can be used by dictionary (no quota means no limit)

options       ('i': all keys are number, 's': dictionary will not be updated after init.)

The resulting object dict has the following methods:

init
set
get
del
get_keys

ts.shared.DICT.init

syntax: ts.shared.DICT:init(FUNCTION)

context: init stage of the lua script

description: Init the dict within FUNCTION.

The dict will be passed to the FUNCTION as a parameter.

Here is an example:

local ft = ts.shared.DICT('fruit')
ft:init(function(shdct)
            shdct:set('oscar', 'new year')
        end)

function do_remap()
    print(ft:get('oscar'))
    return 0
end

Then we will get the output:

new year

ts.shared.DICT.set

syntax: success, errmsg = ts.shared.DICT:set(key, val)

context: global

Sets a key-value pair into the dictionary. Returns two values:

success: boolean value to indicate whether the key-value pair is stored or not.
errmsg: textual error message, can be "no memory".

The key and val argument inserted can be Lua booleans, numbers, strings.

See also ts.shared.DICT

ts.shared.DICT.get

syntax: val = ts.shared.DICT:get(key)

context: global

Retrieving the value in the dictionary for the key key. If the key does not exist, then nil will be returned.

See also ts.shared.DICT

ts.shared.DICT.del

syntax: ts.shared.DICT:del(key)

context: global

Removes the key-value pair from the dictionary.

ft:del('oscar')

See also ts.shared.DICT

ts.shared.DICT.get_keys

syntax: vector = ts.shared.DICT:get_keys(max_count?)

context: global

Fetch a list of the keys from the dictionary, up to max_count.

Here is an example:

local ft = ts.shared.DICT('fruit')
function do_remap()
    ft:set('apple', 5)
    ft:set('banana', 9)
    ft:set('cherry', 78)
    kt = ft:get_keys()
    for k, v in pairs(kt) do
        print(k)
        print(v)
    end
end

Then we will get the output:

1
cherry
2
banana
3
apple

See also ts.shared.DICT

Todo

protocol
net socket

See Also

ts-fetcher http fetcher for ats, implement as plugin with c