Skip to content
This repository

Caching

The caching plugin for OpenRasta lets you implement HTTP caching easily on your existing code-base.

The first part adds support for Last-Modified and ETags mapping for resources, automatic support for Etags/LastModified conditional requests and generation of caching instructions.

The caching module also allows you to cache entity responses using a cache-provider, to bypass your code entirely and make it more efficient, in an HTTP-friendly way.

Install

In an OpenRasta project, simply add the openrasta-caching package.

o add-wrap openrasta-caching

Once done, you need to enable the caching module in your configuration.

ResourceSpace.Uses.Caching();

Status

The current release of the caching module is version 0.2.0.

Controlling caching behavior

By default, the caching plugin will not generate any caching instruction for resources. In HTTP, if you do not provide caching instructions, the response can be cached unless it's authenticated.

To generate custom caching instructions, the methods on your handlers can be attributed to control each of the caches more specifically.

The browser cache

To generate a caching instruction that will let the browser cache a response (and as such, prevent shared caches / proxies from caching), you can add the CacheBrowser attribute to your handler method.

[CacheBrowser]
public object Get() { /*...*/ }

This will generate a response with the following HTTP header.

Cache-Control: private

The proxy cache

If you annotate the method with CacheProxy, you imply that proxies can cache the result (and as such, private caches will also be able to cache).

You can attribute the code as such.

[CacheProxy]
public object Get() { /*...*/ }

This will not generate any cache instruction as it is implied.

Public caching

To enable the response to be cached even when authentication is enabled or when HTTP defines that the entry ought to not get cached, the level of caching needs to be changed for proxies.

[CacheProxy(Cache=ProxyCacheLevel.Public)]
public object Get() { /*...*/ }

When both present, the response will become public.

Cache-Control: public

Explicit expiration

To set expiration times for a resource representation, you can annotate the attributes with the MaxAge property.

Expiration can be enabled for all proxies.

[CacheProxy(MaxAge="00:01:00")]

This will instruct both proxies and browser caches to cache for 60 seconds, and will translate to a max-age instruction.

Cache-Control: max-age=60

Expiration can be set for browsers only.

[CacheBrowser(MaxAge="00:01:00")]

Which will generate the follwoing HTTP header.

Cache-Control: private, max-age=60

Finally, you can specify different expiration times for browsers and proxies.

 [CacheBrowser(MaxAge="01:00:00"), CacheProxy(MaxAge="00:10:00")]

This will generate the following header.

 Cache-Control: max-age=3600, s-maxage=600

Resource mapping

The caching module also allows users to map certain properties of resource objects to Last-Modified, Etags and expiry.

Conditional requests

Once resource mappings have been added, conditional requests can be processed automatically.

As of version 0.2, conditionals are only supported for GET requests. Support for other HTTP methods will be added later based on feedback.

## ETag generation

The caching module takes care of generating strong etags correctly, something that many people do wrong.

Sanitization

While the caching module can accept and process any valid ETag, when you generate them from the server side, only safe characters will be allowed, with any unsafe ones being replaced with the underscore character (Unicode U+005F _) .

Character Range Safe ETag Allowed in HTTP
\x21 (!) Yes Yes
\x23 to \x7E (# to ~) Yes Yes
\x80 to \xFF Yes No
Something went wrong with that request. Please try again.