About

Mongrel-ESI is an ESI Server built as a Mongrel::Handler. It uses ragel to implement a native ESI Parser and the ruby language to make it easy to run and install.

ESI stands for Edge Side Include. Edge Side meaning as near as possible to your customers. Include because it's a set of tags you include in your pages.

Based on Mongrel, it is a light weight easy to install cache server that handles a subset of the ESI spec. It's parser is written using ragel, so it's fast and portable.

Support

Please feel free to ask questions or submit patches to the group

Install

svn checkout http://mongrel-esi.googlecode.com/svn/trunk/ mongrel-esi

or

gem install mongrel_esi

Configuration Overview

As of version 0.4 configuration is handled very similar to mongrel. You can pass a -S option to have a special ruby script loaded that defines your own custom routing rules.

Here's a simple example:

ESI::Config.define(listeners) do|config|

  # define the caching rules globally for all routes, defaults to ruby
  config.cache do|c|
    #c.memcached do|mc|
    #  mc.servers = ['localhost:11211']
    #  mc.debug = false
    #  mc.namespace = 'mesi'
    #  mc.readonly = false
    #end
    c.ttl = 600
  end

  # define rules for when to enable esi processing globally for all routes
  config.esi do|c|
    c.allowed_content_types = ['text/plain', 'text/html']
    #c.enable_for_surrogate_only = true # default is false
  end

  # define request path routing rules
  config.routes do|s|
    s.match( /content/ ) do|r|
      r.servers = ['127.0.0.1:4000']
    end
    s.default do|r|
      r.servers = ['127.0.0.1:3000']
    end
  end

end

Supported ESI Features

• esi:include
• src: source of fragment
• timeout: duration to wait for response
• alt: if primary src fails, try this url
• onerror: if src and alt fail, raise an exception unless this value is 'continue'

  <esi:include src="/user/1"/>

• esi:try

• esi:attempt

• esi:except

• esi:invalidate

Only basic invalidation is supported when using memcached

<esi:invalidate output="no">
  <?xml version="1.0"?>
  <!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
  <INVALIDATION VERSION="WCS-1.1">
    <OBJECT>
      <BASICSELECTOR URI="/fragment/url/to/expire?params=all"/>
      <ACTION REMOVALTTL="0"/>
      <INFO VALUE="invalidating fragment test 1"/>
    </OBJECT>
  </INVALIDATION>
</esi:invalidate>

• HTTP_COOKIE variable

(e.g. $(HTTP_COOKIE{name}) will be replaced with the value of the cookie, name)

From esi-lang

+ Inclusion - ESI can compose pages by assembling included content, which is fetched from the network. This allows each such fragment to have its own metadata (e.g., cacheability and handling information) seperately associated.

- Variable support - ESI 1.0 supports the use of variables based on HTTP request attributes in a manner reminiscent of the Common Gateway Interface. These variables can be used by ESI statements or written directly into the processed markup.

- Conditional processing - ESI allows conditional logic with Boolean comparisons to be used to influence how a template is processed.

+ Exception and error handling - ESI provides for specification of alternate and default resources in a number of situations.

Surrogate-Control Header. Using the Surrogate-Control response header you can enable or disable ESI processing. Also, you can tell mongrel-esi how long to cache the response body by setting Surrogate-Control: max-age=50, where 50 is measured in seconds.

Documentation

• RDoc
• Coverage Report

Informative

• Rdocs
• ESI Lang
• ESI Arch
• HTTP Reading

Setting up a Rails Project

[ESI_and_Rails]

Blog

I post about progress occassionally on my blog idle-hacking