Behind a CDN

A hub’s names can be proxied by a CDN such as Cloudflare: the backend’s name, the published leaf address and the gateway hostnames, the site links included. The hub then sees the CDN’s addresses, and the CDN gives the caller’s own address in a header. Three things need setting up so everything works as without the CDN: which ranges the hub trusts for that header, the certificates, and the status the CDN answers with while the hub is out of reach.

Trust the CDN’s header#

Cloudflare gives the caller’s address in CF-Connecting-IP. The terminator and the gateway accept that header only from the ranges in WEIKIO_EDGE_RANGES and remove it from every other request, so nobody else chooses the address the audit trail records or the address the sign-in limit counts.

.env has Cloudflare’s published ranges on a commented line with the date they were taken. When the names are proxied, uncomment that line in place of the empty WEIKIO_EDGE_RANGES= and run:

$ docker compose up -d

Nothing fetches the list for you, so compare it with https://www.cloudflare.com/ips/ from time to time and update the line when Cloudflare changes its ranges. A request from outside the list still works and counts as coming from the address it came from. With the names not proxied, leave the line empty.

Another CDN works the same way when it does what Cloudflare does: it sets CF-Connecting-IP to the caller’s address, replacing any value the caller sent, and adds the caller’s address at the end of X-Forwarded-For. The terminator removes the X-Real-Ip a caller sends through the CDN.

The hub’s allowed networks judge the same caller, the address the CDN gives. The CDN’s own ranges go in WEIKIO_EDGE_RANGES and never on the allowed networks, because a range that has one of them lets every caller of the CDN in.

Certificates behind a CDN#

A proxied name doesn’t point at the hub, so Let’s Encrypt can’t check it over port 443. Either the platform proves the names through DNS with a DNS connection for the zone, or you upload the CDN’s origin certificate on Settings › Installation, as Certificates describes. When the CDN refuses the temporary certificate the hub serves before its first one, give the origin certificate to the first init with --hub-certificate.

The status while the hub is away#

Sites send their telemetry to the backend’s name, through the CDN when the names are proxied. A site keeps a batch the CDN answers with 502, 503 or 504 and sends it again later, and discards a batch answered with any other status. So while the hub can’t be reached, the CDN must answer 502, 503 or 504. A 404, or a status in the 520s that some CDNs give for a server they can’t reach, loses the telemetry the sites send meanwhile.

Sign-in limits#

The terminator limits sign-in attempts to a burst of 5 and then 10 a minute per caller, the caller being the address the CDN gives. A refused attempt gets 429 with Retry-After: 6 and the sentence Too many sign-in attempts from this address. Retry after 6 seconds. A request for /metrics gets a 404 on every name.

Uploads in parts#

A CDN caps the body of one request. Cloudflare’s cap is 100 MB on the Free and Pro plans, 200 MB on Business and 500 MB on Enterprise. The weikio CLI uploads each file of an integration larger than 32 MiB (33,554,432 bytes) in parts of that size, one request each, so a large jar in libs/ or a big mapping file passes the cap. The part size is the backend setting Weikio__Api__BlobChunkBytes, and it must stay under the cap of the plan the names are on.

The CLI knows each file’s digest before it starts, so an interrupted upload asks the hub how much it has and continues from there. The terminator has no body limit of its own and gives a request 600 seconds, so a part arrives on a link as slow as 0.5 Mbit/s.