1. Home
  2. Reference documentation
  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.

WARNING: Fiddles are not private, and you should assume that your work can be seen by anyone on the internet.

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 why you created the fiddle.

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 or origin_0 in a Compute program. Origins must be defined as a protocol (http:// or https://) and a hostname. Do not include a path when defining an origin.

The Fiddle tool supports dynamic backends for compatible language SDKs in Compute 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 the Fastly-provided 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:

I want the origin toSolution
... errorWith HTTP-Me origin, set request URL to /status=503 or /status=500 or whatever HTTP status code you want.
... time outWith HTTP-Me origin, set request URL to /wait=1000 (or whatever millisecond value you like) and set a short timeout with set bereq.first_byte_timeout = 1s; in vcl_miss and vcl_pass.
... return a custom cache-control TTLWith HTTP-Me origin, set request URL to /cache=3600 or whatever you want the max-age to be in seconds.
... return a specific headerWith HTTP-Me origin, set request URL to /header=key:value, adding more path segments for each header that you want included in the response.
... serve an imageWith HTTP-Me origin, set request URL to /image-png, /image-webp, /image-gif, or /image-jpeg.
... serve something specificIf it's small, Use HTTP-Me with /base64=<data> or /body=<string>. If it's big, upload your content somewhere like Mocky, GitHub pages or a Google Cloud Storage bucket, get a URL for your object, and put the hostname part in the Origins list and the path in the request URL field.
... execute some logicIf you can write JavaScript, use Glitch to set up your app. Use your app's Glitch hostname as the origin (e.g.,my-awesome-app.glitch.me). Alternatively, you could consider setting up a Google Cloud Function.
... be unhealthySet req.backend to F_origin_unhealthy. Origin servers added to a fiddle always appear to be healthy, even if they are down, due to a limitation of the Fiddle tool. This special backend is provided to allow you to test with unhealthy backends.

HINT: With Http-Me, requests are composable. Try using /status=404/image-png to see what happens, and check out Http-me for more information on combining directives.

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 query string, but not a hostname or anchor (e.g. /path/to/resource?q=text)
  • Method: Choose an HTTP 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 at the edge using VCL or Compute programs. This configuration option simulates the behavior of the client application, like a web browser. This is a good place to define headers such as Cookie, User-Agent or Accept, and should be formatted as <name>: <value>, one per line.
  • 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.
    • 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 platform only]: A set of data specified in YAML format, to be exposed to the Compute program at runtime via state interfaces such as edge dictionaries.
  • Tests: A list of assertions to verify once the request has completed. See Testing.

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 a valid configuration, and will demonstrate the default behavior of a Fastly service. For Compute fiddles, you will need some code to make the fiddle compile successfully; sample programs are available in the Compute 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 programs are able to include arbitrary third-party dependencies from package registries such as npm or crates.io. However, in Compute fiddles, currently only a specified allowlist of the most common dependencies are available:

  1. Rust
  2. JavaScript
  3. Go

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.

Log output in Fiddle

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 the Compute platform, 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, such as console.log or println. All such output is captured and displayed by Fiddle.

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 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.
  • 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 (or use a host header override when defining your backend) if you have multiple backends with different hostnames. You can still do this in fiddles, but since every execution of a fiddle has a unique public hostname, it's likely that you don't want this to be the Host value forwarded to your backend. We therefore change 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.
  • Edge Rate Limiting does not keep track of counters. Requests will always return a count of 1.
Fastly
© Fastly 2024