1. Home
2. Learn to build on the Fastly platform
3. Tools
4. Fiddle

Authoring fiddles

As soon as you begin typing into the Fiddle interface, your fiddle will be assigned a unique ID that will appear in the address bar of your browser. At any time, you can copy this URL and send it to a friend, colleague, or the Fastly support team, and they will be able to see what you've created.

Here we'll look at the components of a fiddle.

Title

Click on the text Click to set title to replace it with a name of your choice. This is a good way to remember what the fiddle was for.

Origin servers (backends)

You can configure up to five statically-defined origin servers for a fiddle. When you create a blank fiddle, we pre-populate https://http-me.glitch.me/ as the only origin by default. This becomes F_origin_0 in VCL and origin_0 in Compute@Edge languages. Origins must be defined as a protocol (http:// or https://) and a hostname. Do not include a path when defining an origin.

Fiddle supports dynamic backends for compatible language SDKs, and has dynamic backends enabled on all fiddles.

You may want to use your own application servers as origins, or other third party services designed for this kind of testing. In addition to HTTP-Me, Mocky can be a useful way to create the backend behavior that you want for testing Fastly. Here are some other ideas for ways to simulate certain origin server behavior:

Requests

The Configure requests section of the fiddle web interface allows you to set up the requests that will be sent to the external domain of your Fastly service when the fiddle is RUN. The following elements of each request are customizable:

• Path: The large text field takes a URL path, which may include a querystring, but not a hostname.
• Method: Choose a method other than GET if you wish.
• Headers: This text field allows setting of headers that you want to send in the request to Fastly. This should not be confused with headers that you set in VCL. These headers are essentially simulating those that would be set by the browser. This is a good place to define a Cookie: <something> header, for example.
• Body: Request body. Only UTF-8-encoded text is currently supported. For POST requests, this is a good place to add data in application/x-www-form-urlencoded or application/json format. Will be sent regardless of the request method, so be sure to choose a method that suits having a request body.
• Options: A set of request-specific connection options:
  • Enable clustering: [VCL only] Enables the clustering mechanism to direct requests to the appropriate storage node within a POP. Enabled by default in fiddle and also in normal Fastly services.
  • Enable shielding: [VCL only] Sets up shielding for all the origins configured in the fiddle. The choice of shield location cannot be changed.
  • Enable WAF: [VCL only] Enables Fastly's Web Application Firewall (WAF) for your fiddle service. See using WAF with fiddle to learn more.
  • Follow redirects: Prompts the Fiddle client to follow 3xx redirect responses automatically. Normally when a redirect (3xx response with Location header) response is returned from your fiddle service, it will just be reported. If you prefer you can tell Fiddle to automatically follow the redirect and execute an additional request. Fiddle will not follow redirects if the redirect response has resulted from following an earlier redirect (i.e. we will not fall into a redirect loop).
  • Use fresh cache: [VCL only] Empty the edge cache before sending this request.
  • Connection: Sets the connection protocol. Most requests to Fastly are over HTTP/2 (which mandates the use of TLS). If you prefer you can choose to use HTTP/1.1, either with or without TLS.
  • Client IP: Overrides the client IP address. A number of Fastly platform services act upon the client's IP address, such as geolocation. For reliable testing, you may want to choose to spoof a predictable IP address associated with a specific region.
• Data [Compute@Edge only]: A set of data specified in YAML format, to be exposed to the Compute@Edge application at runtime via state interfaces such as edge dictionaries.
• Tests: A list of assertions to verify once the request has completed. See Writing tests.

Edge logic

Within the Edge logic section, you can write the code that defines the behavior of your fiddle service. For VCL fiddles, you don't have to write code here; simply giving a title to a blank fiddle will make it runnable, and will demonstrate the default behavior of a Fastly service. For Compute@Edge fiddles, you will need some code to make the fiddle compile successfully; sample programs are available in the Compute@Edge usage guides for the language of your choice.

For examples of fiddles populated with code, see our library of code examples. As a simple starting point, try adding the following to the vcl_recv field in a VCL fiddle, and then press RUN:

set req.http.My-Fiddle-Header = "Hello world!";

You should see a report showing that Fiddle has made a request to Fastly and that Fastly has passed the request to the origin server, adding a My-Fiddle-Header HTTP header along the way. To learn more about interpreting and analyzing the results of running a fiddle, move on to the Running fiddles and interpreting results page.

Dependencies

Compute@Edge programs are able to include arbitrary third-party dependencies from package registries such as npm or Crates.IO. However, in Compute@Edge fiddles, currently only a specified allowlist of the most common dependencies are available:

In VCL services, and therefore in VCL fiddles, dependencies and imports are not supported.

Logging

Logging from a Fastly service normally requires creating a named Log endpoint, and then sending output to it from VCL using the log statement:

log "syslog " req.service_id " log-endpoint-name :: LOG MESSAGE HERE";

You cannot create your own log endpoints on fiddles, but Fiddle will intercept any log output and render it in the report.

The normally required service ID and log endpoint name can be set to anything or omitted entirely. All of the following log statements will work in VCL fiddles:

log "syslog " req.service_id " log-endpoint-name :: LOG MESSAGE HERE";
log "syslog :: LOG MESSAGE HERE";
log "LOG MESSAGE HERE";

In Compute@Edge, each language SDK offers an API for logging to Fastly named log endpoints, and the language usually also offers methods for directing output to STDOUT or STDERR. All such output is captured by Fiddle.

Using WAF with Fiddle

If Enable WAF is selected in request options, the Fastly WAF is available to your VCL fiddle service. The WAF inspects requests and triggers behaviors based on rules. These are customizable per-service, and the set of rules configured for Fiddle is not editable, so rather than testing your specific WAF configuration, you can use Fiddle to understand the mechanism of how WAF integrates into Fastly services.

By default, WAF will run at the end of vcl_miss and vcl_pass, after your fiddle's VCL. To trigger it manually, call the fiddle_waf custom subroutine:

call fiddle_waf;
# ... code to execute AFTER the WAF has run

If you include call fiddle_waf; anywhere in your code, Fiddle will not invoke WAF automatically. When the WAF is triggered, it will throw an error code 991. You can intercept this in vcl_error if you want:

if (obj.status == 991 && obj.response == "WAF block") {
  set obj.status = 403;
  set obj.response = "Forbidden";
  set obj.http.Content-Type = "text/html";
  synthetic "Request blocked!";
  return (deliver);
}

Fiddle will capture error 991 automatically and convert it to a 403 Forbidden if you don't do anything with it yourself.

Service chaining

The hostname on which the fiddle is hosted is allocated dynamically at runtime, which means you can't know what it will be ahead of time. This makes it hard to do so-called 'service-chaining', in which a Fastly service uses itself as an origin server. To allow for service chaining in fiddles, we therefore support the special origin hostname https://self, which will be transformed into the hostname on which the fiddle is hosted.

Limitations

While the intention is that anything you can do with a real Fastly service, you can do in a fiddle, there are some exceptions and limitations:

• All fiddle code is public. It is intentionally not possible to have private fiddles. Anything you type or paste into the Fiddle web interface is visible to anyone on the internet.
• No defining origins in VCL. Unlike in a real VCL service, you can't define origins in Fiddle VCL. Use the origin text fields in the Fiddle web interface for this instead, and then refer to them in VCL as F_origin_0 through F_origin_4. You also cannot define origins in Compute@Edge fiddle code but you can't do it in a real Compute@Edge service either.
• Some header names are reserved. You can't read or write any HTTP header that begins with Fastly-Fiddle, because these are used by the Fiddle tool.
• The Host header is set automatically. Normally you would need to set the Host header if you have multiple backends with different hostnames. You can still do this in fiddles, but since you will almost always need to set an override (otherwise the host header passed to the backend will be something like exec1.fiddle.fastly.dev), we do it for you if you don't do it yourself.
• Backends are always healthy for origins you define, even if your origin is down. This is a side effect of using a proxy to collect data about origin requests (the health check is checking the proxy, not the actual origin). If you want to test using an unhealthy backend, use the special F_origin_unhealthy backend in VCL fiddles, which is always sick.
• Fiddles can only be directly executed by the creator. We don't allow fiddles to be executed outside of the app by anyone other than the creator, because we don't want to allow anyone to host arbitrary content on our infrastructure. If you want to share a fiddle with someone else, you can do so by copying the URL, appending /clone, and sending it to them.