Skip to main content

Rules

The GBox gives you fine-grained per-type or even per-field control over your cache behavior for every single query that is sent through upstream GraphQL server with cache rules.

Declaring rules​

The GBox use Caddyfile syntax to declaring rules via GBOX_CACHING_RULES environment variable.

GBOX_CACHING_RULES: |
    book { # rule name it can be anything.
        types {
          Book
        }
        max_age 30m
        swr 30m
    }

If you're not declaring rules, default value of GBOX_CACHING_RULES below will be used, it will cache all types with public scope (all users will get the same cached data).

GBOX_CACHING_RULES: |
    default {
        max_age 30m
        swr 30m
    }
info

A rule applies to all queries that contain the rule's types or fields. If multiple rules apply to the same query, GBox will use the minimum max_age, the minimum swr, and combine all varies to cache the query result.

Caddy caching rule directives​

types​

The rule will apply its cache configuration to any query that contains the types or fields mentioned in the types directive.

You can target both types and specific fields of types:

types {
  # The rule will apply to any query that contains Book type
  Book

  # The rule will apply to any query that contains Book type with author field (Book.author).
  Book author
}

info

If not set, the rule will apply for all types.

max_age​

The max_age directive configures how long query results that match the rule types should be cached, in seconds.

info

If multiple rules apply to the same query, the minimum max_age will be used for the entire query result.

swr​

The swr stale-while-revalidate directive configures how long stale query results that match the rule types should be served, in seconds, while fresh data is already being fetched in the background.

info

If multiple rules apply to the same query, the minimum swr will be used for the entire query result.

varies​

Which varies to apply to query results that match the rule types. See the documentation of it for more information.

If not set, the rule will apply for all users (all users will get the same cached query results).

info

If multiple rules apply to the same query, all varies of them will be combined to one.