Add support for proxy_cache_background_update

[Copilot]

Adds nginx proxy_cache_background_update support, allowing stale cached responses to be served while an expired item is refreshed in the background.

Changes

• config.yaml: New proxy_cache_background_update boolean option (default: false). Documents that updating must be present in cache_use_stale (already in the default value — backward compatible).
• src/charm.py: Converts config to NGINX_CACHE_BACKGROUND_UPDATE env var ("on"/"off").
• content-cache_rock/nginx_cfg.tmpl: Adds proxy_cache_background_update directive after proxy_cache_revalidate.
• Tests: 3 new unit tests; updated JUJU_ENV_CONFIG and all nginx config fixture files.

Test plan

Unit tests cover env config generation and nginx config rendering for both enabled/disabled states. All 39 tests pass.

Review focus

Per nginx docs, proxy_cache_background_update on requires updating in proxy_cache_use_stale. The default cache_use_stale already includes updating, so no forced coupling was added — users who customise cache_use_stale to omit updating are responsible for the interaction.

What this PR does

Adds a new proxy_cache_background_update charm config option that maps to the nginx directive of the same name, enabling background cache refresh while serving stale content.

Why we need it

Allows operators to enable nginx's background update behaviour for expired cache entries, improving perceived latency by returning stale content immediately while revalidating in the background.

Checklist

• I followed the contributing guide
• I added or updated the documentation (if applicable)
• I updated docs/changelog.md with user-relevant changes
• I added a change artifact for user-relevant changes in docs/release-notes/artifacts. If no change artifact is necessary, I tagged the PR with the label no-release-note.
• I used AI to assist with preparing this PR
• I added or updated tests as needed (unit and integration)
• If integration test modules are used: I updated the workflow configuration
  (e.g., in .github/workflows/integration_tests.yaml, ensure the modules list is correct)
• If this PR involves a Grafana dashboard: I added a screenshot of the dashboard
• If this PR involves Rockcraft: I updated the version

[Copilot]

Pull request overview

Note

Copilot couldn't run its full agentic review because no GitHub Actions runner was available. Make sure your repository has a runner available to run Copilot's review, or add a copilot-setup-steps.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds support for nginx proxy_cache_background_update via a new charm config option, enabling stale responses to be served while expired cache entries refresh in the background.

Changes:

• Added proxy_cache_background_update boolean option to charm config and mapped it to an Nginx directive.
• Extended env-config generation with NGINX_CACHE_BACKGROUND_UPDATE (on/off) and rendered it in the nginx template.
• Updated/added unit tests and nginx config fixtures to cover enabled/disabled rendering.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
config.yaml	Adds operator-facing config option with docs about cache_use_stale interaction.
src/charm.py	Converts new config option into an env var consumed by nginx template rendering.
content-cache_rock/nginx_cfg.tmpl	Emits proxy_cache_background_update directive in generated nginx config.
tests/unit/test_charm.py	Adds unit tests validating env var generation and template output.
tests/files/nginx_config*.txt	Updates and adds fixtures to include the new directive.

Comments suppressed due to low confidence (1)

src/charm.py:1

• When proxy_cache_background_update is enabled but cache_use_stale does not include updating, nginx won’t serve stale content during background refresh (the primary value of enabling this feature). Consider adding a runtime validation: if background update is on and updating is missing from cache_use_stale, either (a) log a clear warning and proceed, or (b) automatically append updating (and document that behavior). This helps operators avoid a silent misconfiguration.

#!/usr/bin/env python3

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.