Forem: Katsuyuki Omuro

Start your next Fastly Compute JavaScript application with npm init

Katsuyuki Omuro — Thu, 19 Dec 2024 08:03:51 +0000

The npm init (or npm create) command is a popular, platform-standard method of initializing a JavaScript application based on a template. If you’re working with JavaScript in Fastly Compute, we have exciting news for you – the npm init script for Fastly Compute gives JavaScript authors an additional way to start their Fastly Compute applications using common and standard tools.

Just over a year ago, JavaScript became a generally available language for development on Fastly Compute. With this, we have been able to bring the convenience of JavaScript to the power of the edge to developers around the world. JavaScript is a very popular language on the platform, and we want to continue to give it access to as many users as we can.

In October we announced that we have brought the Fastly CLI to npm. Today we have additional good news for JavaScript users: we now have an official npm init script for Fastly Compute!

In case you’re not familiar with npm init, it is a method of initializing a new JavaScript project based on an initialization script, built into the npm command. Fastly now provides an initializer for npm init, so it’s possible to create a new Fastly Compute project in JavaScript like this:

npm init @fastly/compute

After typing this command, you will be presented with interactive prompts to select a directory, language, and starter kit, to create your Fastly Compute application in JavaScript or TypeScript.

The initializer called by npm init @fastly/compute is a Node.js program distributed via npm under the name @fastly/create-compute. It asks questions relevant to your new JavaScript application, and then under the hood, calls the Fastly CLI to initialize your new application. No global installation of the CLI is required, however, since it declares the dependency as an npm package.

You’re already working with JavaScript, stay in the JavaScript mindset

Traditionally, the procedure to create a new Fastly Compute application has been to obtain the Fastly CLI and type the following:

fastly compute init

This meant that it was necessary for you to install a global instance of the Fastly CLI just to create a new application for Fastly Compute. You also needed it to run and publish the application. Because this was true even if you just wanted to experiment with the platform, we felt that this was sometimes getting in the way of developers wanting to try out the platform. Additionally, the Fastly CLI would prompt the selection of a programming language when initializing a new project, a potential friction point that could even take you “out of the zone” when you are already thinking in terms of JavaScript.

As always, we looked for ways to enable developers to get the job done with one fewer tool needed to be installed, with one fewer click, with one fewer dependency. Is there a way to enable JavaScript development to be even simpler? The solution was to use the standard, platform-defined npm init mechanism to allow users to initialize new applications for Fastly Compute in JavaScript.

Most JavaScript developers are already familiar with npm, since it's the tool used to install dependency packages into your application. Being able to use the npm tool to initialize a new application enables developers to stay with tools within the JavaScript ecosystem from the start of the lifetime of their application.

Batteries included!

Recently, Fastly’s JavaScript and TypeScript starter kits have been updated to install the Fastly CLI as a dependency package. This means that for most tasks you no longer need to work with the Fastly CLI directly, to run or publish your application. Instead, you are able to work with it through npm scripts.

Once your application has been initialized, use the following command to start your application:

npm run start

This will run fastly compute serve, which will build your application and start it under the development environment.

When you’re ready to go live, type the following command to deploy to production (for most starter kits):

npm run deploy

This will run fastly compute publish, which will build your application and publish it to your Fastly account.

Of course, if you would like to call the Fastly CLI directly, or in the case you need to perform additional functions with the Fastly CLI, such as add backends or work with edge storage, you can invoke it from within your application directory using npx:

npx fastly <command>

JavaScript + edge computing = ❤️

At Fastly, we enjoy providing you with the power to run more code at the edge and develop for it with the tools you know and love. One fewer thing to get in the way is one more victory for us in that direction. Our initializer enabling you to create JavaScript applications for Fastly Compute using npm is another item on this journey.

We love to hear about it when our users get the most out of these tools. Get your free Fastly developer account, join us on the Fastly community forum, and let us know what you’ve been building!

Fastly CLI on npm: now at your JavaScript fingertips

Katsuyuki Omuro — Thu, 19 Dec 2024 07:57:10 +0000

The Fastly CLI is the recommended tool provided by Fastly for interacting with the Fastly API from the command line. It’s an open-source tool used by developers and in continuous integration pipelines to perform various actions on behalf of a Fastly account, including creating services, managing backends and domains, and deploying Compute packages. If you’re working with Fastly Compute in JavaScript, we have exciting news that brings the Fastly CLI closer to you – the Fastly CLI is now available as a package on npm.

It’s been an exciting three years since we announced JavaScript support in the Fastly Compute edge platform, and almost two years since we released v1.0 of the JavaScript SDK. It’s a very popular language on the platform and also happens to be my personal favorite. Developing for Fastly Compute using JavaScript enables the creation of edge applications in a quick and fun way, and we want to extend access to it to as many users as we can.

As a developers-first company, there is one thing we always have on our minds: to remove as many obstacles as possible from getting in the way of actual development. That is, how can we enable developers to get the job done with one fewer click, with one fewer dependency, with one fewer tool needed to be installed? Is there a way to make JavaScript development on Compute simpler? That’s what we set out to tackle this time.

The Fastly CLI is an open-source tool used to perform actions with your Fastly account. Since it’s used for running and publishing Compute applications, it is one of the requirements for developing for Fastly Compute in JavaScript, even if it’s just to try it out locally. This has traditionally meant a trip to the GitHub repository to obtain a prebuilt package, or installing it through Homebrew on macOS. While these are steps that are generally familiar to developers, we wanted to lower the barrier as much as we can for getting your feet wet in Compute application development.

That’s why starting with version 10.14.0, we’ve decided to publish the Fastly CLI on npmjs.org as an additional avenue of distribution. If you’re a JavaScript developer in 2024, chances are you’re familiar with npmjs.org as the de facto package repository from where you install packages into your application, whether you use yarn, pnpm, or the trusty old npm as your interface. This means npmjs.org is available by default to everyone, making it a great way for us to put this essential tool into our users’ hands.

Run the Fastly CLI without needing to install it

One handy feature of npm is npx, which allows you to run commands from npm packages without being required to install them to a project. So long as Node.js and npm are available in your environment, you can now directly invoke the Fastly CLI as such:

npx @fastly/cli

The first time you do this, you will be prompted by npm to fetch the package; this will add it to your environment’s npm cache, and it will be available immediately in the future.

Since the Fastly CLI is always called with additional parameters, you just specify them as normal as parameters following the command. For example, to list the services in your Fastly account, you can type:

npx @fastly/cli service list

Fastly CLI as a dependency package

Of course, availability on npmjs.org means you can now add the Fastly CLI to your Compute JavaScript application as a standard dependency:

npm install @fastly/cli
Alternatively, you can add it to your project’s package.json file:

{
  "dependencies": {
    "@fastly/cli": "^10.14.0"
  }
}

Then install the dependencies for the project:

npm install

This installs @fastly/cli as a dependency into your project’s node_modules directory. It becomes available as a program called fastly under the node_modules/.bin subdirectory, so you will be able to invoke it like this:

npx fastly

For example, to start your application in the local development environment, type the following:

npx fastly compute serve

Additionally, any references to fastly in the scripts section of the package.json file will now find this locally installed version of @fastly/cli instead of requiring a global installation of the Fastly CLI to be available on the system.

{
  "scripts": {
    "build": "js-compute-runtime src/index.js bin/main.wasm",
    "start": "fastly compute serve",
    "deploy": "fastly compute publish"
  }
}

No global installation necessary

Traditionally, it has been necessary for every developer working with Fastly Compute to install a globally available instance of the Fastly CLI to develop applications and publish them to their Fastly account, even when just getting started with the platform to experiment. By making the Fastly CLI available as a standard dependency to a JavaScript application, first-time users of Fastly Compute can experience a Compute application by simply cloning its application repository, installing its dependencies as normal, and typing npm start. In fact, we have updated all our JavaScript and TypeScript starter kits to take this approach, so that they can be experienced by more users, even if they have no prior experience with the Compute platform.

It’s also great when you work in a team. You, as well as other developers who work with your application, can obtain your application’s code, use the standard procedure to install its dependencies, and get right to work, batteries included.

This convenience extends to your continuous integration (CI) pipeline as well, enabling your application to have reliable access to the Fastly CLI as part of its build or test process.

Use new features of the CLI with confidence

The Fastly CLI is under active development, constantly receiving new features and improvements.

Specifying the Fastly CLI as a standard dependency of your package enables you to prescribe its version using semantic versioning. This allows your package to safely depend on features of the CLI that have been added recently or whose behavior may have changed, without having to worry about whether other developers who work with your application have a compatible version of the CLI installed on their environments.

Calling the Fastly CLI from Node.js code

If you are writing code intended to run under Node.js that calls out to the Fastly CLI, such as in a tool or utility program, this package provides a very straightforward and reliable way to do so.

The default export of @fastly/cli resolves to a string value representing the full path of the executable of the Fastly CLI, appropriate for the operating system, architecture, and how it has been installed. It can be used directly with functions such as spawnSync in Node.js. Because this is available in this way, you don’t need to have the user of your package obtain a global installation of the Fastly CLI before running your program.

The following example Node.js program executes the fastly version command:

import { spawnSync } from 'node:child_process';
import fastly from '@fastly/cli';

const result = spawnSync(fastly, [ 'version' ]);

console.log(result.stdout);

Even install the Fastly CLI globally

If you ever do need a global installation of the Fastly CLI, this package also acts as one way of obtaining it for global use:

npm install -g @fastly/cli

Once it’s installed, invoke it as you would have done traditionally:

fastly

Under the hood, this is no different than invoking the copy of the CLI cached in the environment using npx @fastly/cli. However, this procedure makes the command available as fastly on the system path, enabling it to fit with other tools that expect to find it there. The end result is effectively identical to if you had used any of the traditional methods of global installation, but this installation process is a convenient alternative, as npm is widely available on many machines.

Bringing edge computing to more developers

At Fastly, we strive to provide the tools that give you the power to run more code at the edge and develop for it with the tools you know and love. We want nothing to get in the way of this. As JavaScript is the most popular language on the planet, the release of the Fastly CLI on npm moves the needle further along this mission.

We love to hear about it when our users get the most out of these tools. Get your free Fastly developer account, join us on the Fastly community forum, and let us know what you’ve been building!

A modular Edge Side Includes component for JavaScript Compute

Katsuyuki Omuro — Thu, 19 Dec 2024 07:41:28 +0000

In the summer of 2022, my teammate Kailan worked on a Rust crate for Fastly Compute, implementing a subset of the Edge Side Includes (ESI) templating language, and published a blog post about it. This article was significant not just because we released a useful library, but because it was a brilliant illustration of what Compute can bring us: a programmable edge with modular functionality. And now that JavaScript has been generally available on Compute for more than a year, it was time we had a similar solution for our JavaScript users. Fastly’s ESI library for JavaScript, now available on npm, allows you to add powerful ESI processing to your application.

Programmability and Modularity

For almost a decade, Fastly’s CDN has had support for Edge Side Includes (ESI), a templating language that works by interpreting special tags in your HTML source. It revolves around the tag <esi:include>, which instructs the edge server to fetch another document and inline it into the stream.

index.html

<body>
<esi:include src="./header.html" />
<main>
Content
</main>
</body>

header.html

<header>Welcome to the web site</header>

output

<body>
<header>Welcome to the web site</header>
<main>
Content
</main>
</body>

When Compute entered the scene, the edge landscape changed in two main ways: programmability and modularity.

Soon after our platform support for Rust had stabilized, we published a crate for Rust that implemented ESI, and added programmability. You could now configure, using code, how to build additional backend requests, and how to handle response fragments. You could even perform ESI processing on documents that don’t originate from the backend server. This programmability differentiated it from the ESI support we have in VCL, which was limited to the fixed set of features we offered.

At the same time, this approach was highly modular, giving the programmer a choice to perform this ESI processing on a per-request basis, and the option to combine the processing with other modules that work with compatible data types, and apply them in any order and/or logical condition specified.

Next target: JavaScript

Similar to our Rust release, we wanted this JavaScript library to be programmable. Fastly’s JavaScript support has always embraced the Fetch API and its companion Streams API. One useful feature of the Streams API is the TransformStream interface, allowing for data to be “piped” through an object in order to apply a transformation—perfect for ESI. By implementing the ESI processor as an implementation of TransformStream, we were able to fit it right into a Fastly Compute Application written in JavaScript.

Here's how you can stream through it:

const transformedBody = resp.body.pipeThrough(esiTransformStream);

return new Response(
  transformedBody,
  {
    status: resp.status,
    headers: resp.headers,
  },
);

The transformation, which we call the EsiTransformStream, is applied to the stream directly, alleviating memory and performance concerns. This means:

There is no need to buffer the entire upstream response before applying the transformation.
The transformer consumes the upstream response as quickly as it can, and processes ESI tags as they show up in the stream. As the transformer finishes processing each ESI tag, the results are released immediately downstream, so we are able to hold the minimal possible buffer. This allows the client to receive the first byte of the streamed result as it becomes ready, without having to wait for it to be processed in entirety.

In addition, this design is modular, making the EsiTransformStream just another tool you can use alongside other things. For example, you might have other transformations you want to apply to responses, like compression, and a response can be piped through any number of these transform streams, since it's a completely standard interface. If you wanted to, you could even conditionally enable ESI for just certain requests or responses, such as by request headers, paths, or response content type.

Here's how you instantiate EsiTransformStream:

const esiTransformStream = new EsiTransformStream(req.url, req.headers, {
  fetch(input, init) {
    return fetch(input, { ...init, backend: 'origin_0' });
  }
});

The constructor takes a URL and a Headers object, and optionally takes some options as a third parameter. As described earlier, the main functionality of ESI is to download additional templates, for inclusion into the resulting stream. Encountering an <esi:include> tag uses fetch as the underlying mechanism to retrieve a template, and the main purpose of these parameters is to configure those fetch calls:

The URL is used to resolve relative paths in the src of <esi:include> tags.
The Headers are used when making the additional requests to fetch the templates.
The optional configuration object can be used to override the behavior of the fetch that is made, and to apply other custom behavior, such as how to process the fetched template, and custom error handling.

In the simplest case, you’ll use just the fetch value of the configuration object. If you don’t provide it, then it uses the global fetch function instead, but in Compute you’ll need it to specify a backend for the fetch to use when including a template (unless you’re using the dynamic backends feature). The example snippet above assigns the backend named origin_0 before calling the global fetch.

That’s it! With this simple setup you can have a backend serving ESI tags and a Compute application processing them. Here’s a full example that you can run:

fiddle.fastly.dev

Support for ESI features

This implementation offers more ESI features than others we have made available in the past.

Error handling

Sometimes, a file referenced by an <esi:include> tag may fail to fetch due to it not existing or causing a server error. It’s possible to ignore the error in these cases by adding the attribute onerror="continue".

<esi:include src="/templates/header.html" onerror="continue" />

If /templates/header.html causes an error, the ESI processor silently ignores the error and replaces the entire <esi:include> tag with an empty string.

It’s also possible to use more structured error handling by employing an <esi:try> block, which looks like this:

<esi:try>
  <esi:attempt>
    Main header
    <esi:include src="/templates/header.html" />
  </esi:attempt>
  <esi:except>
    Alternative header
  </esi:except>
</esi:try>

The ESI processor first executes the contents of <esi:attempt>. If an esi:include tag causes an error, then the ESI processor executes the contents of <esi:except>.

It’s important to note that the entire <esi:try> block is replaced by the entirety of the <esi:attempt> block if it succeeds or the <esi:except> if there is an error. In the above example, if /templates/header.html causes an error, then this also causes the text "Main header" not to appear in the output; only the text "Alternative header" is included. See the ESI language specification for more details.

Conditionals

ESI also allows conditional execution, by performing runtime checks on variables. The following is an example of such a check:

<esi:choose> 
    <esi:when test="$(HTTP_COOKIE{group})=='admin'"> 
        <esi:include src="/header/admin.html" /> 
    </esi:when> 
    <esi:when test="$(HTTP_COOKIE{group})=='basic'">
        <esi:include src="/header/basic.html" />
    </esi:when> 
    <esi:otherwise> 
        <esi:include src="/header/anonymous.html" /> 
    </esi:otherwise>
</esi:choose>

When the processor encounters an <esi:choose> block, it runs through the <esi:when> blocks, checking the expressions set in their test attributes. The processor executes the first esi:when block where the expression evaluates to true. If none of the expressions evaluates to true, then it will optionally execute the esi:otherwise block if it’s provided. The entire <esi:choose> block is replaced by the entirety of whichever <esi:when> or <esi:otherwise> block that executes.

The processor makes available a limited set of variables, which are based primarily on request cookies. In the above example, an HTTP cookie by the name “group” is checked for its value. Our implementation is based on the ESI language specification; refer to it for more details.

List of supported tags and features

This implementation supports the following tags of the ESI language specification.

esi:include
esi:comment
esi:remove
esi:try / esi:attempt / esi:except
esi:choose / esi:when / esi:otherwise
esi:vars

The <esi:inline> tag is defined in the spec to be optional, and is not included in this implementation.

ESI Variables are supported in the attributes of ESI tags, and ESI Expressions are supported in the test attribute of <esi:when>. Additionally, the  comment is supported.

Custom behavior means endless possibilities

While the feature set is enough to get thrilled about, the truly exciting part of being programmable is that even more things are possible. Bringing in templates is the main use of ESI, but that’s by no means all that it can do. Here’s an example.

Consider you have a timestamp marked up in your document that you want represented as a relative date when it’s displayed, such as “2 days ago”. There are many ways of doing this, but to have the best performance and memory implications, it would be great to perform a find/replace in streams. Programming this ESI library can actually be used as a good option for doing this.

We can define timestamps to be encoded in your backend document using a specially-crafted ESI tag in a format such as the following:

<esi:include src="/__since/<unix-timestamp>" />

For example, this snippet can represent midnight on January 1, 2024, Pacific time:

<h1>This document was written <esi:include src="/__since/1704034800" />.</h1>

Now, set up the EsiTransformStream to serve a synthetic replacement document whenever it sees that URL pattern:

const esiTransformStream = new EsiTransformStream(req.url, req.headers, {
  fetch(input, init) {
    const url = new URL(input instanceof Request ? input.url : String(input));

    // If custom URL pattern, return synthetic Response
    const sinceMatch = /^\/__since\/(\d+)$/.exec(url.pathname);
    if (sinceMatch != null) {
      const timestampString = sinceMatch[1];
      const timestamp = parseInt(timestampString, 10);
      return new Response(
        toRelativeTimeSince(timestamp), // This function builds a relative date
        {
          headers: { 'Content-Type': 'text/plain', },
          status: 200,
        }
      );
    }

    // For all other esi:include tags, add the backend and call the global fetch
    return fetch(input, { ...init, backend: 'origin_0' });
  }
});

Now, when the processor encounters the example snippet above, it will emit a result similar to the following (depending on how many days into the future you run it):

<h1>This document was written 22d ago.</h1>

Because the backend document is cacheable by Fastly, future requests can benefit from a cache HIT, while the processing will continue to display the updated relative time.

For a live example of this, view the following fiddle:

fiddle.fastly.dev

Take it for a spin!

@fastly/esi is now available on npm, ready to be added to any JavaScript program. Use it at the edge in your Fastly Compute programs, of course, but in fact, it even works outside of Compute, so long as your environment supports the fetch API. The full source code is available on GitHub.

Get started by cloning either of the Fiddles above and testing them out with your own origins, even before you have created a Fastly account. When you’re ready to publish your service on our global network, you can sign up for a free trial of Compute and then get started right away with the ESI library on npm.

With Compute, the edge is programmable and modular – choose and combine the solutions that work best for you, or even build your own. We aren’t the only ones who can provide modules like this for Compute. Anyone can contribute to the ecosystem and take from it. And, as always, meet us at the Fastly community forum and let us know what you’ve been building!

Test your Compute apps end-to-end with JavaScript

Katsuyuki Omuro — Mon, 29 Jan 2024 02:45:27 +0000

Automated testing is a vital part of modern application development, and applications built for the edge on Fastly’s Compute platform are no exception. Today, developers can run tests for their Compute applications with custom shell scripts, but we wanted a more convenient and natural way for this to be done. Our new Compute Application Testing library allows you to use JavaScript to write your tests.

This new library makes writing a new test as easy as:

describe('/user.json', () => {
  it('returns 200 status and valid username', async () => {
    const resp = await app.fetch('/user.json');
    assert.strictEqual(resp.status, 200);
    const data = await resp.json();
    assert.ok(/^\w+$/.test(data.username));
  });
});

In this post, we'll compare testing via shell script and the new Compute Application Testing library so you can choose the best way to test your code, regardless of the programming language used to write the Compute application.

Automated testing is a technique used in the software development process to prove that code works as it’s intended, and to ensure that changes made to the code will not break existing functionality. When combined with strategies such as continuous delivery, it helps developers build and deploy reliable software, enabling a team to always have a shippable, high-quality product ready.

There are a few types of testing: "Unit" testing refers to testing the smallest building blocks of your software in isolation, often at the function, class, or API level. "Integration" tests check the interactions between these various units that make up the software. Finally, "end-to-end" testing refers to a type of test that is applied against an entire application, checking that specified inputs produce an expected output.

Testing at all of these levels is important. In this post, we cover end-to-end testing, which is one effective way to ensure that your Fastly Compute application continues to produce an expected set of outputs.

How can we test Compute applications end-to-end?

Fastly Compute is a platform that executes WebAssembly modules across our global network of edge servers, compiled from a language of your choice, such as Rust, Go, or JavaScript. For development and testing, Fastly provides a local testing environment for Compute.

What does an end-to-end test look like for an application running on Fastly Compute? Because Compute applications are served as HTTP APIs, one way to accomplish this would be a GitHub actions workflow that starts the Compute application in the testing environment and then executes a shell script which runs cURL commands:

.github/workflows/tests.yaml (excerpt)

jobs:
  curl-test:
    name: Build Compute Edge service, and test with curl
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
      - name: Set up Fastly CLI
        uses: fastly/compute-actions/setup@main
      - name: Install Edge code dependencies
        run: npm install
      - name: Build and start Compute application
        run: fastly compute serve > ./out.txt & (tail -f ./out.txt &) | grep -qF 'Listening on http://127.0.0.1:7676'
      - name: Run tests
        run: ./curl-tests/test.sh

./curl-tests/test.sh

#! /bin/bash

echo "test: returns 200 and the text \"Hello, World!\" for /"
OUTPUT=$(curl -vs "http://127.0.0.1:7676/" 2>&1)
grep -qF "200 OK" <<< "$OUTPUT" || { echo 'status not 200' ; exit 1; }
grep -qF "Hello, World!" <<< "$OUTPUT" || { echo 'unexpected response content' ; exit 1; }

echo "test: returns 200 and json including \"newField\": \"newValue\" for /json"
OUTPUT=$(curl -vs "http://127.0.0.1:7676/json" 2>&1)
grep -qF "200 OK" <<< "$OUTPUT" || { echo 'status not 200' ; exit 1; }
grep -qF "\"newField\":\"newValue\"" <<< "$OUTPUT" || { echo 'unexpected response content' ; exit 1; }

Although we have to perform a little bit of text handling in shell scripts, these tests ensure that changes to the program will continue to emit the expected output.

Tests written in JavaScript

However, many programming languages, platforms, and communities offer better options, like utilizing frameworks designed specifically for writing and executing tests.

We wanted this same functionality for Fastly Compute too, with the ability to write simple tests for a Fastly Compute service like this:

  it('returns 200 and the text "Hello, World!" for /', async () => {
    const resp = await app.fetch('/');
    assert.strictEqual(resp.status, 200);
    assert.ok((await resp.text()).includes('Hello, World!'));
  });
  it('returns 200 and json including "newField": "newValue" for /json', async () => {
    const resp = await app.fetch('/json');
    assert.strictEqual(resp.status, 200);

    const responseJson = await resp.json();
    assert.strictEqual(responseJson['data']?.['newField'], 'newValue');
  });

This is why we built Compute Application Testing for JavaScript, a library designed specifically for this purpose.

NOTE: End-to-end tests only work with the inputs and outputs of a program. Therefore, the tests and the Compute app that they apply to can be written in the same or different languages. This library allows you to specifically use JavaScript to write end-to-end tests against your Compute application.

JavaScript is everywhere and super popular. JavaScript offers great support for making web requests, natively parsing JSON, utilities such as regular expressions, access to data structures such as objects and arrays, and the ability to work with an extensive package library available on npm. Because of these capabilities, it just felt natural to write end-to-end tests using JavaScript. And since we’re just checking the inputs and outputs, we can do this regardless of the language of the Compute application.

Compute Application Testing for JavaScript is a JavaScript library, available on npm as @fastly/compute-testing. Your test application will be running in Node.js, so you’ll want to make a test application separate from your Compute application. There, you can add it as a development dependency:

npm install --save-dev @fastly/compute-testing

Now, let’s take a look at what an individual test would look like.

  it('returns 200 and the text "Hello, World!" for /', async () => {
    const resp = await app.fetch('/');
    assert.strictEqual(resp.status, 200);
    assert.ok((await resp.text()).includes('Hello, World!'));
  });

If you’re familiar with the standard Node.js test runner, or a BDD-style runner such as Jest, this should look familiar to you. The test case has the name returns 200 and the text "Hello, World!" for /. It uses the variable "app" to make a call to the '/' path of the Compute application. It then makes assertions on the status code and the text content of the response.

What is the variable "app", you may be asking? It’s an instance of ComputeApplication, a class that allows you to instantiate your Compute application in the local test environment. The variable represents an instance of the Compute application, and it’s used like this:

import { ComputeApplication } from '@fastly/compute-testing';

describe('Edge app', () => {

  const app = new ComputeApplication();

  before(async () => {
    await app.start({
      // Set 'appRoot' to the directory in which to start the app.  This is usually
      // the directory that contains the 'fastly.toml' file.
      appRoot: path.join(__dirname, '..'),
    });
  });

  after(async() => {
    await app.shutdown();
  });

  // ...tests here

});

When the class is instantiated, it calls out to the Fastly CLI to spawn an instance of your Compute application at appRoot. Once it’s running, your tests will be able to make requests to it—simply call .fetch() on it. It takes the same parameters as the global fetch function, so you can pass a URL object, a string, or a Request object as its first parameter, and set headers as you need—and you will receive back a Response object, which you can test for its status, headers, and contents. And because it’s a Response, you can also use its other useful features, such as built-in JSON deserialization:

  it('returns 200 and json including "newField": "newValue" for /json', async () => {
    const resp = await app.fetch('/json');
    assert.strictEqual(resp.status, 200);

    const responseJson = await resp.json();
    assert.strictEqual(responseJson['data']?.['newField'], 'newValue');
  });

There are plenty of other JavaScript features that are available to you to write expressive tests as well. For example, use Request to send JSON, form data (using FormData), and streaming blobs. And because you get back a Response object, you’re able to access native streaming and JSON parsing, which are useful for checking HTTP responses.

Of course, using Node.js also opens you to all of the packages available on npm: If you need to parse an HTML DOM, you can look to JSDOM. Do you need to work with a JSON Web Token (JWT)? Look no further than jsonwebtoken. In this post we’re using Node.js's test runner along with Node.js's assertions, but do you prefer testing with Jest, Mocha, or Chai? These are all available too. Whatever intent your test needs to express, writing your tests in JavaScript for Node.js will help you do that.

Now, running these tests can be done with a GitHub workflow like this:

.github/workflows/tests.yaml (excerpt)

jobs:
  compute-testing-test:
    name: Test Compute Edge service using compute-testing
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
      - name: Set up Fastly CLI
        uses: fastly/compute-actions/setup@main
      - name: Install Edge code dependencies
        run: npm install
      - name: Install Test code dependencies
        working-directory: ./test
        run: npm install
      - name: Run tests
        working-directory: ./test
        run: npm test

Triggering this workflow results in this neat format that gives us access to test names and some stats:

If you’d like to take a closer look at the code and tests in this example, they are available on my GitHub at https://github.com/harmony7/compute-testing-demo.

Try it on your own code

Using JavaScript to write tests is now a great alternative to using scripts. Compute Application Testing for JavaScript is available on npm for you to try right away. See how easy it is to build and run tests against your Compute application, and to add them to your CI tests.

NOTE: @fastly/compute-testing is provided as a Fastly Labs product. Visit the Fastly Labs website for terms of use.

For more information and examples, be sure to check out our project page on GitHub.

At Fastly, we strive to provide the tools that give you the power to run more code at the Edge and develop for it with the tools you know and love. We love to hear about it when our users get the most out of these tools. Join us on the Fastly community forum and let us know what you’ve been building!

Host your Remix app on Fastly Compute

Katsuyuki Omuro — Thu, 02 Mar 2023 02:08:51 +0000

Remix is a popular, modern JavaScript-based full stack web framework that allows the developer to focus on the user interface and work with web standards, in order to deliver user experiences that are responsive and robust. With our new remix-compute-js libraries, you can now host your Remix application on our Compute platform, allowing you to serve at our world-wide edge network — you don't even need an origin server.

As our support for JavaScript on Compute grows, we are increasingly able to offer more integrations to work with existing JavaScript libraries and frameworks. We talked about serving static websites entirely at the edge earlier this year, and more recently, running your Next.js site at the edge. And today, we’d like to share with you some work we’ve done to support running Remix.

Remix is a popular JavaScript-based full stack web framework with an emphasis on web standards and progressive enhancement. It’s a modern framework that fully embraces the Fetch API interfaces, making it a great fit for Compute, which does the same. And best of all, Remix has a bring-your-own-runtime design, written from the ground up to work with various server runtimes and server adapters, so that it can run on a multitude of platforms.

As a result we’ve been able to build a Remix runtime, an entry point adapter, and a project template to give you full support to target Compute as an environment to run Remix.

You now have the full power of Remix available to your Compute application, with its rich support of Web Standards and progressive enhancement. You’re free to build your Remix project as you wish, using its handy features: defining convention-based routing, harnessing the power of React Router, rendering MDX, and building API Routes.

And of course, you can take advantage of Compute features too, such as making fetch calls to backends, or using polyfills to integrate with compatible modules available from NPM.

Create your Remix project

A template for Fastly Compute exists on GitHub at https://github.com/fastly/remix-compute-js/tree/main/packages/remix-template. This means you just need Node.js installed locally, and then you can create a Remix project by using the official create-remix command-line tool:

npx create-remix@latest ./my-app --template https://github.com/fastly/remix-compute-js/tree/main/packages/remix-template

You’ll be asked if you want to create your project using JavaScript or TypeScript (my personal preference is TypeScript!). The rest of the process will happen automatically.

If you switch to the ./my-app directory, you’ll see that you’ll have a project structure built out. In addition to being a Remix project, it will also be a Compute JavaScript application complete with a fastly.toml file that describes your application to Fastly, and an entry point at src/index.js.

Your application is preconfigured to work on Fastly’s Development Server, which will be available just by having the Fastly CLI installed. Simply run the following command:

npm run dev

Open up http://127.0.0.1:7676 in your web browser, and you will see the Remix template application showing up.

This file is built from the app/routes/index.jsx file (.tsx if you’re using TypeScript!). You can go ahead and make changes to this file, and you’ll see that your application will be rebuilt, and your browser window will refresh automatically.

There are actually two processes running here: Remix’s compiler and Fastly’s development server, both running in watch mode. Whenever you make changes to files in the app/ directory, the Remix compiler will trigger a rebuild, causing output files to update in the build/ and public/build/ directories. Whenever this happens, or whenever you update files in the public/ directory, Fastly’s development server will rebuild. In effect, you now have a self-refreshing development environment for your Remix application running on Compute.

The server adapter

Remix’s powerful architecture keeps two concerns separate: the Remix application itself, which is your code written within the Remix framework; and the interface between Remix and the server platform. This provides for flexibility in how the server platform interfaces with Remix - great news for platform providers like us (thanks Remix team!).

The simplest usage, which is also the one implemented in the project template, is to use the createEventHandler function Fastly exports from the server adapter package. It expects staticAssets, imported from the ./statics file that is generated by the Static Publisher (also installed automatically when using the template):

import { createEventHandler } from "@fastly/remix-server-adapter";
import { staticAssets } from "./statics";

addEventListener("fetch", createEventHandler({ staticAssets }));

But if you have a case where you want more granular control over the ServerBuild module to use with Remix, or how to handle requests for static assets, we also provide lower-level functions to help you do that:

import { createRequestHandler, handleAsset } from "@fastly/remix-server-adapter";
import { staticAssets } from "./statics";

const build = staticAssets.getAsset("/build/index.js").module;  
const requestHandler = createRequestHandler({build});  

addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));  
async function handleRequest(event) {  
  let response = await handleAsset(event, staticAssets);  
  if (!response) {  
    response = requestHandler(event);  
  }  
  return response;  
}

Going Live

When you're ready to ship, create a production build and view your site to make sure that it runs well.

Stop the development server, then run the following commands:

npm run build
npm start

This generates a production build of your application, generating optimized JavaScript files. Then refresh your browser to see the production-build version of your app running in the development server (live reloading is not available in production builds).

Once you’ve seen that the production build of your site looks good, you're ready to deploy to Fastly. If you don't already have an account, start by creating one and then configure Fastly CLI with your new account credentials. Once that's done, you can deploy your app to your Fastly account:

npm run build
npm run deploy

You'll be prompted to create a new Fastly service. If you want to use an existing service, modify fastly.toml and set the service_id value to your service ID before running the commands above.

And that’s really all there is to using Remix on Compute: Develop as normal using npm run dev. Test with npm run build and npm start, and when you’re ready to go to production, deploy to the edge with npm run build and npm run deploy.

Already have a Remix application? Let’s bring it to Compute

Do you already have a Remix application that you’ve started? Perhaps one already hosted on a Node.js backend? So long as your project doesn’t attempt to do something that isn’t conceptually impossible on Fastly, such as trying to interact with the filesystem, it’s usually not too hard to adapt the application to work on Compute.

The easiest way to do this is to create an empty Remix project using the template above. That way, all of the dependencies will be installed for you, and the server adapter will be created as part of the process as well. Install into your new project any dependency packages referenced by your original project. Then, move your existing project’s files into your new project. In Remix, your application’s files are found in app/ and public/. For most of the files in these directories, you can usually simply copy them into your new project, keeping the following points in mind.

Some of the source files will reference Remix runtime packages such as @remix-run/node, @remix-run/cloudflare, or @remix-run/deno. Modify these references to @fastly/remix-server-runtime.

For example, you may have the following:
```
import { json } from "@remix-run/node";
```
You’ll want to change this to:
```
import { json } from "@fastly/remix-server-runtime";
```
For entry.client.tsx, entry.server.tsx, and root.tsx in the app/ directory, you’ll generally want to start with the ones found in the new project. Examine these files in your source project. Look for any changes that you had made to them in your source project, and then make the equivalent changes in the new project as necessary.
Skip /public/build/. This is a directory that is generated during the build step.
Depending on the dependencies used by your project, you may need to add polyfills to run in Compute.

And that’s all there is to it! Build and deploy your application to the edge as we did in the previous section.

Your Remix application, now on Compute

The integration between Remix and Compute is here – you can now host your Remix application entirely at the edge, without even needing an origin server. Benefit from the robust architecture of Remix, and then go to Compute to run your app on thousands of servers across Fastly's network.

At Fastly, we strive to provide the tools that give you the power to run more code at the Edge and develop for it with the tools you know and love. We love to hear it when our users get the most out of these tools. Reach out to us on Twitter and let us know what you’ve been building!

Supercharge your API with realtime push powers using Fastly Fanout

Katsuyuki Omuro — Tue, 22 Nov 2022 08:01:46 +0000

More than ever before, users expect applications and websites to be “realtime”—to see new information as soon as it becomes available on the server side, without needing to ask for a refresh. Fastly Fanout is here to augment your API with the power of realtime push, enabling you to power these applications using your existing HTTP origin instead of needing to maintain a complicated and dedicated messaging infrastructure.

Realtime is the thing these days. Users are in a world where websites and apps constantly show updated data in a dynamic and interactive way. Your website users need to see the newest chat message, the newest stock price, and the newest in-stock item—and they need to see these updates right now, without needing to request a refresh.

Realtime apps need realtime APIs

APIs are the future of the world. We already live in a world where you can shorten a URL, translate text into various languages, get social media updates, and even order stuff from retailers and control the lights in your house, all using web APIs. As demand for realtime web applications continues to grow, it only makes sense that support for realtime push in APIs will become essential to meet this need.

At first glance, the requirements of realtime push seem to be at odds with the traditional “one-request, one-response” model of HTTP messaging. However, by utilizing long-lived TCP connections, realtime APIs can and do exist. For example, Twitter’s streaming endpoint is such an API. With HTTP streaming, the response from the server is sent without a Content-Length header, and instead uses Transfer-Encoding: chunked. The response stays open forever, and the server continues to append to the response as data becomes ready on the server.

GET /1.1/statuses/simple.json HTTP 1.1
Host: stream.twitter.com
Authorization: OAuth [...]

HTTP/1.1 200 OK
connection: close
content-type: application/json
date: Wed, 19 Oct 2022 00:32:07 GMT
server: tsa
transfer-encoding: chunked
x-connection-hash: 6028cbda...6f0443a6

{"created_at": "Wed Oct 19 00:32:06 +0000 2022", "id": 588862464202297345, "text": "tweet 1", ... }
{"created_at": "Wed Oct 19 00:32:07 +0000 2022", "id": 588862468392255488, "text": "tweet 2", ... }

... (ad infinitum)

Twitter’s streaming API hangs open after the request and adds data about tweets to the end of the response as they become ready.

Streaming HTTP responses are arguably a hack that subverts the conventional one-request, one-response model that HTTP was designed to serve. It’s also the underlying mechanism of the popular Server-Sent Events technology, supported by all modern browsers.

HTTP long-polling is another common technique, used for example by Facebook until very recently for its chat platform, where the server’s response hangs open only until the next "event" happens or a timeout period passes. At that point the server responds and ends the connection. The client then initiates another request right away, waiting for the next event. This effectively creates a data channel for the server to send push updates, but in a way that uses HTTP more conventionally:

Avoiding the use of HTTP protocols may be an option as well. Recently, for example, WebSocket support can be found in all modern browsers, which does away with the creative use of HTTP and adds support for messages to flow in both directions. HTTP techniques are still handy though, so we'll focus on those in this post, and will cover WebSockets in the next post.

So how can we implement an HTTP API to support realtime push?

Implementing a realtime API

There are lots of off-the-shelf components that are designed to push data from the server to the client, like Ably, Firebase, and Pusher. While these are all fine solutions for their use case, they tend to be end-to-end, that is, they are hosted solutions, or they provide a server library to use on your stack. They may use some private protocol and sometimes they require the use of their client SDKs. These may, indeed, be the product of choice if you’re using it to build an entire application stack yourself and don’t plan to expose your APIs publicly.

However, if it’s an API that you’re trying to offer, this is not the best strategy for you. You need control over your API surface. You want to speak HTTP directly and perhaps even document the API using tools such as OpenAPI, rather than require the use of a specific SDK.

Of course, you can go ahead and roll your own stack, but that often means maintaining a complicated and dedicated messaging infrastructure. And with all these long-lived connections, the problem of server resources is one you’ll need to tackle, not to mention scalability as demand for your product increases. If you’re Twitter or Facebook, you may have the resources to build such a project and maintain it, but even if you do, it often ends up not being very CDN-friendly, as you’ll still have to handle the traffic at your origin.

With realtime becoming an imminent need worldwide, it was clear that we needed a better solution for APIs.

The realtime solution for APIs: Fastly Fanout

Earlier this year, Fastly announced that Fanout (https://fanout.io) would be joining Fastly, and that we would be offering Fanout as a product. I actually joined Fastly as part of that acquisition, and now that we've wired it all up, I can show you how to use Fanout with a Fastly service.

Under the hood, Fastly Fanout is based on Pushpin, an open source project that Fanout started (and is still under active development).

Fanout runs on Fastly's edge servers across our global network and forwards requests to your origin that serves your API. It’s your API, so you get full control over its API surface, and we don’t require your users to use a specific server or client SDK. It runs at the edge, so it solves the problems with persistent connections and with scalability of origin traffic. And it supports HTTP streaming (e.g., Server-Sent Events), HTTP long-polling, and WebSocket connections (more on WebSocket in the next article).

But more fundamentally, Fanout has a different design philosophy to other push services, which makes it really great for building APIs. Not only did we want to give you full control over your API, we wanted to use standard, interoperable components. We also wanted to make sure our solution maintained the proper separation of concerns on your team.

Suppose your API design team has defined a realtime API at /stream. Then you have engineer roles build the backend (and perhaps the frontend too), as well as operation roles who decide on things like your infrastructure and caching.

As Fastly Fanout, we enter this diagram in the middle like this:

This architecture allows you to keep your original API design. Fanout handles the long-lived connections and the publishing of data, and lets the origin focus on the business logic. Your API consumers don’t even need awareness of Fanout.

It also frees you from technological and vendor lock-in. As all of these components are standard and interoperable, you’re free to:

make API design changes as you wish
make engineering decisions, such as to switch your origin's programming language or framework, or to switch database engines
make operations decisions, like moving your origin to a cloud provider, or switching from Fastly Fanout to running Pushpin on-prem

The off-the-shelf, end-to-end solutions we mentioned earlier would have encroached on every layer here, but Fanout’s design allows for each of the concerns to stay with their respective roles.

This is all possible because we define the backend interaction with Fanout to use an open integration protocol. We call this protocol GRIP (Generic Realtime Intermediary Protocol), which we publish as an open standard for anyone to implement. Fastly Fanout is simply one such implementation. Fastly and Fanout have always been dedicated to open-source and open standards, and our common stance here is one of the reasons we have always gotten along so well! Fastly will continue to support both Pushpin and GRIP.

This architecture is truly empowering! Because Fanout runs at the edge, realtime activity can happen at any of our numerous POPs nearest the user.

We take on all of the heavy lifting of holding your long-lived connections around the world and publishing messages to individual clients, so your origin doesn’t have to. We free you from the scalability issues of having to sustain numerous connections, as well as from the burden of having to maintain a complex messaging infrastructure.

Enabling Fanout

Fanout is a feature of Fastly that can be enabled per service. Once it’s enabled for your service, handle the request in Compute@Edge, and call req.handoff_fanout("backend") for each request that you wish to pass through the Fanout proxy to your backend (Supported in Rust programs for now, other languages coming soon). This design gives you flexibility and granular control over which requests you wish to handle with Fanout.

If you simply want to pass all requests through Fanout, then we have a Fanout forward starter kit that you can use. Obtain the Fastly CLI, and create a Compute@Edge project using the starter kit as follows, and put it in front of your origin server. See Compute@Edge Starter Kits for more information.

$ mkdir my-project
$ cd my-project
$ fastly compute init --from=https://github.com/fastly/compute-starter-kit-rust-fanout-forward

Realtime response lifecycle with GRIP

As mentioned earlier, Fanout and your origin interact using GRIP. When a client makes a request through the Fanout proxy, Fanout forwards it to the origin.

The origin response is what makes Fanout interesting. The origin is free to make a runtime decision about whether the response should use realtime push. Of course it may elect to always use realtime, but it can, for example, check a query parameter, an Accept header, or for any condition you wish. The origin uses GRIP to indicate to the proxy what to do (such as to hold the response as HTTP streaming, and to subscribe the connection to channels foo and bar), and may also provide an initial payload depending on the circumstances. After that, the origin is free to drop this connection, and if the GRIP instruction contains a hold, Fanout will now hold that connection open.

You may be wondering how complicated this GRIP is. It’s actually super simple:

HTTP/1.1 200 OK
Content-Type: text/plain
Grip-Hold: stream
Grip-Channel: foo, bar

[start stream]

The bolded HTTP headers above are the instructions that instruct Fanout to hold the response as HTTP streaming, and to subscribe the connection to channels foo and bar.

If you call this endpoint now, you’ll see the following, and the response will hang open.

$ curl https://your-service-name.edgecompute.app/stream
[start stream]
(response hangs)

At any later time, when the origin is ready to publish a message to one of these channels, it can signal to the proxy using a GRIP Push:

This is done by making an HTTP POST to the GRIP publishing endpoint:

POST /service/ABCDEFGHI0123456789/publish/ HTTP/1.1
Host: api.fastly.com
Fastly-Key: YOUR_FASTLY_KEY
Content-Type: application/json

{
  "items": [
    {
      "channel": "foo",
      "formats": {
        "http-stream": {
          "content": "hello\n"
        }
      }
    }
  ]
}

On Fastly Fanout, the publishing endpoint is at api.fastly.com/service/<service-id>/publish/. Make a POST to it using your Fastly Service ID, and provide a Fastly API token that has the publish scope for your service. The endpoint accepts up to 64kb of POST data per call, and we accept an array of items, so that you can publish multiple items at once. Each item must specify the channel (foo in this example) as well as the data.

The data is provided as a keyed object, and we allow the data to be specified in any number of formats. This example is for the http-stream format (HTTP streaming), but we also support http-response (HTTP long-polling) and ws-message (WebSocket). This design allows various clients to listen on different transports for updates on the same channel.

Performing the publish shown above would insert the following bolded line into the output stream of our example stream, and the response will again continue to hang.

$ curl https://your-service-name.edgecompute.app/stream
[start stream]
hello
(response hangs)

Example: Adding realtime to an API endpoint

Now that we’ve talked about how Fanout works, it’s a great opportunity to show how it can be used to take an existing API endpoint and add realtime powers.

Imagine an example API that represents a counter, identified by an ID. You can get the current value of a counter by calling it with the GET method, and you can increment it by calling with the POST method. This is implemented using the following PHP code:

if (preg_match('#^/counter/(\d+)/?#', $_SERVER['REQUEST_URI'], $matches)) {
  $counter_id = $matches[1];
  if ($_SERVER['REQUEST_METHOD'] === 'GET') {
    $value = getCounterValue($counter_id);
    echo json_encode(['value' => $value]) . "\n";
    die;
  }
  if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $value = incrementCounter($counter_id);
    echo json_encode(['value' => $value]) . "\n";
    die;
  }
}

We’ll put Fastly Fanout in front of it, and then we can invoke it like this:

$ curl https://fastly-fanout-blog.edgecompute.app/counter/1
{"value": 1}
$ curl -X POST https://fastly-fanout-blog.edgecompute.app/counter/1
{"value": 2}
$ curl https://fastly-fanout-blog.edgecompute.app/counter/1
{"value": 2}
$

Now let’s add realtime to this GET endpoint. As discussed earlier, Fanout lets us do this conditionally. So this time, let’s check for the existence of an Accept header with the value text/event-stream. In that case we use GRIP to ask Fanout to hold an HTTP stream open and subscribe the connection to a channel named after the counter’s ID:

  if ($_SERVER['REQUEST_METHOD'] === 'GET') {
    $value = getCounterValue($counter_id);

    // -- Start of new code
    if ($_SERVER['HTTP_ACCEPT'] === 'text/event-stream') {
      header('Content-Type: text/event-stream');
      header('Grip-Hold: stream');
      header('Grip-Channel: counter-' . $counter_id);
      echo 'data: ' . json_encode(['value' => $value]) . "\n\n";
      die;
    }
    // -- End of new code

    echo json_encode(['value' => $value]) . "\n";
    die;
  }

This is what happens if we call this endpoint now. Note that if we call it with the Accept: text/event-stream header, we see the “data” prefix and the response will hang open.

% curl https://fastly-fanout-blog.edgecompute.app/counter/1
{"value": 2}
% curl -H "Accept: text/event-stream" https://fastly-fanout-blog.edgecompute.app/counter/1
data: {"value": 2}
(response hangs)

We’ll add publishing to our POST endpoint now. In the code that handles POST, we build the data structure for publishing, and send it to the GRIP publishing endpoint.

  if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $value = incrementCounter($counter_id);

    // -- Start of new code
    $headers = [
      'Fastly-Key: ' . getenv('FASTLY_KEY'),
      'Content-Type: application/json',
    ];
    $content = [
      'items' => [
        [
          'channel' => 'counter-' . $counter_id,
          'formats' => [
            'http-stream' => [
              'content' => 'data: ' . json_encode(['value' => $value]) . "\n\n",
            ],
          ],
        ],
      ]
    ]; 
    $context = stream_context_create([
      'http' => [
        'method' => 'POST',
        'header' => join("\n", $headers),
        'content' => json_encode($content),
      ]
    ]);
    file_get_contents(
      'https://api.fastly.com/service/' . getenv('FASTLY_SERVICE_ID') . '/publish/',
      false,
      $context
    );    
    // -- End of new code

    echo json_encode(['value' => $value]) . "\n";
    die;
  }

Let’s try calling this! It’s best to leave the previous request hanging, and use a new terminal window.

$ curl -X POST https://fastly-fanout-blog.edgecompute.app/counter/1
{"value": 3}
$ curl -X POST https://fastly-fanout-blog.edgecompute.app/counter/1
{"value": 4}
$

The updates stream through to the first window (new lines bolded):

$ curl -H "Accept: text/event-stream" https://fastly-fanout-blog.edgecompute.app/counter/1
data: {"value": 2}

data: {"value": 3}

data: {"value": 4}

(response hangs)

So there we have it! We’ve used GRIP to add realtime to an API by expanding on the existing origin code. This was done in a PHP codebase—a language that we’d usually never expect to be doing realtime. With Fanout, we’re able to do this without needing to hold our own connections, without needing to build a messaging architecture, using an API that we’ve defined, using all standard components, all standard protocols, and an open standard, GRIP, to tie it all together.

Check out the code for this example, available for viewing on Glitch at https://glitch.com/edit/#!/fanout-blog-demo, and behind Fanout at https://fastly-fanout-blog.edgecompute.app/.

Conclusion

As more of the world demands apps that update in real time, your web APIs need realtime push as well. Fastly Fanout is here to help you add realtime push to your APIs, allowing you to leverage your existing HTTP origin and design principles, while also relieving you from having to sustain numerous connections and having to maintain a complex messaging infrastructure.

We’re certain that this opens a new world of possibility and we can’t wait to see what you’ll be creating with your new realtime powers. Try it out and let us know what you think.

Additional reading

Fanout on Fastly Developer Hub 
https://developer.fastly.com/learning/concepts/real-time-messaging/fanout

Fanout Documentation 
https://docs.fanout.io/

Pushpin - Open Source GRIP Proxy
 https://pushpin.org/

Pushpin on GitHub
https://github.com/fanout/pushpin

GRIP - Generic Realtime Intermediary Protocol 
https://pushpin.org/docs/protocols/grip/