Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Document the scoped HTTP cache purge body and http_cache.warm_after_flush (api-components-bundle #484)

Closed Beginner friendly
  • Is something wrong?
#256 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
yaml
Domain
documentation

Research direction

Start in content/4.api/ and find the HTTP cache purge and bundle configuration pages. Document the scoped purge body, validation errors and status codes, then add the http_cache.warm_after_flush settings, Messenger routing, and behavior described in the issue. Done when the API docs explain both features, including that only a request with no body flushes the whole cache and that full flushes make pages cold.

Written by the indexing model from the issue text.

Description

From components-web-app/api-components-bundle#484, implemented in components-web-app/api-components-bundle#487.

Please document the following in the API docs (content/4.api/):

Scoped purge: POST /_/http_cache/purge

  • ROLE_ADMIN. It is the HTTP version of silverback:api-components:purge-http-cache --path/--tag.
  • A body {"paths": ["/about-us"], "tags": ["cwa-html"]} (either key or both) purges only those tags. Each path becomes the tag a write to the route at that path purges (the /_api import prefix is included), and the page is not looked up. It never flushes. Success is 204 with no body.
  • Only a request with no body at all flushes the whole cache. {}, null, [], malformed JSON, unknown keys, an empty or non-list paths/tags, a path not starting with /, or a tag that is empty or has whitespace or a comma are all a 422, with propertyPath paths, tags, paths[i] or tags[i].
  • 501 when no purger is configured (scoped) or the purger cannot flush (full); 502 when the purge fails.
  • Present the full flush as a last resort: it makes every page render cold at once. A write already purges its own tags.

http_cache.warm_after_flush (off by default)

silverback_api_components:
  http_cache:
    warm_after_flush:
      enabled: true
      base_url: 'http://localhost'   # the HTTP cache in front of the API, as warm-http-cache --base-url
      max_time: 60                   # seconds, for each encoding
      concurrency: 2
      timeout: 30
      limit: ~                       # most routes, shortest first; null = all until max_time
  • After a successful full flush (the endpoint with no body, purge-http-cache with no options, every fixture load's flush), the bundle dispatches two Silverback\ApiComponentsBundle\Message\WarmHttpCacheMessages on messenger.default_bus: one with Accept-Encoding: gzip (SSR) and one with br (browsers and CDN). Each runs the warm-http-cache logic over the public routes, shortest first, until max_time.
  • Route the message to an async transport and run a worker. Without async routing, the warm runs inside the request or command that flushed and holds a php worker. With no Messenger bus at all, nothing is warmed and a warning is logged.
  • A failed dispatch is logged at error and never fails the flush. The setting changes no response.
framework:
  messenger:
    routing:
      Silverback\ApiComponentsBundle\Message\WarmHttpCacheMessage: async
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
1h 20m
Merged PRs (30d)
1

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from components-web-app/docs

All issues in components-web-app/docs

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.