The ExpiresByPath and BlockByPath selectors represent the (virtual) location of one or more files, relative to the Web site's home or root directory. The selector can include multiple paths, separated by commas. Paths may contain any combination of alphanumeric characters, underscores, forward slashes ( / ) and dots ( . ), plus wildcards (the * symbol). Paths must begin with either an initial slash (representing the home or root directory) or a wildcard. In the examples, the ExpiresByPath selector picks out all files located in the images directory, or any of its subdirectories, while the BlockByPath selector does the same for the tempimages directory and its subdirectories.

Unlike ExpiresByType selectors, ExpiresByPath selectors are not mutually exclusive. To continue with our example, it would be perfectly legal to have a second ExpiresByPath rule in our rules.cr file with the selector /perm_images/*.gif. Because of this, it is possible for more than one selector to apply to the same file. When this happens, the most specific selector always takes precedence. Thus, for gif files in the perm_images directory, a rule with the selector /perm_images/*.gif would take precedence over one with the selector /perm_images/* because the former selector is more specific (contains more information) than the latter.

Note: BlockByPath selectors always take precedence over all ExpiresByPath selectors, even when the ExpiresByPath selector contains more path information than the BlockByPath selector. Thus, a BlockByPath selector of /tempimages/* would override an ExpiresByPath selector of /tempimages/butnotthisone.jpg.

One way to write an expiration clause is by using one of two special keywords -- never and immediately. Using immediately, as in the example, sets the expiration time to be exactly equivalent to the date of access. (The date of access is simply the date and time when the server delivered the file to the client.) Since the file will be "stale" as soon as it is received, it will not be cached. Using never causes the expiration time to be set for one year from the date of access. The file will be cached, and the cached copy will remain "fresh" for one year.

Note: One year in the future is what the HTTP specification recommends as the maximum expiration time servers should send. It is possible to set longer expiration times than this using CacheRight, but we do not recommend doing so. For the relevant part of the HTTP specification, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21.

A second way to write an expiration clause is to specify an interval of time relative to some starting-point, at the end of which a cached copy will be considered "stale." This is done with a simple phrase consisting of a number and an interval keyword -- year(s), month(s), week(s), day(s) or minute(s), followed by the word after and one of two starting-point keywords -- access or modification. The access keyword means that the specified interval is relative to the date on which the client accessed the file on the server. The modification keyword means that the interval is relative to the last time the file was changed. In the example, a cached copy of an affected file will be considered stale 14 days after the server delivers it to the client.

Note that the practical effect of a relative interval can be very different depending on the starting-point used. If modification had been used in the example instead of access, then the cached file would be considered stale 14 days after its last modification, no matter when the client received it from the server. Depending on how much time had gone by between the file's last modification and the client getting a copy of it from the server, that copy might be considered stale immediately, after 14 days, or anytime in between. The best keyword to use depends on whether it is more useful for a particular file's freshness to be determined from the point of view of the client accessing it, or from the point of view of its creator or editor. Generally speaking , the more frequently files are changed, and the more time-sensitive their content, the more likely you will want to use modification in place of access.

The third way to write an expiration clause is to specify an expiration date. The date must be in GMT format (details can be found online at www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.3). In the example, cached copies of the affected files will be considered fresh until March1st, 2003.

The public and private keywords cause either the "public" or the "private" directive to be added to the cache control headers for a given file or files. You may have noticed that all the examples have one or other of these directives, but never both. There is a good reason for this: The public and private directives are mutually exclusive and one or the other of them must always be appended to every CacheRight rule. The "public" directive simply insures that a response is cachable by both shared (proxy) and nonshared (browser) caches. The "private" directive prevents a response from being cached by shared (proxy) caches, but permits caching by browsers. In the examples, only the last of the three rules (the ExpiresByPath rule) has private rather than public, so only files affected by that rule will be uncachable by shared (proxy) caches.

The no-transform directive is optional. Caches are allowed to transform the objects they cache to make their storage and transmission more efficient. A cache may, for example, recode image files or compress text files. Under certain circumstances, these kinds of transformations can cause problems. Appending no-transform to a rule prevents caches from modifying the files affected by that rule. Since shared (proxy) caches are more likely to use such transformations, no-transform will often be appended to CacheRight rules that have the public keyword, as in the example.