Expose Nginx Cache Management API

Open
  • Is something wrong?
#1,046 2 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
javascript
Domain
api, backend, performance

Research direction

Start by reviewing the existing NJS APIs and how Nginx proxy and FastCGI cache files are managed. Narrow the proposed capabilities to a feasible cache-purge scope, then identify the relevant implementation entry points and validation needed for URL-based clearing. Done means an agreed, implementable API with clear behavior for individual and batch purges.

Written by the indexing model from the issue text.

Description

feature njs

Currently, if you use any sort of proxy or fastcgi cache, the only way to manage that cache is:

  1. Via Nginx Plus
  2. Via 3rd party cache management modules
  3. Via workarounds to tamper with the underlying cache files

Our specific use case forced us into that third solution so if we need to purge cache files from our fastcgi or proxy caches, we have to manually delete those through other mechanisms outside of Nginx. Technically, this works fine but it does confuse Nginx since Nginx obviously doesn't assume that something else is managing cache files on its behalf. The only noticeable consequence of this is that error logs are generally clogged with tons of this sort of error.

2026/04/07 09:00:53 [crit] 3245228#3245228: unlink() "/path/to/cache/4/57/c3ee1ac6eafe854c5f8bff6ee97b7574" failed (2: No such file or directory)
2026/04/07 09:01:10 [crit] 3245228#3245228: unlink() "/path/to/cache/3/ac/645c2cda0008f5643a47423edf5f7ac3" failed (2: No such file or directory)

I suspect that there are other less obvious consequences to this type of cache management as well.

Ideally, it would be nice to have a way to manage cache files in Nginx via NJS. Ultimately, the ability to properly purge a URL or series of URLs is the only specific capability that I can think of that's necessary to satisfy this request as it's already possible to control cache conditions (e.g. whether to cache or not, or to cache for differing lengths of time) through other Nginx configurations (e.g. cache bypass settings, X-Accel-Expires headers). But there are several different ways of clearing those cache files that could be beneficial.

  1. Clearing a single URL by URL
  2. Clearing a single URL by path (ignore query string)
  3. Clearing a batch of URLs by URL
  4. Clearing a batch of URLs by path (ignore query string)
  5. Clearing a batch of URLs by prefix (e.g. clear everything with a prefix path of /something)

Knowing what I know about how Nginx stores these cache files, I realize that a few of these might be more like wishlist items. Clearing by path (ignoring the query string) and clearing by path prefix might not be feasible to do. But it seems like it would be straightforward to expose mechanisms to clear a single URL by URL and separately to clear a batch of URLs by URL.

Are there any plans to expose this part of Nginx's functionality so that manual cache clears can be done with NJS instead of things like 3rd party modules and workarounds?

Dominant language
C
Stars
1.6k
Forks
245
Avg merge
2d 5h
Merged PRs (30d)
6

Getting set up

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 nginx/njs

All issues in nginx/njs

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.