Edge Dictionaries allow you to create logic that doesn't need to be attached to a configuration service version. Edge Dictionaries are made up of dictionary containers and dictionary items. Attaching dictionary containers to a service version allows you to turn frequently repeated statements into single function statements that act as a constant.
Create an empty dictionary container within a service
To use a dictionary container, start by creating an empty one within an unlocked version of a service.
Before an Edge Dictionary can be manipulated, its dictionary container must be associated with at least one service version that is not locked and not active so that the service becomes aware of the dictionary's existence.
For example, if you were creating a referer blocklist via the API, you would make an API call by running this command:
1
curl -X POST -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'name=referer_blocklist' https://api.fastly.com/service/<service_id>/version/<version_number>/dictionary
which would return:
1
2
3
4
5
6
7
8
9
10
{
"created_at": "2017-05-03T16:11:41+00:00",
"deleted_at": null,
"id": "<dictionary_id>",
"name": "referer_blocklist",
"service_id": "<service_id>",
"updated_at": "2017-05-03T16:11:41+00:00",
"version": <version_number>,
"write_only": false
}
Activate the service associated with the dictionary container
For an Edge Dictionary to appear in generated VCL so it can be referred to later, the version associated with the dictionary container must be activated.
In our referer blocklist example, you would make this API call to activate service version associated with the empty dictionary container you created:
1
curl -X PUT -H 'Fastly-Key: FASTLY_API_TOKEN' https://api.fastly.com/service/<service_id>/version/<version_number>/activate
The response would be this:
1
2
3
4
5
{
"number": <version_number>,
"active": true,
"service_id": "<service_id>"
}
Add dictionary items
Once the dictionary container becomes associated with the configuration of a service, you can begin populating it with dictionary items. Our guide to working with dictionary items provides more detail on manipulating dictionary items. In the example shown here, you would use the following API call for each URL you want to add to your referer blocklist:
1
curl -X POST -H 'Fastly-Key: FASTLY_API_TOKEN' -d 'item_key=example-referer.org&item_value=true' "https://api.fastly.com/service/<service_id>/dictionary/<dictionary_id>/item"
The response for each URL added would look similar to this:
1
2
3
4
5
6
{
"dictionary_id": "<dictionary_id>",
"service_id": "<service_id>",
"item_key": "example-referer.org",
"item_value": "true"
}
Once the blocklisted URLs are added as items in your dictionary container, you can find them in your generated VCL by looking for a table similar to this:
1
2
3
4
5
table referer_blocklist {
"example-referer.org": "true",
"another-referer.net": "true",
"sample-referer.com": "true",
}
Using a service to call dictionaries
When you create Edge Dictionaries via API calls, the dictionary contents aren't tied to any single version of your service.
The logic needed to interact with the table of information the Edge Dictionary creates, however, is always tied to a service version.
For example, adding a new referer to your blocklist requires that you specifically interact with the Edge Dictionary at some point after you create it. You could do this via API calls because its data would not require a service version activation. The dictionary was created via API calls not via custom VCL.
Specifically, you would set the Host of the referer to a header by including custom VCL like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// versioned vcl
sub vcl_recv {
# capture host of referer into a header
set req.http.Referer-Host = regsub(req.http.Referer, "^https?://?([^:/\s]+).*$", "\1");
# check if referrer host is in blocklisted table
if (table.lookup(referer_blocklist, req.http.Referer-Host)) {
# ResponseObject: forbidden-referrer
error 900 "Fastly Internal";
}
#end condition
}
sub vcl_error {
if (obj.status == 900) {
set obj.http.Content-Type = "";
synthetic {""};
return(deliver);
}
}
Custom VCL examples
These examples illustrate how to use Edge Dictionaries in custom VCL. The dictionaries are created via API calls and are displayed in the tables.
IMPORTANT: Personal data should not be incorporated into VCL. Our Compliance and Law FAQ describes in detail how Fastly handles personal data privacy.
Example: Referer blocklist
This example returns a 403 error message if the referer is in the dictionary.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// dictionary items can be added, updated, removed via the API
// does not require cloning and activating versions
table bad_actors {
"example.com" : "nope",
"fastly.com" : "nope",
}
// versioned vcl
sub vcl_recv {
set req.http.Referer-Host = regsub(req.http.Referer, "https?://([^/]+)/.*", "\1");
set req.http.Referer-Check = table.lookup(bad_actors, req.http.Referer-Host, "yes");
if (req.http.Referer-Check == "nope") {
error 403;
}
}
Example: CORS origin database
This example adds the origins in the dictionary to the Access-Control-Allow-Origin
header.
1
2
3
4
5
6
7
8
9
10
11
12
13
// dictionary items can be added, updated, removed via the API
// does not require cloning and activating versions
table acceptable_origins {
"http://example.com" : "yes",
"http://fastly.com" : "yes",
}
// versioned vcl
sub vcl_deliver {
set req.http.CORS = table.lookup(acceptable_origins, req.http.Origin, "nope");
if (req.http.CORS == "yes") {
set resp.http.Access-Control-Allow-Origin = req.http.Origin;
}
}
Example: TTL database
This example sets the TTLs for the URLs in the dictionary.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// dictionary items can be added, updated, removed via the API
// does not require cloning and activating versions
table ttls {
"/" : "60",
"/public" : "86400",
"/api" : "3600",
"/foo" : "7200",
"/user" : "5"
}
// versioned vcl
sub vcl_fetch {
/* cut URL down to first directory, or just / */
if (req.url.path ~ "^(/[^/\?]*)") {
/* should always be true */
set beresp.ttl = std.atoi(table.lookup(ttls, re.group.1, "30"));
}
IMPORTANT: Personal information, secrets, or sensitive data should not be included in dictionaries or incorporated into VCL. In addition, we do not maintain version histories of your dictionaries. Our Compliance and Law FAQ describes in detail how Fastly handles personal data privacy.