A MediaWiki cache built on Caddy: caddy-mwcache

.

낙엽1124·November 7, 2026

페미위키:운영팀/개발팀/기술 블로그/feed

© su neko, CC BY 2.0

Hello, this is Leslie from the Femiwiki development team. Femiwiki keeps the pages it shows to logged-out visitors in a cache we built ourselves, called caddy-mwcache. In this post I would like to introduce how this cache was made, and a bug we recently fixed that kept it from holding more than 17 pages. This post is written for readers who already know about web servers and HTTP caching.

Background

When a page changes, MediaWiki sends a PURGE request to that page's address to tell the cache in front of it to drop the old copy. Wikipedia receives these requests with Varnish, but Femiwiki had only one server, which made a separate cache server hard to justify, and it was already using Caddy as its web server. So when CPU usage suddenly rose in December 2020, we decided to cache requests from logged-out visitors, built it ourselves as a Caddy module, and released the first version in April 2021.

How the cache is built

Responses are stored in Ristretto, an in-memory cache library written in Go, and whether to cache something is decided by rules similar to Wikimedia's Varnish. For example, a request with a session or token cookie, or an Authorization header, may come from a logged-in user, so it bypasses the cache; a response carrying private, no-cache, no-store or Set-Cookie is not cached; and how long a response is kept follows the s-maxage that MediaWiki sends.

sessionCookiePattern = regexp.MustCompile(`([sS]ession|Token)=`)

func hasSessionCookie(r *http.Request) bool {
	cookie := r.Header.Get("Cookie")
	return sessionCookiePattern.MatchString(cookie)
}

By the way, when we first built it, PURGE requests never reached the cache. When $wgInternalServer is empty, MediaWiki sends PURGE to $wgServer, which is an https://… address, and Caddy took that as a proxy tunnel (CONNECT) request and passed it on over HTTPS. We fixed this by setting $wgInternalServer to http://127.0.0.1:80.

The cache that held only 17 pages

In September 2026 we noticed that the main page was always served from the cache, while an ordinary page was rendered anew no matter how many times it was reopened. Opening the same address twice and comparing the x-request-id attached to each response told them apart, because a response from the cache carries the value it had when it was cached.

/w/페미위키:대문  x-request-id: 539669cff53359cf8874d69d
/w/페미위키:대문  x-request-id: 539669cff53359cf8874d69d
/w/설경구        x-request-id: b32ef97ff7d12cf14c30ce70
/w/설경구        x-request-id: fd9e121cfaf1ee53b06a97ca

Two causes overlapped. First, every entry was given a cost of 1 when it was stored, so the max_cost setting counted entries rather than bytes. On top of that, unless IgnoreInternalCost is turned on, Ristretto adds 56, the size of its internal struct, to the cost of every entry, so an entry with a cost of 1 actually took up 57, and the cache could only hold max_cost divided by 57. Putting 5,000 entries into a cache with a MaxCost of 1,000 gives this:

held: 17
hit: 17 miss: 4983 keys-added: 5000 keys-evicted: 4983 cost-added: 285000 ... hit-ratio: 0.00

So we added a new setting, max_cost_bytes, which costs each entry at the response's size in bytes. Since someone somewhere might be using caddy-mwcache, which is open source, we left the existing max_cost as it was for backward compatibility, and when counting in bytes, the internal struct size is counted too, because it is memory actually in use.

cost := int64(1)
if m.costInBytes {
	cost = int64(len(val))
}

Hit rate

Even after the cache grew from 17 entries to 1,000, and then to 64 MiB, the number of requests served from it stayed at about 155 to 195 every five minutes. To find out why, we counted the page requests that came in during one hour from 11 a.m. on September 25 (KST).

Requests	1,691
Distinct addresses	1,545
Repeat requests for the same address	146 (8.6%)
Requests served from the cache	96
Cache usage	19.7 MB of 64 MiB

In other words, with only 146 repeat requests for the same address, no amount of extra cache size looked able to get more hits than that. 1,498 addresses were requested exactly once, which is just what a crawler sweeping a wiki from start to finish looks like; for example, one IP address made 247 requests at intervals of 3.5 to 5.7 seconds.

Other improvements

We could not raise the hit rate, but along the way we made the following improvements.

• Caddy was compressing responses taken from the cache with gzip all over again every time, and about 60% of the CPU Caddy used on the production server went to compression. Now a response is compressed once when it is stored and sent out as it is.
• Because load.php does not use sessions (MW_NO_SESSION), it is now served from the cache even when a session cookie is present. A crawler that picked up a cookie on the account creation page had been making the server rebuild a stylesheet every few seconds.
• Following Wikimedia's static.php, static files whose address carries a version hash, such as skin icons, are now marked as cacheable for a year when the hash matches the file on disk.
• The host is now part of the cache key, so pages from different hosts cannot get mixed up even if different hosts serve different pages someday.
• When several requests ask for the same page at once, MediaWiki is asked only once, and when the browser's copy is still current, the cache answers 304 without a body and adds an Age header.
• Pages are stored separately for each visitor language, so the cache works with the automatic interface language selection we recently turned on.

Closing

When we first introduced the cache, I thought that for a wiki a bigger cache was always better, and vaguely assumed it would be doing something, but recently, with crawlers making up most of Femiwiki's traffic, I saw in numbers for the first time that it does very little. Now Femiwiki also has CloudFront in front of it, so requests such as load.php are mostly served by CloudFront and caddy-mwcache takes the remaining pages behind it, among many other improvements.

caddy-mwcache is published under the AGPL, so if you run MediaWiki on a single server, we would be glad if you considered giving it a try.

References

Recent posts

• From Docker Swarm through k3s and Nomad to no orchestrator November 10, 2026
• If you use the pecl memcached client in MediaWiki, turn off Nagle's algorithm November 10, 2026
• Introducing terraform-aws-mediawiki-chart-renderer November 8, 2026

All posts (in Korean)