Always online: serve stale cache when the origin cannot provide a fresh response

The Always Online option serves stale cached content when the origin cannot provide a usable fresh response, and those responses include the X-Cache: Stale header. When none of the selected stale conditions applies, the CDN resumes serving fresh responses.

The option serves stale content for these conditions:

Condition	Meaning
Error	Network or connectivity failure
Updating	Cached object is being refreshed
Timeout	Origin response timed out
Invalid Header	Origin returned an invalid header
403, 404, 429, 500, 502, 503, 504	Origin returned that HTTP status

The CDN can serve only objects that are already present in cache. If some page assets are not already cached when a stale condition occurs, those images, stylesheets, or other files can still fail to load.

Always online

Turn it on for the conditions that should serve stale content.

1. 1

   Open the CDN resource

   In the CDB Technical Web Portal, navigate to CDN and click the CDN resource.

2. 2

   Open Always online

   In the sidebar, click Cache. In the expanded menu, click Always online.

   
3. 3

   Enable Always online

   Enable the Enable always online toggle.

4. 4

   Select stale conditions

   In the Serve stale cached content in case of the following errors field, select the conditions.

5. 5

   Save the resource

   Click Save changes.

When stale is enabled for a selected condition, the CDN serves the cached response and marks it with X-Cache: Stale. When none of the selected stale conditions applies, the CDN resumes serving fresh responses.

The CDN can serve only objects that are already present in cache. If some page assets are not already cached when a stale condition occurs, those images, stylesheets, or other files can still fail to load.

ℹ️

An API token is required.

Export these variables. CDN_RESOURCE_ID is the id from list CDN resources.

export GCORE_API_KEY="{YOUR_API_KEY}"
export CDN_RESOURCE_ID="{YOUR_RESOURCE_ID}"

Stale values

value accepts error, updating, timeout, invalid_header, http_403, http_404, http_429, http_500, http_502, http_503, and http_504. error is a network or connectivity failure, and updating is a cache refresh.

Both enabled and value are required. When enabled is true, value must contain at least one condition; an empty list returns HTTP 400.

The request below enables stale delivery for http_404 and http_500.

import os
from gcore import CDB

client = CDB()

resource = client.cdn.cdn_resources.update(
    int(os.environ["CDN_RESOURCE_ID"]),
    options={
        "stale": {"enabled": True, "value": ["http_404", "http_500"]},
    },
)
print(resource.options.stale.enabled, resource.options.stale.value)

package main

import (
    "context"
    "fmt"
    "os"
    "strconv"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cdn"
)

func main() {
    client := gcore.NewClient()
    ctx := context.Background()
    resourceID, err := strconv.ParseInt(os.Getenv("CDN_RESOURCE_ID"), 10, 64)
    if err != nil {
        panic(err)
    }

    resource, err := client.CDN.CDNResources.Update(ctx, resourceID, cdn.CDNResourceUpdateParams{
        Options: cdn.CDNResourceUpdateParamsOptions{
            Stale: cdn.CDNResourceUpdateParamsOptionsStale{
                Enabled: true,
                Value:   []string{"http_404", "http_500"},
            },
        },
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(resource.Options.Stale.Enabled, resource.Options.Stale.Value)
}

curl -X PATCH "https://api.cdb-staging.cdn.orange.com/cdn/resources/$CDN_RESOURCE_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "stale": {
        "enabled": true,
        "value": ["http_404", "http_500"]
      }
    }
  }'

The API returns HTTP 200:

{
  "id": 12345,
  "options": {
    "stale": {
      "enabled": true,
      "value": ["http_404", "http_500"]
    }
  }
}

Set stale so the CDN serves a cached response when the origin cannot provide a usable fresh response, using the Terraform provider v2. The served response includes X-Cache: Stale. When none of the selected stale conditions applies, the CDN resumes serving fresh responses. The CDN can serve only objects that are already present in cache.

value accepts error (network or connectivity failure), updating (cache refresh), timeout (origin response timed out), invalid_header (origin returned an invalid header), http_403, http_404, http_429, http_500, http_502, http_503, and http_504. enabled and value are both required. When enabled is true, an empty value list returns HTTP 400. Leaving stale out of options leaves the stored option unchanged. Run terraform apply after editing options.

Serve stale content

Set enabled to true. With http_404 and http_500, a 404 or 500 from the origin is served from cache and marked with X-Cache: Stale.

resource "gcore_cdn_origin_group" "example" {
  name = "my-origin-group"

  sources = [
    {
      source  = "example.com"
      enabled = true
    }
  ]
}

resource "gcore_cdn_resource" "example" {
  cname           = "cdn.example.com"
  origin_group    = gcore_cdn_origin_group.example.id
  origin_protocol = "HTTPS"

  options = {
    stale = {
      enabled = true
      value   = ["http_404", "http_500"]
    }
  }
}