Fastly CDN Module for Magento 2

repository·master·Indexed 41 days ago

https://github.com/fastly/fastly-magento2

The Fastly_Cdn module integrates Fastly's CDN capabilities with Magento 2 to enhance caching performance and enable Geo-IP features. It provides advanced stale-content handling, including serving stale on errors and soft purging. The module includes a suite of CLI tools for managing configuration (fastly:conf:set, fastly:conf:get, fastly:conf:import), uploading VCL files, managing Force TLS, and controlling maintenance mode via the fastly:maintenance command.

Tokens: 24.4K
Snippets: 48
Records: 119
Agent score: 100%

What's inside Fastly

Overview of the Fastly CDN module for Magento2
master
The Fastly_Cdn module connects a Fastly.com account with a Magento 2 commerce shop to leverage enhanced caching and Geo-IP capabilities.
It operates using two primary components:
1. Magento2 Module: Extends Magento's native page cache and Varnish capabilities by adding specific Cache-Control headers to every response.
2. VCL (Varnish Configuration Language): Configures Fastly's Varnish service to process client requests and Magento HTML responses based on the headers provided by the module.
Key features include:
- Geo IP Detection: Enables regional store delivery based on the client's IP.
- Serving Stale on Errors: Serves expired content if the origin returns an error, preventing visible site outages.
- Serving Stale while Revalidating: Serves expired content while simultaneously refreshing it from the origin to maintain performance.
- Soft Purging: Marks content as expired before its TTL, allowing the cache to serve stale content while actively freshening it.
https://github.com/fastly/fastly-magento2/blob/master/README.md
Technical implementation of Other CMS integration
master
The module uses VCL to intercept requests and determine if they should be routed to the external backend.
Request Logic (vcl_recv)
1. It clears any existing X-ExternalCMS header on restarts.
2. It extracts the first part of the URL path.
3. It checks if that path segment exists in the configured Edge Dictionary.
4. If a match is found, it sets req.http.X-ExternalCMS = "1".
5. WordPress Compatibility: If the path contains /wp-admin, the module restores the Magento-Original-URL to prevent Magento's query argument sorting from breaking WordPress load-scripts.php functionality.
Hostname Overriding (vcl_pass and vcl_miss)
If an Override backend host name is provided, the following logic is applied to backend requests:
```
if ( req.backend.is_origin && req.http.X-ExternalCMS ) {
  set bereq.http.host = "<your_override_hostname>";
}
```
```
# Example vcl_recv logic applied by the module
if ( req.restarts == 0 ) {
   remove req.http.X-ExternalCMS;
}

if ( req.url.path ~ "^/?([^:/\s]+).*$" ) {
   if ( table.lookup(magentomodule_config, re.group.1, "NOTFOUND") != "NOTFOUND" ) {
     set req.http.X-ExternalCMS = "1";
     if ( req.url.path ~ "/wp-admin" ) {
       set req.url = req.http.Magento-Original-URL;
     }
   }
}
```
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/Edge-Modules/EDGE-MODULE-OTHER-CMS-INTEGRATION.md
How Mobile Themes support works via VCL
master
The Mobile Themes support module uses three VCL snippets to manage device detection and caching behavior:
1. vcl_recv: Sets the X-UA-Device header. It defaults to desktop and switches to mobile if the User-Agent matches iPhone, iPod, Android Mobile, or Tizen Mobile patterns.
2. vcl_fetch: Ensures that for text/html content types, the Vary:X-UA-Device header is set. This tells Fastly to cache different versions of the HTML based on the device type.
3. vcl_deliver: Removes the Vary:X-UA-Device header from the response sent to the user (unless the request is a Fastly debug request or part of a specific visit count) to keep the response clean.
```
# Mobile device detection for mobile themes
  set req.http.X-UA-Device = "desktop";

  if (req.http.User-Agent ~ "(?i)ip(hone|od)") {
      set req.http.X-UA-Device = "mobile";
  } elsif (req.http.User-Agent ~ "(?i)android.*(mobile|mini)") {
      set req.http.X-UA-Device = "mobile";
  } elsif (req.http.User-Agent ~ "(?i)tizen.*mobile") {
      set req.http.X-UA-Device = "mobile";
  }
```
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/Edge-Modules/EDGE-MODULE-THEME-SUPPORT.md
Automatic purging and cache observers
master
The Fastly_Cdn module includes observers that automate cache purging in synchronization with Magento cache operations. This ensures that when Magento's internal cache is refreshed, Fastly is also updated to prevent stale content.
Supported Observers
- Flush Magento Cache: Purges all objects in Fastly when the Magento cache is flushed.
- Flush Cache Storage: Purges all objects in Fastly when the cache storage is flushed.
- Flush Catalog Images Cache: Cleans objects in Fastly matching appropriate surrogate keys for images.
- Flush JavaScript/CSS Cache: Cleans objects in Fastly matching appropriate surrogate keys for JS/CSS.
Automatic Purging of Entities
You can configure the module to automatically purge CMS pages, categories, and products whenever they are saved.
Disabling Observers
If you wish to prevent these observers from taking automatic action, you must comment them out in the module's config.xml file.
https://github.com/fastly/fastly-magento2/blob/master/Documentation/OTHER-FUNCTIONS.md
Technical implementation of Hard Reload Cache Bypass
master
The Hard Reload Cache Bypass functionality works by injecting VCL snippets into the Fastly service. When a request originates from an IP in the maint_allowlist (the selected ACL) and contains a no-cache Pragma header, the following logic is applied:
1. vcl_recv: Sets req.hash_always_miss = true to ensure the request bypasses the cache.
2. vcl_hash: Appends NOCACHE to the request hash to differentiate the bypass request from standard cached requests.
```
# Snippet Type: vcl_recv
if ( req.http.Fastly-Client-IP ~ maint_allowlist && req.http.pragma ~ "no-cache" ) {
  set req.hash_always_miss = true;
}

# Snippet Type: vcl_hash
if ( req.http.Fastly-Client-IP ~ maint_allowlist && req.http.pragma ~ "no-cache" ) {
  set req.hash += "NOCACHE";
}
```
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/Edge-Modules/EDGE-MODULE-HARD-RELOAD-CACHE-BYPASS.md
Choose a Blocking mode
master
Fastly for Magento 2 supports two modes for traffic restriction. Choose the mode that matches your security requirements:
- Blocklist (Default): Blocks all access for users originating from the selected countries or ACLs.
- Allowlist (Available in version 1.2.70+): Blocks all access EXCEPT for users from the selected countries or ACLs.
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/BLOCKING.md
Use Adaptive pixel ratios (srcset)
master
The Adaptive pixel ratios feature enables delivering fixed-width images that adapt to varying device-pixel-ratios (DPR) via srcset. This allows the browser to select the most optimal image based on the device's screen density.
Note: This will increase the total size of images served to high-DPR devices. For example, a request for a 240x300 image on a dpr=2 device will result in a 480x600 image being served. Fastly will not upscale images beyond their original dimensions.
Example Transformation:
```
<img class="product-image-photo"
  srcset="https://mymagentosite/pub/media/catalog/product/m/b/mb02-gray-0.jpg?width=240&height=300&quality=80&bg-color=255,255,255&fit=bounds&dpr=2 2x,
  https://mymagentosite/pub/media/catalog/product/m/b/mb02-gray-0.jpg?width=240&height=300&quality=80&bg-color=255,255,255&fit=bounds&dpr=3 3x"
  src="https://mymagentosite/pub/media/catalog/product/m/b/mb02-gray-0.jpg?width=240&height=300&quality=80&bg-color=255,255,255&fit=bounds"
    width="240"
    height="300"
  alt="Fusion Backpack"/>
```
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/IMAGE-OPTIMIZATION.md
Force lossy conversion for images
master
By default, Fastly IO preserves the original format (e.g., PNG stays PNG) except for JPEG to WebP conversion. Enabling Force lossy conversion forces lossless formats like PNG, BMP, or WebP into JPEG or WebP.
Pros:
- Significant reduction in image size (often 60-70%).
Cons:
- Potential visual quality loss depending on settings.
- Alpha channels/transparencies are stripped and replaced with a white background (unless using Deep image optimization with a theme background color).
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/IMAGE-OPTIMIZATION.md
Enable Deep image optimization
master
Enabling Deep image optimization offloads image resizing entirely from Magento to Fastly IO. This feature applies only to product images; CMS images are not resized.
Behavioral changes:
- It adds a background color definition to every image based on your theme.
- It converts WebP images from lossless to lossy, which drops the alpha channel (transparency) to achieve much smaller file sizes.
Example Transformation: An original product image URL: https://mymagentosite/pub/media/catalog/product/cache/.../m/b/mb02-gray-0.jpg
Is rewritten to include optimization parameters: https://mymagentosite/pub/media/catalog/product/m/b/mb02-gray-0.jpg?width=240&height=300&quality=80&bg-color=255,255,255&fit=bounds
```

<img class="product-image-photo"
    src="https://mymagentosite/pub/media/catalog/product/cache/f073062f50e48eb0f0998593e568d857/m/b/mb02-gray-0.jpg"
    width="240"
    height="300"
  alt="Fusion Backpack"/>


<img class="product-image-photo"
    src="https://mymagentosite/pub/media/catalog/product/m/b/mb02-gray-0.jpg?width=240&height=300&quality=80&bg-color=255,255,255&fit=bounds"
    width="240"
    height="300"
  alt="Fusion Backpack"/>
```
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/IMAGE-OPTIMIZATION.md
Configure Abusive Crawler Protection
master
Abusive Crawler Protection guards against a single user (IP address) making an excessive number of requests that hit your Magento backend.
Default Behavior:
- The default threshold is 100 requests per hour. Once this threshold is exceeded, Fastly starts returning a block to the user.
- Unlike Path Protection, this is a general guard against high-volume request patterns hitting the origin.
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/RATE-LIMITING.md
Understand Rate Limiting exemptions
master
Certain users and entities are automatically exempt from rate limiting blocks:
- Maintenance IPs: Any IP addresses defined in var/.maintenance.ip (as configured in your Maintenance Mode settings).
- Known Good Bots: Search engine crawlers like Googlebot or Bingbot are exempt by default under Abusive Crawler Protection.
Note: You can disable the bot exemption by setting Exempt Known Good Bots to No in the configuration.
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/RATE-LIMITING.md
Manage snippets outside of Magento Admin
master
The Magento Admin UI for Custom VCL snippets only displays and manages snippets that were originally created through the Magento Admin interface.
If you add custom snippets via the Fastly API or the Fastly Web UI, they will not appear in the Magento Admin UI. To manage those specific snippets, you must use the Fastly UI or API directly.
https://github.com/fastly/fastly-magento2/blob/master/Documentation/Guides/CUSTOM-VCL-SNIPPETS.md

Fastly CDN Module for Magento 2

What's inside Fastly

Overview of the Fastly CDN module for Magento2

Technical implementation of Other CMS integration

Request Logic (`vcl_recv`)

Hostname Overriding (`vcl_pass` and `vcl_miss`)

How Mobile Themes support works via VCL

Automatic purging and cache observers

Supported Observers

Automatic Purging of Entities

Disabling Observers

Technical implementation of Hard Reload Cache Bypass

Choose a Blocking mode

Use Adaptive pixel ratios (srcset)

Force lossy conversion for images

Enable Deep image optimization

Configure Abusive Crawler Protection

Understand Rate Limiting exemptions

Manage snippets outside of Magento Admin

Fastly CDN Module for Magento 2

What's inside Fastly

Request Logic (vcl_recv)

Hostname Overriding (vcl_pass and vcl_miss)

Supported Observers

Automatic Purging of Entities

Disabling Observers

Request Logic (`vcl_recv`)

Hostname Overriding (`vcl_pass` and `vcl_miss`)