Edge Dictionaries: Make Real-Time Decisions | Fastly

We’re always seeking ways to give our customers more control at the edge. With this in mind, we’re pleased to announce Edge Dictionaries, which give you the ability to create dictionaries (key/value pairs that your VCL can reference) inside your Fastly services. This allows you to make real-time decisions from every server in the Fastly network.

Making real-time decisions at the edge based on a particular value was previously possible with Fastly, but it was a rather cumbersome process that required many nested ‘if’ statements, like this:

if (something == "value1") {
   set other = "result1";
} else if (something == "value2") {
  set other = "result2";
}...

Building this logic is much easier with the new dictionary approach (see the ‘table’ object below) in VCL, like so:

table <ID> {
    "KEY_STRING": "VALUE_STRING",
    ...
}

We didn’t stop there, though. We understood that while the dictionary functionality was a huge improvement for our customers, it still required the following five steps to update the data inside the dictionary. A customer still had to:

1. Download current Custom VCL file.

2. Manually update table entries in the Custom VCL file.

3. Clone a new VCL version.

4. Upload edited Custom VCL.

5. Activate new version.

Instead of going through a series of these steps (which were difficult to programmatically execute), you can create, update, delete, and modify dictionaries (and their contents) via our API without having to increment your VCL version.

Essentially, Edge Dictionaries can be compared to having data that lives in an external database (the Edge Dictionary) referenced by your application (a Fastly service built on VCL).

Edge Dictionaries offer greater flexibility and control for customers across many industries. Usage examples include:

• Content sharing and social media outlets updating large referer blacklists. Companies that like to have their media shared usually want to have brand protection and revenue potential tied around this share. Undeniably, there are many fraudulent and non-partner sites that link to content in an unauthorized fashion. With Edge Dictionaries, a single (programmatic-driven) API call can update your rules to include a new referrer block or remove an existing one.

• Multi-layer token authentication. Many of our customers already use token authentication to validate that a piece of content should be served to an end user. However, these temporary tokens don’t always account for activities such as unauthorized sharing, and sometimes customers want an extra layer of authentication that may not be exposed via the initial token. With Edge Dictionaries, a customer can "challenge" a generated token (the key created in real time via API) with another value that only the authenticated requester can provide. This could be an IP address (the value, also created in the same API call) — where the requester does not actually know what the Fastly rule is looking for in addition to the URL token.

• Global publishers redirecting users to country-specific site based on geo-location. Instead of having an ‘if-then’ statement for each country-specific site and having to manually update VCL for each change, a publisher with international versions of their site can simply update their redirect rules via the Edge Dictionary API.

Some more detailed examples include:

• A major online publisher is frustrated by a suspected increase in fraudulent traffic. This is threatening their existing relationships with premium advertisers, which is impacting revenue. While they notice predictable patterns in the referrals of this fraudulent traffic, these patterns seem to change every few days; normally, this would require manual and constant updates to their VCL service configurations, which would be both cumbersome and prone to errors. 

  With Edge Dictionaries, they can create their own dictionary, and each time their bot detection system detects newly suspicious activity, it would programmatically call the Fastly API:

curl -XPOST -H 'Fastly-Key: API_KEY' 
"https://api.fastly.com/service/SERVICE_ID/dictionary/DICTIONARY_ID/item?item_key=example.com&item_value=true"

Their VCL configuration file would then show the dictionary and its contents:

table blacklists_2 {
    "example.com":"true",
 }

Now, they can create a condition to check in the table for the referer value. If the referer is in the table, they can configure a custom response to be served:

 if( table.lookup(blacklists_2, req.http.Referer, "false") ) {  
    error 900 "Fastly Internal"; 	
}  

Learn how to create your dictionary by reading our documentation.

• A high-end CMS hosting service wants to better facilitate their 20+ code pushes per day for rapid pushes, rollbacks, and A/B testing for their Ember app. A common deployment strategy in Ember apps, as embodied in ember-cli-deploy is:

1. Push a large number of possibly large asset files to a BLOB store like S3. Fingerprint each asset, as in vendor-f319e01cb3b28.js. This is the "deploy" or "publish" phase.

2. Push a smaller number of smaller files to a dynamic store like Redis. These are un-fingerprinted, as in index.html, crossdomain.xml, or robots.txt. This is the "activate" phase, as the new index.html consumes or points to the already uploaded assets.

This could also be adapted for a customer using Google Cloud Storage (GCS) and Fastly:

1. Push assets to GCS (instead of S3)

2. Use Edge Dictionaries for the un-fingerprinted files:

table tango_resources {
   "/index.html" : "<html>...</html>",
   "/crossdomain.xml" : {"<?xml version="1.0"?>…"},
}

table content_types {
   "xml" : "application/xml",
   "html" : "text/html",
   "txt" : "text/plain",
}

sub vcl_fetch {
   unset req.http.X-Content;
   set req.http.X-Content = table.lookup(tango_resources, req.url.path);
   if (req.http.X-Content) {
     error 910;
   }
}

sub vcl_error {
   if (obj.status == 910) {
     set obj.status = 200;
     set obj.response = "OK";
     set obj.http.Content-Type = table.lookup(content_types, req.url.ext);
     synthetic req.http.X-Content;
   }
}

We built this feature to give you fast, programmatic control while saving you time, allowing your team to address issues as they arise.

Read more about how to use Edge Dictionaries and email support@fastly.com if you have any questions.