# SRE-Filter and SSI-Caching

To improve performance, SRE-Filter will "cache" HTML documents that have server side includes (SSI). This caching is of the document after the SSIs have been performed. In simple cases SRE-Filter can send this cached file, without having to repeat the actual process of SSI lookups, etc. Needless to say, this can greatly improve server performance.

Note: the bottom of this document contains a few SSI-Cache control options.

## Basic Description

First, let us define some terms:

Static SSIs
  Static SSIs are those that do not change over time and client. over time. For example, the <!-- REPLACE WEBMASTER --> should rarely change (it writes the contents of the WEBMASTER SRE-Filter parameter). Another example is <!-- INCLUDE `filename` -->, given that the contents of `filename` does not change.
Dynamic SSIs
  Dynamic SSIs are those that will change over time and client. The simplest example is <!-- REPLACE TIME -->.

  Somewhat less obvious are all the "processing" options, such as:

  - <!-- INTERPRET xxx -->,
  - <!-- #exec cmd=xxx -->
  - <!-- SELECT xx --> Although these three options may yield unchanging values, it's likely that (at least occasionally), the values will depend on the client, time of day, or some other varying factor.
Simple cases
  Simple cases are HTML documents that only contain static SSIs.

It's not hard to see that the caching of simple cases yields immediate benefits. This is especially true as the number and size of static SSIs increases. For example, if you use HEADERS, FOOTERS, and <!-- INCLUDE filename --> SSIs to maintain a standard set of backgrounds and menu bars, the advantages of caching can be substantial.

In non-simple cases, caching is more complex. SRE-Filter's caching procedure solves this problem by using the following strategy:

1. The raw HTML document (the one containing the SSI keyphrases) is read in.
2. Static server side includes are performed.
3. Dynamic server side includes are noted, with placeholders inserted.
4. This partially processed file is saved in the cache.
5. When a request for the raw HTML document is recieved, the TRIGGERS and DURATION are checked. If either of these are out of date, the cache entry is reset.
6. Assumine step 5 is not a problem, the partially processed file is read, and the dynamic SSIs (from step 3) are resolved.
7. Since SSIs are recursive, this might entail another round of processing (say, of REPLACE keyphrases in an INCLUDEd file). This later round is not cached.
8. The final result is returned to the client

While not as quick as simple cases, the pre-processing of static SSIs does improve performance.

## Configuring the SRE-Filter SSI-Cache

Configuration of the SRE-Filter SSI-Cache is accomplished by changing the SSI_CACHE_ON, SSI_CACHE_SIZE, SSI_CACHE_DURATION, and SSI_CACHE_STAMP parameters.
In addition, `<!-- CACHE argument -->` server side include keyphrases can be used to set file-specific caching options.

### The SSI_CACHE parameters

The SSI_CACHE_ON parameter is used to enable/disable the SSI-Cache. It is set in the INITFILT.80 file.

The SSI_CACHE_SIZE, SSI_CACHE_DURATION, and SSI_CACHE_STAMP parameters, which are set in the SREFILTR.80 file, can be customized by ambitious administrators (others may wish to leave them be). Modifications to these parameters will not take effect until you restart GoServe.

SSI_CACHE_ON
  SSI_CACHE_ON is used to enable the SSI-Cache. You can use the SRE-Filter configurator to change it's value.

  > Turning off caching is sometimes useful (or necessary) in highly dynamic environments; say, where INCLUDE files are constantly changing.

SSI_CACHE_SIZE
  SSI_CACHE_SIZE is used to set the size of the server side include cache. You should enter the size in Kilobytes. For example, the default value of `SSI_CACHE_SIZE=5000` corresponds to a cache size of 5M.
SSI_CACHE_DURATION
  SSI_CACHE_DURATION is used to set (in days) the "lifespan" of entries in the server side include cache. Example: `SSI_CACHE_DURATION=0.5` corresponds to a 12 hr. lifespan.

  > Note that you can use the <!-- CACHE DURATION time --> SSI keyphrase to override this default value on a file-by-file basis.

SSI_CACHE_STAMP
  The SSI_CACHE_STAMP dictates which fields to use when determining whether a SSI-cache trigger file has changed. SSI_CACHE_STAMP can take one of the following values:
  - ALL : Use time,date, and size (if any change, the trigger is considered to be out-of-sync)
  - DATE : Just use the date
  - TIME : Just use the time (hr/minute)
  - DATETIME : Use the time and date
  - SIZE : Just use the size
  Example: SSI_CACHE_STAMP='DATETIME'

  > Note that you can use the <!-- CACHE TRIGGER_type stamp --> SSI keyphrase, where stamp is one of the above values, to override this default value on a file-by-file basis.

For further discussion of these parameters, please see INITFILT.DOC.

### The CACHE keyword

To set ssi-caching options on a document specfici basis, you can use the <!-- CACHE option --> SSI keyphrase. The following lists the currently valid options:

<!-- cache no --> or <!-- cache off -->
  Do not cache this document
<!-- cache asis -->
  Use a cached version "as is" -- the first-round of dynamic SSIs will be resolved prior to caching (they will not be updated for future requests). However, SELECT keyphrases and "later rounds" (of keyphrases generated by a dynamic include) will not be converted.

  > When `asis` is specified, INCLUDE files, the REPSTRGS_FILE, and INITFILT.80 will not be included in the trigger list.

  <!-- cache asis --> should be used with care !
<!-- cache notrigger -->
  Do not check the trigger files; but do check the owm file. In particular, the various INCLUDEd files, and the SRE-Filter parameter files, will not be checked (nor will any explicitly mentioned trigger files be checked). One can think of `notrigger` as a subset of asis.
<!-- cache duration `nnn` --> or <!-- cache days `nnn` -->
  Set the lifespan for this file's cache entry. After `nnn` (possibly fractional) days, the cached entry will be removed. Note that if this is not specified, the SSI_CACHE_DURATION parameter is used.
<!-- cache hours `hhh` -->
  Same as <!-- cache duration-->, except `hhh` is interpreted as hours (not as days)
<!-- cache trigger file1 file2 .. -->
  Check the file-stamps for these fully qualified files. If any of them have changed (since the time the cached file was created), then do not use the cached file (the entry will be recreated). Notes:
  - The own file name is always implicitly included in the trigger list (regardless of `asis` or `duration` settings).
  - Depending on which static SSIs were used, and assuming that a `CACHE ASIS` keyphrase is not used:
  - SRE-Filter's parameter files (such as the REPSTRGS_FILE and INITFILT.80) may be included in the trigger list.
  - The list of `INCLUDE`d files may be included in the trigger list.``
<!-- cache trigger_type stamp -->
  Selects which field(s) of the trigger file-stamps to check.

  `stamp` can take one of the following values: DATE TIME DATETIME SIZE ALL. The above description of the SSI_CACHE_STAMP describes these values.

  Note that you can only use one of these five stamps (combinations are ignored). Furthermore, by default the SSI_CACHE_STAMP parameter is used.

## Hints, Cautions, and other miscellaneous Notes

- Since the SSI-cache will cache all files that might have server side includes, we recommend use of the SSI_SHTML_ONLY option. In particular, with SSI_SHTML_ONLY in place (and a proper naming convention used), one can take advantage of GoServe's own cache for non-SSI HTML documents.
- If a document only has static SSIs (that is, no TIME, HITS, INTERPRET, or any other SSIs that might depend on time, client identity, or other varying factors); then it is treated as an `asis` document.
- Non-asis documents are partially cached -- the cache file is first processed for dynamic SSIs, and then sent to the client. This yields a more "accurate" document, but it's not as fast as returning `asis` entries.
- If you have more then one set of DELIMiters, or you have turned the DO_SEND_PIECE parameter on, then SSI-caching will not occur. Thus, we recommend that you do not use multiple DELIMiters, nor should you use the send pieces as they become available option.
- Cached files are stored in your TEMPDATA_DIR directory (typically, GOSERVE\TEMP). They have names of _CSH????.80 (or .nnn, if you are using port .nnn).
- Once the size of the cached files exceeds SSI_CACHE_SIZE kilobytes, the oldest entries will be deleted (where oldest is measured in terms of "last request").
- If you use the `asis` or `notrigger` CACHE options, the quickest way to reset the cache entry is by touching the document's file (say, by modifying it's creation time).
- Cache entries are host-specific -- the same file delivered by different hosts will have seperate cache entries.

## Some SSI-Cache Controls

The following links (and forms) can be used to view and control the SSI-Cache. However, you must have SUPERUSER privileges to use these controls.

A very brief status report will be returned to your browser.

- Reset (clear) the SSI-Cache?

- View the status of the SSI-Cache?

- Remove a (host specific) entry from the SSI-Cache.
  Please enter a fully-qualified file name:

- Cleanup the SSI-Cache (remove dead and expired entries)

Hint: To suppress use of the SSI-Cache, you can use SRE-Filter's !FORCE/a_url special directive.