How does Perma-Cache Work?

Perma-Cache is a secondary permanent cache layer, that sits between the CDN and your origin. Once a request is not cached on the CDN and is passed to the origin, the CDN will first check with the Geo-Replicated storage to see if the file is available there.

Due to the optimized routing and global footprint of our Geo-Replicated storage, this can have a very beneficial performance boost for uncached content and significant traffic servings on your servers. Instead of going from the CDN to your server every time, there's a high chance the file is already available right next to the CDN nodes on our globally replicated storage. This decreases the wait times and significantly increases the throughput for uncached files that reside on the Perma-Cache.

Let's see how it all works.


The Perma-Cache can connect to any BunnyCDN storage zone and uses a special folder structure described in the Perma-Cache Folder Structure article.

If a file is not found on the storage, the request is then passed normally back to the origin server and returned to the CDN. At the same time, a request is passed to the Perma-Cache system which then asynchronously begins the background caching process. The system connects to your origin server again and downloads the file from your origin to our Geo-Replicated storage. Depending on your replication system, the file is then replicated to our global storage network.

The next time a CDN node will request this file as part of a cache MISS, it will already be available on the storage node and the request will never hit your origin again. The file will effectively be permanently stored in our system.

A cache MISS on the CDN does not 100% guarantee that a file will appear in the Perma-Cache, so we do not suggest using this as a substitute for permanent storage.

Purging Cache

The Perma-Cache also integrates into our file purging API. When a single URL is purged through the API, our system will first send a request to the storage to delete the cached file. After that, the purge request will be processed on the CDN as well and a fresh file will be fetched from the origin again.

When purging the cache for the full Pull Zone cache, the Perma-Cache does not get deleted. Instead, the system switches to a new directory structure within the storage zone. In case of a full purge, you will need to manually delete the old caching folder.


The Perma-Cache will also add a unique set of caching headers called Perma-Cache, which can be either HIT or MISS. If the file was successfully loaded from the Perma-Cache system, the header will be returned as HIT. If the Perma-Cache passed the request to the origin first, this will appear as MISS.

CDN Caching

In cases where a file is already cached on the CDN, the request will not be passed to the Perma-Cache system until a cache MISS happens. This means that if Perma-Cache is enabled on an existing zone, it can take some time for Perma-Cache to start filling up. That just means that the CDN is already doing a great job of keeping its own cached files.


Was this article helpful?
12 out of 12 found this helpful