iris: Index | Files | Directories

package cache

import ""


Package Files

browser.go cache.go


const (
    // PragmaHeaderKey is the header key of "Pragma".
    PragmaHeaderKey = "Pragma"
    // PragmaNoCacheHeaderValue is the header value of "Pragma": "no-cache".
    PragmaNoCacheHeaderValue = "no-cache"
    // ExpiresHeaderKey is the header key of "Expires".
    ExpiresHeaderKey = "Expires"
    // ExpiresNeverHeaderValue is the header value of "ExpiresHeaderKey": "0".
    ExpiresNeverHeaderValue = "0"


var Cache304 = func(expiresEvery time.Duration) context.Handler {
    return func(ctx *context.Context) {
        now := time.Now()
        if modified, err := ctx.CheckIfModifiedSince(now.Add(-expiresEvery)); !modified && err == nil {


Cache304 sends a `StatusNotModified` (304) whenever the "If-Modified-Since" request header (time) is before the time.Now() + expiresEvery (always compared to their UTC values). Use this `cache#Cache304` instead of the "" or iris.Cache for better performance. Clients that are compatible with the http RCF (all browsers are and tools like postman) will handle the caching. The only disadvantage of using that instead of server-side caching is that this method will send a 304 status code instead of 200, So, if you use it side by side with other micro services you have to check for that status code as well for a valid response.

Developers are free to extend this method's behavior by watching system directories changes manually and use of the `ctx.WriteWithExpiration` with a "modtime" based on the file modified date, can be used on Party's that contains a static handler, i.e `HandleDir`.

var CacheControlHeaderValue = "private, no-cache, max-age=0, must-revalidate, no-store, proxy-revalidate, s-maxage=0"

CacheControlHeaderValue is the header value of the "Cache-Control": "private, no-cache, max-age=0, must-revalidate, no-store, proxy-revalidate, s-maxage=0".

It can be overridden.

var ETag = func(ctx *context.Context) {
    key := ctx.Request().URL.Path
    ctx.Header(context.ETagHeaderKey, key)
    if match := ctx.GetHeader(ifNoneMatchHeaderKey); match == key {

ETag is another browser & server cache request-response feature. It can be used side by side with the `StaticCache`, usually `StaticCache` middleware should go first. This should be used on routes that serves static files only. The key of the `ETag` is the `ctx.Request().URL.Path`, invalidation of the not modified cache method can be made by other request handler as well.

In typical usage, when a URL is retrieved, the web server will return the resource's current representation along with its corresponding ETag value, which is placed in an HTTP response header "ETag" field:

ETag: "/mypath"

The client may then decide to cache the representation, along with its ETag. Later, if the client wants to retrieve the same URL resource again, it will first determine whether the local cached version of the URL has expired (through the Cache-Control (`StaticCache` method) and the Expire headers). If the URL has not expired, it will retrieve the local cached resource. If it determined that the URL has expired (is stale), then the client will contact the server and send its previously saved copy of the ETag along with the request in a "If-None-Match" field.

Usage with combination of `StaticCache`: assets := app.Party("/assets", cache.StaticCache(24 * time.Hour), ETag) assets.HandleDir("/", iris.Dir("./assets"))

Similar to `Cache304` but it doesn't depends on any "modified date", it uses just the ETag and If-None-Match headers.

Read more at: and

var NoCache = func(ctx *context.Context) {
    ctx.Header(context.CacheControlHeaderKey, CacheControlHeaderValue)
    ctx.Header(PragmaHeaderKey, PragmaNoCacheHeaderValue)
    ctx.Header(ExpiresHeaderKey, ExpiresNeverHeaderValue)



NoCache is a middleware which overrides the Cache-Control, Pragma and Expires headers in order to disable the cache during the browser's back and forward feature.

A good use of this middleware is on HTML routes; to refresh the page even on "back" and "forward" browser's arrow buttons.

See `cache#StaticCache` for the opposite behavior.

var StaticCache = func(cacheDur time.Duration) context.Handler {
    if int64(cacheDur) <= 0 {
        return NoCache

    cacheControlHeaderValue := "public, max-age=" + strconv.Itoa(int(cacheDur.Seconds()))
    return func(ctx *context.Context) {
        cacheUntil := time.Now().Add(cacheDur).Format(ctx.Application().ConfigurationReadOnly().GetTimeFormat())
        ctx.Header(ExpiresHeaderKey, cacheUntil)
        ctx.Header(context.CacheControlHeaderKey, cacheControlHeaderValue)


StaticCache middleware for caching static files by sending the "Cache-Control" and "Expires" headers to the client. It accepts a single input parameter, the "cacheDur", a time.Duration that it's used to calculate the expiration.

If "cacheDur" <=0 then it returns the `NoCache` middleware instaed to disable the caching between browser's "back" and "forward" actions.

Usage: `app.Use(cache.StaticCache(24 * time.Hour))` or `app.Use(cache.Staticcache(-1))`. A middleware, which is a simple Handler can be called inside another handler as well, example: cacheMiddleware := cache.StaticCache(...) func(ctx iris.Context){



func Cache Uses

func Cache(expiration time.Duration) *client.Handler

Cache accepts the cache expiration duration. If the "expiration" input argument is invalid, <=2 seconds, then expiration is taken by the "cache-control's maxage" header. Returns a Handler structure which you can use to customize cache further.

All types of response can be cached, templates, json, text, anything.

Use it for server-side caching, see the `iris#Cache304` for an alternative approach that may be more suited to your needs.

You can add validators with this function.

func Handler Uses

func Handler(expiration time.Duration) context.Handler

Handler like `Cache` but returns an Iris Handler to be used as a middleware. For more options use the `Cache`.

Examples can be found at:

func WithKey Uses

func WithKey(key string) context.Handler

WithKey sets a custom entry key for cached pages. Should be prepended to the cache handler.

Usage: app.Get("/", cache.WithKey("custom-key"), cache.Handler(time.Minute), mainHandler)


rulesetPackage ruleset provides the basics rules which are being extended by rules.

Package cache imports 4 packages (graph) and is imported by 28 packages. Updated 2020-09-10. Refresh now. Tools for package owners.