cloudflare_worker

sxg-rs/cloudflare_worker

This is a Cloudflare Worker that automatically generates signed exchanges (SXGs) for your site. It enables the site to be prefetched from Google Search in order to improve its Largest Contentful Paint, one of the Core Web Vitals.

Alternatively, Cloudflare Automatic Signed Exchanges provides similar functionality as well as automatic software upgrades and certificate renewals.

Ensure compatibility with SXG

The Google SXG Cache may reuse an SXG for several visits to the page, or for several users (until SXG expiration). Before installing this worker with a production certificate, follow these instructions to ensure all signed pages are compatible with such reuse. To opt some pages out of signing, set the Cache-Control header to include private or no-store in the upstream server.

The Google SXG Cache tries to update SXGs often, but may reuse them for up to 7 days. To ensure they expire sooner, set s-maxage or max-age on the Cache-Control header on the upstream server.

Install

1. Install Rust.

2. Install @cloudflare/wrangler.

3. Create a Cloudflare account and sign up for Workers account. Their free tier plan is sufficient to power up sxg-rs.

4. Clone this repo and cd into the repository root folder.

   git clone https://github.com/google/sxg-rs.git
   cd sxg-rs/

   All following steps in this README.md should be done in the repository root folder.

5. Create your config input file from the template input.example.yaml.

   cp input.example.yaml input.yaml

6. Edit the input.yaml to put the information of your website. For most fields you can use the values from the example file, but you have to change following values with yours.

   • Replace every instance of YOUR_DOMAIN with your domain name. For example, in html_host and routes.
   • Put your Cloudflare account ID and zone ID in the cloudflare section. To determine the IDs, see this screenshot.

7. Get an SXG-compatible certificate using these steps.

   • If you are using ACME, you should have followed the instructions to comment the entire pre_issued section, and uncomment create_acme_account section in input.yaml.

8. Run following command.

   cargo run -p tools -- gen-config --platform cloudflare

   This command will create a cloudflare_worker/wrangler.toml that is used by the wrangler command, and an artifact.yaml that is used by future calls to gen-config.

   • It is not recommended to directly modify the generated wrangler.toml, because your changes will be overwritten when you run gen-config again. For example, if you would like to customize the routes list in wrangler.toml based on the Cloudflare Docs, you can modify the cloudflare.routes values in your input.yaml, and run this step again.

9. Run (cd cloudflare_worker && ./publish.sh) to build and deploy the worker online.

10. Put your private key as a secret to cloudflare worker.

    1. Parse your private key to JWK format.

       go run credentials/parse_private_key.go <credentials/privkey.pem

    2. Run (cd cloudflare_worker && wrangler secret put PRIVATE_KEY_JWK). (Use the string PRIVATE_KEY_JWK as is, and don't replace it with the actual private key.)
    3. The terminal will interactively ask for the value of the secret. Put the private key in JWK format here.

11. If you are using ACME, in additional to PRIVATE_KEY_JWK, you also need to set ACME_PRIVATE_KEY_JWK. The generated artifact.yaml will contain acme_private_key_instruction.

    # artifact.yaml
    acme_private_key_instruction: echo XXXXXX | openssl enc -base64 -d | wrangler secret put ACME_PRIVATE_KEY_JWK

    Copy the command from your artifact.yaml, and use it in cloudflare_worker folder to set the wrangler secret.

12. If you are using ACME, ensure that Cloudflare's Browser Integrity Check is turned off for URLs like YOUR_DOMAIN/.well-known/acme-challenge/*. ACME servers use these URLs to verify your ownership of the domain, however Cloudflare's Browser Integrity Check blocks ACME servers, because ACME servers are not browsers.

13. Run (cd cloudflare_worker && ./publish.sh) to let the worker load the private keys.

14. Go to the workers dashboard, and edit the your_domain.com/* route to fail open, like this:

15. To check whether the worker generates a valid SXG, use Chrome browser to open https://${WORKER_HOST}/.sxg/test.html.

    • If the worker shows error, you can use (cd cloudflare_worker && wrangler tail --format pretty) to see the logs.

    • If you are using ACME, it takes a few minutes to get the certificate. During this time, the test page always fails.

16. Read on for next steps.

Maintain

If you are not using ACME, the certificates need to be renewed every 90 days.

1. Follow these steps to renew the certificate.
2. Run cargo run -p tools -- gen-config --input input.yaml --artifact artifact.yaml --platform cloudflare.
3. Run cloudflare_worker/publish.sh to restart the worker.

Uninstall

The worker and KV namespace can be deleted from the workers dashboard.