Request to try out OpenResty Edge

Real-time cache purge invalidates cached HTTP responses across an entire gateway network the moment you submit a purge job — with no server reload, restart, or configuration release. In OpenResty Edge you can purge by full URL, by URL prefix, or by custom conditions (URI suffix, headers, cookies, query args).

This tutorial walks through creating a purge job, verifying cache status with the Cache-Status header, purging by URL prefix, and building flexible custom purge conditions.

Cache-Status: HIT response header for a cached page in OpenResty Edge

Create a real-time cache purge job in OpenResty Edge

As always, let’s go to the OpenResty Edge’s Admin web console. This is our sample deployment of the console. Every user has her own local deployment.

OpenResty Edge Admin web console sample deployment

This time we use a real world application for our openresty.org website.

Selecting the openresty.org application in the OpenResty Edge console

Enter this application.

Application dashboard in the OpenResty Edge console

Go to the Cache Purge page of this application.

Cache Purge page of the application in OpenResty Edge

We can see that we already have a lot of previous purge jobs.

List of previous cache purge jobs in OpenResty Edge

Let’s create a new purge job.

Creating a new cache purge job in OpenResty Edge

We can see that we can purge either by full URLs,

Purging cache by full URL in OpenResty Edge

URL prefixes,

Purging cache by URL prefix in OpenResty Edge

or complex custom conditions.

Purging cache by complex custom conditions in OpenResty Edge

We’d try the full URL mode first.

Entering a full URL for the cache purge job

This is the FAQ page on that site. Note that it does not matter if we use http:// or https:// here. This is because we did not include the scheme string in our cache key. The scheme string is not included by default.

Before submitting the purge job, let’s make sure the cache is a hit for this web page so that we can test the effect of purges.

Confirming a Cache-Status: HIT before submitting the cache purge job

On the terminal, we can send test requests to the FAQ web page to make sure it is already a cache hit.

curl -I https://openresty.org/en/faq.html

And do it again.

Note the Cache-Status: HIT response header returned.

curl -I showing the Cache-Status: HIT response header before the purge

Then submit our cache purge job.

Submitting the real-time cache purge job in OpenResty Edge

Great! It is already purged across the whole network.

Cache purge job propagated across the whole gateway network

Purge cache across the whole network with no reload or release

Unlike the rest of the application-level configurations, cache purge jobs are synchronized across the gateway network immediately. It does not require making new application configuration releases. This makes real-time invalidation practical even across a self-hosted private CDN.

Cache purges do not require server reload, restart, or binary upgrade.

Cache purge synchronized to all edge nodes without a configuration release

Manage all your applications via OpenResty Edge

Verify the cache status with the Cache-Status header (HIT / EXPIRED)

Let’s verify the cache status again on the terminal.

curl -I https://openresty.org/en/faq.html

Note the Cache-Status: EXPIRED response header returned. It is indeed a cache miss now.

curl -I showing Cache-Status: EXPIRED after the cache purge

The second request should be a cache hit again.

Note the Cache-Status: HIT response header.

curl -I showing Cache-Status: HIT again after the page is re-cached

Purge cache by URL prefix

Let’s try purging by URL prefixes this time.

Choosing the URL prefix purge mode in OpenResty Edge

We purge everything under the /en/ location.

Purging everything under the /en/ URL prefix

Now submit the new job.

Submitting the URL-prefix cache purge job

It has been propagaged to the whole gateway network now.

URL-prefix purge job propagated to the whole gateway network

Send the test request to our FAQ page.

curl -I https://openresty.org/en/faq.html

It is indeed a cache miss as expected.

curl -I confirming a cache miss on the FAQ page after the prefix purge

Test another page under the /en/ URI prefix, the events page.

curl -I https://openresty.org/en/events.html

It is also a cache miss as desired.

curl -I confirming a cache miss on the events page under /en/

Or the /en/ page itself.

curl -I https://openresty.org/en/

Also a cache miss.

curl -I confirming a cache miss on the /en/ index page

We can also purge other kinds of resources like all CSS files, all our images, as long as these files are grouped under pre-defined URL locations.

Grouping CSS and image files under URL locations for cache purge

We don’t bother actually submitting this new purge job.

Cache purge job form for grouped resources in OpenResty Edge

Custom purge conditions (suffix, headers, cookies, args)

We may want to define more complicated purge conditions.

Defining more complex custom purge conditions in OpenResty Edge

We could, for instance, purge all resources with the URI suffix .css, no matter what their URI locations are.

Choose the suffix match operator.

Choosing the URI suffix match operator for a purge condition

URI suffix match operator selected for the purge condition

And then enter the suffix string value.

Entering the .css URI suffix value for the purge condition

We can add more conditions to the current purge job which are AND’d together.

Adding AND-combined conditions to the cache purge job

We may add a condition checking URI arguments, request headers, cookies, and many more.

Adding conditions on URI arguments, request headers, and cookies

We may also use wildcard or regular expression patterns instead of a literal string pattern.

Using wildcard or regular expression patterns in a purge condition

Or add more value patterns which are OR’d together.

Adding OR-combined value patterns to a purge condition

Flexible custom cache purge conditions in OpenResty Edge

Feel free to try these conditions yourself. As we can see, it is very flexible, just like our Page Rules’ conditions. This is what I’d like to cover today.

Frequently asked questions

What is real-time cache purge?

Real-time cache purge is the immediate invalidation of cached HTTP responses across every edge node in a gateway network. In OpenResty Edge, the moment you submit a purge job it propagates across the whole gateway network immediately, so cached objects matching your rule stop being served without waiting for the cache to expire on its own.

Does a cache purge require a server reload or restart?

No. Cache purge jobs are synchronized across the gateway network immediately and do not require a server reload, restart, or binary upgrade. Unlike application-level configuration changes, purges also don’t need a new configuration release to take effect.

How do I check whether a page is cached with Cache-Status?

Send a request with curl -I and read the Cache-Status response header. Cache-Status: HIT means the response was served from cache, while Cache-Status: EXPIRED (or a miss) means it was fetched from the origin. Sending the same request before and after a purge lets you confirm the purge took effect.

Can I purge the entire CDN network at once?

Yes. A single purge job applies across the whole gateway network, so you can invalidate content on a self-hosted CDN network-wide in one step. You can scope it by full URL, by URL prefix (for example everything under /en/), or by custom conditions such as a .css URI suffix.

What is OpenResty Edge

OpenResty Edge is our all-in-one gateway software for microservices and distributed traffic architectures. It combines traffic management, private CDN construction, API gateway, security, and more to help you easily build, manage, and protect modern applications. OpenResty Edge delivers industry-leading performance and scalability to meet the demanding needs of high concurrency, high load scenarios. It supports scheduling containerized application traffic such as K8s and manages massive domains, making it easy to meet the needs of large websites and complex applications.

Request to try out OpenResty Edge

If you like this tutorial, please subscribe to this blog site and/or our YouTube channel. Thank you!

About The Author

Yichun Zhang (Github handle: agentzh), is the original creator of the OpenResty® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.