TS-2844: update documentation for ESI plugin
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/84517e51 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/84517e51 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/84517e51 Branch: refs/heads/5.0.x Commit: 84517e5129156ea3325d9337fa2e9158f13dab13 Parents: 9a3e5de Author: Kit Chan <[email protected]> Authored: Sun May 25 01:04:24 2014 -0700 Committer: Kit Chan <[email protected]> Committed: Sun May 25 01:04:24 2014 -0700 ---------------------------------------------------------------------- doc/reference/plugins/esi.en.rst | 132 +++++++++++++++++++++++++++++++++- plugins/experimental/esi/README | 96 ------------------------- 2 files changed, 130 insertions(+), 98 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/84517e51/doc/reference/plugins/esi.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/plugins/esi.en.rst b/doc/reference/plugins/esi.en.rst index 18b050a..4b37455 100644 --- a/doc/reference/plugins/esi.en.rst +++ b/doc/reference/plugins/esi.en.rst @@ -1,7 +1,7 @@ .. _esi-plugin: -ESI Plugin (undocumented) -************************* +ESI Plugin +********** .. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file @@ -22,3 +22,131 @@ ESI Plugin (undocumented) This plugin implements the ESI specification. + +Specification +============= + +Supportted ESI tags: + +:: + + esi:include + esi:remove + esi:comment + esi:vars + esi:choose + esi:when + esi:otherwise + esi:try + esi:attempt + esi:except + <!--esi ... --> + +extended ESI tags: *esi:special-include* + +Supported variables: + +:: + + $(HTTP_HOST) + $(HTTP_REFERER) + $(HTTP_ACCEPT_LANGUAGE{name}) + $(HTTP_COOKIE{name}) or $(HTTP_COOKIE{name;subkey}) + $(QUERY_STRING{name}) + +Note: the name is the key name such as "username", "id" etc. For cookie support sub-name or sub-key, the format is: +name;subkey, such as "l;u", "l;t" etc. e.g. such cookie string: l=u=test&t=1350952328, the value of +$(HTTP_COOKIE{"l;u"}) is test and the value of $(HTTP_COOKIE{"l;t"}) is 1350952328 + +Compile and Installation +======================== + +This plugin is only built if the configure option :: + + --enable-experimental-plugins + +is given at build time. Note that this plugin is built and installed in combination with the ESI module, since they +share common code. + +Enabling ESI +============ + +1. First we need to set up /usr/local/etc/trafficserver/plugin.config and make sure the following line is present. + +:: + + esi.so + +2. There are four options you can add to the above. + +- "--private-response" will add private cache control and expires header to the processed ESI document. +- "--packed-node-support" will enable the support for using packed node, which will improve the performance of parsing + cached ESI document. +- "--disable-gzip-output" will disable gzipped output, which will NOT gzip the output anyway. +- "--first-byte-flush" will enable the first byte flush feature, which will flush content to users as soon as the entire + ESI document is received and parsed without all ESI includes fetched (the flushing will stop at the ESI include markup + till that include is fetched). + +3. We need a mapping for origin server response that contains the ESI markup. Assume that the ATS server is abc.com. And + your And your origin server is xyz.com and the response containing ESI markup is http://xyz.com/esi.php. We will need + the following line in /usr/local/etc/trafficserver/remap.config + +:: + + map http://abc.com/esi.php http://xyz.com/esi.php + +4. Your response should contain ESI markup and a response header of .X-Esi: 1'. e.g. using PHP, + +:: + + <?php header('X-Esi: 1'); ?> + <html> + <body> + Hello, <esi:include src="http://abc.com/date.php"/> + </body> + </html> + +5. You will need a mapping for the src of the ESI include in remap.config if it is not already present. + +:: + + map http://abc.com/date.php http://xyz.com/date.php + +Or if both your ESI response and the ESI include comes from the same origin server, you can have the following line in +remap.config instead to replace separate map rules for date.php and esi.php + +:: + + map http://abc.com/ http://xyz.com/ + +6. Here is a sample PHP for date.php + +:: + + <?php + header ("Cache-control: no-cache"); + echo date('l jS \of F Y h:i:s A'); + ?> + +Useful Note +=========== + +1. You can provide proper cache control header and the ESI response and ESI include response can be cached separately. +It is extremely useful for rendering page with multiple modules. The page layout can be a ESI response with multiple ESI +include, each for different module. The page layour ESI response can be cached and each individual ESI include can also +be cached with different duration. + +2. You might want to compile the code without using ESI_PACKED_NODE_SUPPORT because it may not work in some corner cases + +Differences from Spec - http://www.w3.org/TR/esi-lang +===================================================== + +1. <esi:include> does not support "alt" and "onerror" attributes + +2. <esi:inline> is not supported + +3. You cannot have <esi:try> inside another <esi:try> + +4. HTTP_USER_AGENT variable is not supported + +5. HTTP_COOKIE supports fetching for sub-key http://git-wip-us.apache.org/repos/asf/trafficserver/blob/84517e51/plugins/experimental/esi/README ---------------------------------------------------------------------- diff --git a/plugins/experimental/esi/README b/plugins/experimental/esi/README index 36657ed..8d88daa 100644 --- a/plugins/experimental/esi/README +++ b/plugins/experimental/esi/README @@ -3,99 +3,3 @@ ESI plugin This plugin implements the ESI specification. -Supportted ESI tags: - esi:include - esi:remove - esi:comment - esi:vars - esi:choose - esi:when - esi:otherwise - esi:try - esi:attempt - esi:except - <!--esi ... --> - -extended ESI tags: - esi:special-include - -Supported variables: - $(HTTP_HOST) - $(HTTP_REFERER) - $(HTTP_ACCEPT_LANGUAGE{name}) - $(HTTP_COOKIE{name}) or $(HTTP_COOKIE{name;subkey}) - $(QUERY_STRING{name}) - - Note: the name is the key name such as "username", "id" etc. - cookie support sub-name or sub-key, the format is: name;subkey, such as "l;u", "l;t" etc. - fg. such cookie string: l=u=test&t=1350952328, the value of $(HTTP_COOKIE{"l;u"}) is test - and the value of $(HTTP_COOKIE{"l;t"}) is 1350952328 - - -Compile and Installation ------------------------- - -1) Just run "make" in the directory of trafficserver/plugins/experimental/esi/ - -2) Copy trafficserver/plugins/experimental/esi/.libs/esi.* to /usr/local/libexec/trafficserver/ - -Enabling ESI ------------- - -1) First we need to set up /usr/local/etc/trafficserver/plugin.config and make sure the following line is present - -esi.so - -There are four options you can add. - "--private-response" will add private cache control and expires header to the processed ESI document. - "--packed-node-support" will enable the support for using packed node, which will improve the performance of parsing cached ESI document. - "--disable-gzip-output" will disable gzipped output, which will NOT gzip the output anyway. - "--first-byte-flush" will enable the first byte flush feature, which will flush content to users as soon as the entire ESI document is received and parsed without all ESI includes fetched (the flushing will stop at the ESI include markup till that include is fetched). - -2) We need a mapping for origin server response that contains the ESI markup. Assume that the ATS server is abc.com. And your origin server is xyz.com and the response containing ESI markup is http://xyz.com/esi.php. We will need the following line in /usr/local/etc/trafficserver/remap.config - -map http://abc.com/esi.php http://xyz.com/esi.php - -3) Your response should contain ESI markup and a response header of .X-Esi: 1'. e.g. using PHP, - -<?php header('X-Esi: 1'); ?> -<html> -<body> -Hello, <esi:include src="http://abc.com/date.php"/> -</body> -</html> - -4) You will need a mapping for the src of the ESI include in remap.config if it is not already present. - -map http://abc.com/date.php http://xyz.com/date.php - -Or if both your ESI response and the ESI include comes from the same origin server, you can have the following line in remap.config instead to replace separate map rules for date.php and esi.php - -map http://abc.com/ http://xyz.com/ - -5) Here is a sample PHP for date.php - -<?php - header ("Cache-control: no-cache"); - echo date('l jS \of F Y h:i:s A'); -?> - -Useful Note ------------ - -1) You can provide proper cache control header and the ESI response and ESI include response can be cached separately. It is extremely useful for rendering page with multiple modules. The page layout can be a ESI response with multiple ESI include, each for different module. The page layour ESI response can be cached and each individual ESI include can also be cached with different duration. - -2) You might want to compile the code without using ESI_PACKED_NODE_SUPPORT because it may not work in some corner cases - -Differences from Spec - http://www.w3.org/TR/esi-lang ------------------------------------------------------ - -1) <esi:include> does not support "alt" and "onerror" attributes - -2) <esi:inline> is not supported - -3) You cannot have <esi:try> inside another <esi:try> - -4) HTTP_USER_AGENT variable is not supported - -5) HTTP_COOKIE supports fetching for sub-key
