Fragments and templates

Any web application can be used to provide html fragments or page templates for other applications. Fragments are defined using ESI tags.

Cross technologies

As we only use ESI tags inside application pages, an application may have been developed with any technology, including Java, PHP or .NET and work with ESIGate.

Reverse proxy

ESIGate works as a reverse-proxy and can be used to retrieve and cache static contents (images, css, js...) as well a dynamic contents.

Pages aggregator

ESIGate parses html pages and processes ESI instructions in order to merge pages, fragments from several applications.

ESI 1.0 specification support

ESIGate fully implements ESI specification and adds some useful custom extensions.

Xpath expressions and XSLT

Tools are also provided to retrieve and transform pages using regular expressions, xpath expressions and to apply on-the-fly XSLT transformations. Xpath and XSLT can be used even with malformed html documents.

HTTP 1.1 Cache

In order to improve performance, the tool uses a cache that fully implements HTTP 1.1 specification. In addition the cache is highly configurable to help you improve cache efficiency and overall performance of your web site.

User context and Single Sign On

Applications may have to share informations about connected users. ESIGate provided a CAS module supporting the proxy authentication mode and the JASIG CAS client. The extension mechanism lets you integrate other Single Sign On systems if needed.

esigate.properties

Then you have to configure esigate.properties which defines provider applications, mappings, network and caching parameters... All details in chapter Configuration

Here is an example configuration, with 4 providers using different mapping types :

# Sample 1 : process all urls	        
provider1.remoteUrlBase=http://host1/
provider1.mappings=/*

# Sample 2 : virtual host configuration
# Process requests made for myhost 
provider2.remoteUrlBase=http://host2/
provider2.mappings=http://myhost/* 

# Sample 3 : Process all php files
provider3.remoteUrlBase=http://host3/
provider3.mappings=*.php

# Sample 4 : Process all files in css and images directories
theme.remoteUrlBase=http://host4/
theme.mappings=/css/*, /images/*

# Sample 5 : Process all files in css and images directories and strip mapping path
theme.remoteUrlBase=http://host4/css-and-images/
theme.mappings=/css/*, /images/*
theme.stripMappingPath=true


	

Each application can use ESI tags in its html pages to include some fragments coming from the other.

Configuration file

ESIGate default behavior is to load a configuration file from the classpath /esigate.properties

Alternatively you can use method org.esigate.DriverFactory.configure(Properties) .

Configuration directives

Local and cross-context providers

You can use local resources or resources from another web application deployed on the same server by using extension org.esigate.servlet.ServletExtension

Advantages:

• Use local resources and apply to them esi transformation
• Use resources from another web application without network calls

# In this example, we use 2 providers: local and crosscontext
# Local context. Local resources may contain esi tags
local.remoteUrlBase=http://localhost:8080/esigate/
local.extensions=org.esigate.servlet.ServletExtension,org.esigate.extension.Esi
local.mappings=*

# Another web application deployed in the same servlet container
crosscontext.remoteUrlBase=http://localhost:8080/myWebapp/
crosscontext.extensions=org.esigate.servlet.ServletExtension,org.esigate.extension.Esi
crosscontext.context=/myWebapp
crosscontext.mappings=/crosscontext/*

Technically, local and cross-context call rely on the following methods:

Note: cross-context has to be enabled in the context configuration. For example on Tomcat context xml file:

<Context docBase="esigate" path="" crossContext="true"/>
			

Note: local and crosscontext providers do not support background revalidation.

Variables resolver

You can define variables in classpath esigate-vars.properties

variable_name=variable_value
someUrl=/cms/article123

The syntax for using a variable is $(variable_name) and is fixed by the standard ESI.

Mapping requests

When a request is received, the ProxyFilter first has to find the provider application to which to forward this request.

1. remove the context path
2. try to match to one of the different mappings declared in the configuration. If several mappings are matching, the longest will be selected in priority
3. if stripMappingPath="true" removes the path part of the mapping

Ex: if the application is deployed under path "/myapplication" and the mappings for a provider application is "/mypath/*.jsp" then we receive a request "http://server/myapplication/mypath/other/test.jsp" EsiGate will map the request to the provider and transform the URL to a relative URL "/mypath/other/test.jsp"

Includes

The situation is more simple for includes as the provider is explicitely declared. Ex: <esi:include src="$(PROVIDER{myprovider})/test.jsp"/> will be mapped to "myprovider" and URL transformed to "/test/jsp"

Routing requests to the provider applications

Now EsiGate has to build the URL to send the request to. First we have to get the base URL of the server and append the relative URL found in the previous step. Ex: if remoteUrlBase=http://localhost:8080/ the previous example's request "http://server/myapplication/mypath/other/test.jsp" transformed to "/mypath/other/test.jsp" will be rewritten to "http://localhost:8080/mypath/other/test.jsp".

If preserveHost=true, the request will still be sent to localhost:8080 but the host header will contain "server" and the URL will become "http://server/mypath/other/test.jsp".

Note: If load-balancing, the URLs are rewritten according to the target host that is selected according to the balancing algorithm.

Rewriting URLs in responses

All the URLs contained in the responses are automatically rewritten. This includes:

• URLs contained in pages (<a href="... scripts, images, javascripts, links)
• Redirections (location header)
• Cookies path and domain
• Other HTTP headers (Refresh, Content-location, Referer)

The rewriting takes into account the original URL in order to do the rewriting in the other way. Ex: a link <a href="http://localhost:8080/mypath/result.jsp"> will be rewritten back to <a href="http://server/myapplication/mypath/result.jsp">.

Depending on parameter fixMode, all URL are rewritten as absolute URLs ex: "http://server/myapplication/mypath/result.jsp" or relative to the server root ex: "/myapplication/mypath/result.jsp". In both cases, the URL is normalized (expressions containing dots are removed) ex: "../test.jsp" will be replaced by "http://server/myapplication/test.jsp").

visibleUrlBase parameter adds a possibility to force the base URL to rewrite with instead of the one from the incoming request

Edge Side Include

ESIGate fully implements ESI 1.0 Language Specification 1.0 and adds also a few extra (but useful) features. Here is the reference list of all supported tags, attributes and variable expressions.

<esi:include>

This tag specifies to include some part of another web page. Here is basic example:

<esi:include src="$(PROVIDER{cms})/news" fragment="news_1"/>

This tag has several other attributes that enable to have a precise control on what you want to retrieve from the page, transform, cache, handle errors... See the reference table bellow for details. src should start with $(PROVIDER, any character before will be ignored

<esi:replace>

This tag can be used only nested inside an include tag and is used to specifies things to replace inside the included fragment.

<esi:include src="...">
    <esi:replace fragment="my_fragment"> Replacement text</esi:replace>
</esi:include>

This tag has several other attributes that enable to have a precise control on what you want to retrieve from the page, transform, cache, handle errors... See the reference table bellow for details.

<esi:fragment>

Delimits a fragment inside a page. This fragment could be fetched or retrieved by another page.

<esi:fragment name="my_fragment">
   Content of the fragment
</esi:fragment>

<esi:try> <esi:attempt> <esi:except>

Enables to handle http errors like 404 or 500.

<esi:try>
   <esi:attempt> ... </esi:attempt>
   <esi:except code="500"> ... </esi:except>
</esi:try>

<esi:choose> <esi:when> <esi:otherwise>

Defines conditional structures.

<esi:choose>
   <esi:when test="..."> ... </esi:when>
   <esi:when test="..."> ... </esi:when>
   <esi:otherwise> ... </esi:otherwise>
</esi:choose>
			

<esi:inline>

Defines fragments that will be stored separately in the cache in order to be reused later. See ESI 1.0 Language Specification 1.0 for details.

<esi:comment>

A comment that appears in the source code of the page but will be removed after ESI processing.

<esi:comment text="This comment will not be sent to the client" />

<esi:remove>

Almost like comment tag. The html nested inside remove tag will be visible inside the page before processing but will be removed by the processing. This tag is very useful for example when you are using a page as a template and you want to see it with sample contents when it has not been ESI-processed.

<esi:remove>
   <strong>This is a sample text that will be removed</strong>
</esi:remove>
			

<!--esi -->

Exactly the opposite of remove tag. Before ESI processing the content of the tag will be seen by the browser as an html comment but after inclusion the tag itself will be removed and the content will become visible.

<!--esi
   <strong>This page has been processed by an ESI processor!</strong>
-->
			

<esi:vars>

Some variable expressions can be used inside esi tag attribute values. With this tag you can use expressions anywhere in your page, you just have to put a vars tag around the part of the page that may contain expressions.

<esi:vars>
   The user-agent of your browser is: $(HTTP_USER_AGENT)
</esi:vars>
			

Tag reference

(If you find a mistake in this table, feel free to contact us.)

Please note that this table lists ESI 1.0 and Esigate additional tags only. Other implementations may have other additional tags (Akamai Edgesuite has).

Variable reference

Variable types

Variables

Functions

For the complete list of variable and expressions that can be used, see §4 in the ESI 1.0 Language Specification 1.0 Note: the expression "PROVIDER" is a specific ESIGate expression useful to externalize the base Url of provider applications inside the configuration file. All the other expressions supported by ESIGate are the ones defined inside the specification.

Cache configuration

ESIGate uses the HttpClient Cache Apache HttpClient since version 4.1. This cache is compliant with HTTP/1.1 specification The cache can use several alternatives as storage, in addition to its native backend where cache entries are kept in memory there are 2 other implementations with EhCache and MemCached All the parameters for the cache including the choice of the backend are set in the main configuration file described in the configuration section.

Content expiration, heuristic expiration, forced expiration

By default the cache uses Cache-control and Expires headers to check if a response is cacheable and how long.

If the headers contains only a Last-modified header with no other header to define when the response expires, the cache will keep the response a for a duration that will be a fraction of its age, by default 10%. This mechanism is known as "Heuristic expiration" and is well described in HTTP 1.1 specification.

In certain cases you may want to force the time-to-live of all the responses coming from a server regardless of the http headers presents in the responses. This can be done using the parameter "ttl" in the configuration.

Variants, E-tag and Vary headers

The cache will store several response variants depending on E-tag and Vary headers. This strategy can be very effective when some contents depend on the user profile or language.

Cache revalidation

When a server response contains E-tag and/or Last-modified header, the cache will use conditional requests using If-none-match and/or If-modified-since request headers for subsequent request to revalidate the cache entries without having to reload them each time.

Background revalidation

The cache also implements the HTTP Cache-Control Extensions for Stale Content specification. This means that the cache receives a request and already has a response to be faster and then revalidate it in order to have an up-to-date response next time. It can also use the stale cache entry when the target server is not responding.

According to the specification, this behavior depends only on the headers Stale-while-revalidate and Stale-if-error defined by the target server, but in ESIGate you can also set these parameters by default for all cacheable responses.

Request headers

Some request headers are forwarded to the target server, some are ignored and some are transformed. Here is the list of supported Request HTTP headers. Any other header would be ignored.

Response headers

Some of the response headers sent by the target servers are forwarded to the browser, some are ignored, some are transformed and some are used for Cache management. Any header not in the following list would be ignored.

Cookie policy and cookie specifications

ESIGate is designed to behave exactly like any web browser. It should accept any cookie coming from provider applications if a standard browser accepts them.

Cookies are checked against cookie specifications. Note that "path" and "domain" attributes are checked against the target server name and path. Target Host name means the name specified in the "host" header of the request sent to the server. In other words, when preserveHost option is set to true, domain must match the original server name used by the browser ; when preserveHost is set to false, cookie domain must match the server name defined in the baseURL parameter in the configuration.

Cookie storing

By default, cookies sent by the browser are forwarded to target applications and cookies sent back by the server are forwarded to the browser. It is also possible to store them in the session on EsiGate side: they are kept server side into a the user context. Of course, every user has a separate user context.

Every driver instance has its own UserContext. Contexts are insulated. This means that cookies sent to one provider are not shared with other sites, even domain cookie. Just like if we were using separate browsers for each provider.

As a result, the only cookie viewed from the browser is the "jsessionid" corresponding to the user session used by ESIGate to store the user context.

Cookie forwarding, cookie storing, cookie discarding

It is possible to configure ESIGate to store all cookies or specific cookies to the session and also discard all or specific cookies. This is done by using the properties "storeCookiesInSession" and "discardCookies" in the configuration file. Values for these properties should be a comma separated list of cookie names or the single value "*".

Example 1: store cookies named "cookie1" and "cookie2", discard cookie name "cookie3", all other cookies will be forwarded (default behavior).

storeCookiesInSession=cookie1,cookie2
discardCookies=cookie3
					

Example 2: store cookies named "cookie1" and "cookie2", discard all other cookies.

storeCookiesInSession=cookie1,cookie2
discardCookies=*
					

Note: if the name of a cookie is present in storeCookiesInSession, it takes priority over "*" in discardCookies

Note: if the name of a cookie is present in discardCookies, it takes priority over "*" in storeCookiesInSession

Note: using value "*" for both storeCookiesInSession and discardCookies is not allowed.

Note: forwarded cookies are not kept server side, they are forwarded both ways, server to browser when the header "set-cookie" is received, browser to server on every request.

Cookie rewriting

For forwarded cookie, the domain and path of the cookie and secure or not cannot be kept as-is because a cookie that would not match its originating domain should be rejected by the browser.

Domain:

• if domain is the server name, it is converted to esigate server name used in the request
• if domain is more general domain, esigate tries to convert it to a domain matching the request domain

Path:

• the path is rewritten to the biggest matching path in the url

Secure:

• cookie is set secure only if server sent it as secure and scheme is https, in all other cases, cookie est set not secure when sent to browser

Authentication

User authentication consists in two different things :

1. authenticating user requests
2. forwarding user information to the providers

Authentication is managed by extensions in ESIGate 4.x. In older versions, authentication was handled by implementations of the AuthenticationHandler interface.

To ease update from a previous ESIGate version or simply for inspiration, an adapter between AuthenticationHandler and Extension is provided : GenericAuthenticationHandler

Extensions are declared for each provider. This means that ESIGate can get content from applications using different authentication systems.

Default authentication handler

The default AuthenticationHandler is RemoteUserAuthenticationHandler implementation. This implementation tries to retrieve the user by calling the method request.getRemoteUser() from the container. If this method returns a user name, the name is forwarded to the provider in the "X_REMOTE_USER" HTTP header.

CAS authentication

There is also an AuthenticationHandler for CAS Single Sign On. See CAS for more information.

Custom authentication

Any other authentication method can be implementing by writing a class that implements Extension or extends GenericAuthenticationHandler.

Http errors

Any HTTP status code different from the following codes is considered as an error :

• 200 OK
• 301 Moved permanently
• 302 Found
• 304 Not modified

Network errors and timeout

There are several kind of network problems for example :

• DNS errors (host name cannot be resolved)
• Connection refused (can be a wrong port number or a firewall problem)
• Broken pipe (host closed connection unexpectedly)
• ...

In addition, for performance issues, ESIGate cannot wait indefinitely for the target server to answer. That is the reason for the "timeout" configuration parameter. This parameter is used in 2 cases :

• Connection timeout (trying to connect to the server but the server does not answer)
• Socket timeout (the connection has been established, the server may have started sending the response but no packet has been received for too much time)

All these problems are handled like Http errors with the following codes :

Handling errors with ESIGate

In case of an error, there are several possible ways to handle the problem :

• Display the error page from the target server in case of an HTTP error
• Display an error page in case of other errors (application server default error page with stacktrace or custom error page)
• Display a simple error message (status code + status text)
• Display a generic error message or just nothing

Depending on where we are, we cannot do anything : for example, while rendering a block inside a page, if a problem occurs but the response is already commited, we can only display a simplified message or generic message because rendering the complete error page may result in a page totally broken.

Cache and errors

According to HTTP specifications, a HTTP compliant cache system should never cache pages with status code other than 200 OK. In ESIGate, it was decided to do exactly the contrary :

This behaviour is designed to avoid performance issues, when there is an error on a resource, there is no reason to continue asking for the same resource again and again. ESIGate will keep the response in cache and try a new request only when the cache entry has expired.

Extensions

Extensions are simply classes which implement the Extension interface .

They are loaded at startup by ESIGate according to the " extensions " configuration directive . Each provider can use a different set of extensions.

In the init() method, an extension will usually read configuration and register to events.

Events

Events are hooks on ESIGate's request processing, allowing to safely insert custom code at every step.

Using this extensions can :

• handle security or login in remote applications by doing more http calls to correctly provide credentials when access is refused.
• alter html content or headers before a request result is used or even put into the cache.
• change cache ttl based on urls .
• rewrite links in headers or in the html body.
• update or remove cookies.
• send additional headers to client or to backends.
• cancel requests.
• do custom logging.
• ...and much more

Extensions can register an event listener to events using the Event Manager : Driver#getEventManager().register()

The following events are supported :

• Proxy events : ESIGate process an incoming request (ESIGate configured as a proxy).
  • EVENT_PROXY_PRE : before processing an incoming request.
  • EVENT_PROXY_POST : after processing an incoming request.
• Fragment events : A fragment is required for inclusion (esi:include). ESIGate will try to use its cache or fallback to an http call to the remote backend.
  • EVENT_FRAGMENT_PRE : before retrieving a fragment.
  • EVENT_FRAGMENT_POST : after retrieving a fragment.
• Fetch events : An HTTP call is made to a remote backend.
  • EVENT_FETCH_PRE : before creating the HTTP call.
  • EVENT_FETCH_POST : after we receive the response.
• Render events : Renderers are applied to the current page. This event can be used to inject additional renderers.
  • EVENT_RENDER_PRE : before applying renderers
  • EVENT_RENDER_POST : after applying renderers
• Read entity event : response is read using the charset declared by HTTP headers.
  • EVENT_READ_ENTITY : after reading response using the default encoding

Available extensions

ESIGate comes with several existing extensions :

X-Powered-By: Esigate

<esi:include src="$(PROVIDER{cms})/news" fragment="news_1"/>

<!--$includeblock$aggregated2$block.html$myblock$-->

kill -1 <esigatepid>

metricPeriod=60

 Metric.aggregated1.org.esigate.fetch-post, count=13, mean_rate=0.28, m1=0.86, m5=1.41, m15=1.53, rate_unit=events/second
 Metric.aggregated1.org.esigate.fetch-post.error.404, count=32, mean_rate=0.60, m1=3.02, m5=5.50, m15=6.08, rate_unit=events/second
 Metric.aggregated1.org.esigate.proxy-post, count=31, mean_rate=0.68, m1=1.04, m5=1.46, m15=1.55, rate_unit=events/second
 Metric.aggregated1.org.esigate.proxy-post.error.404, count=32, mean_rate=0.60, m1=3.02, m5=5.50, m15=6.08, rate_unit=events/second
 Metric.aggregated2.org.esigate.fetch-post, count=59, mean_rate=1.37, m1=6.17, m5=9.80, m15=10.58, rate_unit=events/second
                            

								dns.remoteUrlBase=http://myPrivateVirtualHost:8080/
								dns.remoteIP=172.17.42.1
							

ESIGate users can add custom extensions packaged in a jar or simply compiled classes depending on the way ESIGate is used (standalone server or library).

FragmentLogging and FetchLogging extensions

2 extensions can be used to debug all the requests/responses (with request/response headers, cookies and status code) to the logs:

• org.esigate.extension.FragmentLogging
• org.esigate.extension.FetchLogging

The difference between these 2 extension is that FetchLogging logs only the requests actually sent to the target server when FragmentLogging also logs the responses served from the cache and gives some details about the cache status.

If you did not set "extensions" parameter in esigate.properties file, these extensions are already active. If you have set "extensions" parameter, you will have to explicitly declare them. Then you just need to set the corresponding category to INFO. For example if you are using log4j:

log4j.rootLogger=WARN, A

log4j.appender.A.threshold=TRACE
log4j.appender.A=org.apache.log4j.ConsoleAppender
log4j.appender.A.layout=org.apache.log4j.PatternLayout
log4j.appender.A.layout.ConversionPattern=%d{dd-MM HH:mm:ss} %-8r [%t] %-5p %c %x - %m%n

#log4j.category.org.esigate.extension.FetchLogging=INFO
log4j.category.org.esigate.extension.FragmentLogging=INFO

The logs are compact (every request generates only 1 line in the logs) and the performance overhead is small so these extensions can be used safely in production if needed.

HttpClient wire logging

If you need even more details, you can use HttpClient wire logging. This way you can get all the information you need but log files are going to be very verbose so it is not recommended to use it in production. Also because every request generates a lot of lines in the log, it becomes very hard to analyze if the application is used concurrently by a lot of users.

Taglib

The JSP taglib, JSF and Wicket components have been removed since version 5.0 and replaced by a servlet filter that will benefit of the full ESI syntax and will be compatible with all presentation frameworks (JSP, JSF, Wicket...).

If you plan to migrate an application developped using the taglib please refer to the upgrade documentation.

Html comments-based syntax

In addition to ESI language, ESIGate also supports a syntax based on html comments though the functionalities are more limited

See the html comments-based syntax