fastly_compute

sxg-rs/fastly_compute

This is a Fastly Compute@Edge app 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.

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 app 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 using rustup.

2. Install Fastly CLI.

3. Install Fastly CLI local dependencies.

4. Clone this repo and cd into the current folder.

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

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

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

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

   cp input.example.yaml input.yaml

   • Replace every instance of YOUR_DOMAIN with your domain name, for example, in html_host.

   • For private key

     1. Parse your private key to base64 format.

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

     2. Put the base64 string to input.yaml as sxg_private_key_base64.

7. Run following command.

   cargo run -p tools -- gen-config --input input.yaml --artifact artifact.yaml --platform fastly

   This command will create a new Fastly compute service and create a fastly_compute/fastly.toml that is used by the fastly command.

   • It is not recommended to directly modify the generated fastly.toml, because your changes will be overwriten when you run cargo run -p tools -- gen-config again.

8. Modify the WASM service in Fastly.

   1. Add a domain to the service. This domain will be the final entrypoint of the SXG service.

   2. Add your original server, which serves your HTML website, as a backend to the service. Put it to config.yaml as html_host (see config.example.yaml). Edit the backend and change its name from Host 1 to Origin HTML server.

   3. Add the OCSP server (such as ocsp.pki.goog or ocsp.digicert.com) as a backend to the service. Edit the backend and change its name from Host 1 to OCSP server, and change the port from TLS 443 to Non-TLS 80.

9. Run fastly compute publish.

   • During this step, fastly command will generate a random domain name (for example random-funky-words.edgecompute.app), which is the domain your Fastly worker is deployed on. We refer this domain as WORKER_HOST.

10. If you are using certificates through ACME

    1. Set the config of your original HTTP server (of YOUR_DOMAIN), and make sure http://YOUR_DOMAIN/.well-known/acme-challenge/* is redirected to https://WORKER_HOST/.well-known/acme-challenge/$1.

    2. Run cargo run -p tools -- apply-acme-cert --artifact artifact.yaml --use-fastly-dictionary.

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

12. Configure Fastly caching so that it doesn't serve SXGs to non-SXG request. Either:

    • Include in the cache key, a boolean of whether the Accept header matches this regex.
    • Include conditional logic that bypasses the cache if the Accept header matches that regex.
    • Disable caching.

13. Read on for next steps.

Maintain

The certificates need to be renewed every 90 days.

1. If you are using ACME:

   1. Run cargo run -p tools -- apply-acme-cert --artifact artifact.yaml --use-fastly-dictionary.
   2. Alternatively, you may run cargo build -p tools once and then run tools apply-acme-cert --artifact artifact.yaml --use-fastly-dictionary every 90 days.

2. If you are not using ACME,

   1. Follow these steps to renew the certificate.
   2. Run fastly compute publish to restart the worker.