fastly / compute-starter-kit-rust-beacon-termination

Beacon Termination package template for Rust based Fastly Compute projects.

Beacon Termination Starter Kit for Rust

Capture beacon data from the browser, divert beacon request payloads to a log endpoint, and avoid putting load on your own infrastructure.

For more details about this and other starter kits for Fastly Compute, see the Fastly Developer Hub.

What are beacons?

Beacons are HTTP requests, usually POSTs, sent from a web browser to record some analytics data. Browsers offer native support for beacons via the navigator.sendBeacon method, and via the Reporting API for out-of-band reports on browser-generated warnings like CSP and feature policy violations, deprecations, browser interventions, and network errors. Native apps will also often send beacon data back to base.

For an in-depth guide to beacon termination using VCL, see the Beacon Termination tutorial.

Features

• Exposes a POST /reports endpoint to receive beacon reports (in batches)
• Deserializes individual reports from JSON to Rust data structures, with optional type-checking (see Payload examples)
• Enriches the data with information available at the edge, e.g. by adding geo data
• Sends reports to a logging endpoint as individual JSON lines N.B.: Depending on which logging endpoint type is chosen, these lines may be batched.
• Responds with a synthetic 204

Payload examples

This starter kit allows an individual report to be any valid JSON value.

For optional type-checking, it also includes the data structures for some common report payloads. These structures can be imported from modules following the example_... naming convention:

• CSP Violations

  mod example_csp_violation;
  use crate::example_csp_violation::ReportBody;
  

• Network Errors

  mod example_network_error_log;
  use crate::example_network_error_log::ReportBody;
  

• Core Web Vitals

  mod example_core_web_vital;
  use crate::example_core_web_vital::ReportBody;
  

  Tip: Use the web-vitals JavaScript library to measure all the Core Web Vitals.

Requirements

The following resources need to exist on your active Fastly service version for this starter kit to work:

• A logging endpoint called reports.

Security issues

Please see SECURITY.md for guidance on reporting security-related issues.