prpl-server

An HTTP server for Node designed to serve PRPL apps in production.

Contents

• Usage
  • As a binary
  • As a library
• Differential Serving
  • Builds
  • Capabilities
• Entrypoint
• Base paths
• HTTP/2 Server Push
  • Push manifest
  • Link preload headers
  • Testing push locally
• Service Workers
  • Scope header
  • 404 handling
• HTTPS
• Caching
• HTTP Errors
• Rendering for Bots
• Google App Engine Quickstart

Usage

As a binary

$ npm install -g prpl-server
$ prpl-server --root . --config polymer.json

As a library

$ npm install --save prpl-server

prpl = require('prpl-server');
express = require('express');

const app = express();
app.get('/api/launch', (req, res, next) => res.send('boom'));
app.get('/*', prpl.makeHandler('.', {
  builds: [
    {name: 'modern', browserCapabilities: ['es2015', 'push']},
    {name: 'fallback'},
  ],
}));
app.listen(8080);

Differential Serving

Modern browsers offer great features that improve performance, but most applications need to support older browsers too. prpl-server can serve different versions of your application to different browsers by detecting browser capabilities using the user-agent header.

Builds

prpl-server understands the notion of a build, a variant of your application optimized for a particular set of browser capabilities.

Builds are specified in a JSON configuration file. This format is compatible with

polymer.json

polymer.json

--config

In this example we define two builds, one for modern browsers that support ES2015 and HTTP/2 Push, and a fallback build for other browsers:

{
  "entrypoint": "index.html",
  "builds": [
    {"name": "modern", "browserCapabilities": ["es2015", "push"]},
    {"name": "fallback"}
  ]
}

Capabilities

The

browserCapabilities

You should always include a fallback build with no capability requirements. If you don't, prpl-server will warn at startup, and will return a 500 error on entrypoint requests to browsers for which no build can be served.

The following keywords are supported. See also the browser-capabilities library which prpl-server uses.

| Keyword | Description | :---- | :---- | push | HTTP/2 Server Push | serviceworker | Service Worker API | modules | JavaScript Modules (including dynamic

import()

import.meta

Entrypoint

In the PRPL pattern, the entrypoint is a small HTML file that acts as the application bootstrap.

prpl-server will serve the entrypoint from the best compatible build from

/

prpl-server expects that each build subdirectory contains its own entrypoint file. By default it is

index.html

entrypoint

Note that because the entrypoint is served from many URLs, and varies by user-agent, cache hits for the entrypoint will be minimal, so it should be kept as small as possible.

Base paths

Since prpl-server serves resources from build subdirectories, your application source can't know the absolute URLs of build-specific resources upfront.

For most documents in your application, the solution is to use relative URLs to refer to other resources in the build, and absolute URLs to refer to resources outside of the build (e.g. static assets, APIs). However, since the entrypoint is served from URLs that do not match its location in the build tree, relative URLs will not resolve correctly.

The solution we recommend is to place a

If you are using polymer-cli, set

{"autoBasePath": true}

polymer.json

Note that

HTTP/2 Server Push

Server Push allows an HTTP/2 server to preemptively send additional resources alongside a response. This can improve latency by eliminating subsequent round-trips for dependencies such as scripts, CSS, and HTML imports.

Push manifest

prpl-server looks for a file called

push-manifest.json

Each key in the push manifest is a regular expression pattern that will be matched against the incoming request path. Patterns are forced to match exactly (e.g.

foo.html

^foo.html$

/articles/.*

index.html

Resources in the push manifest can be specified as absolute or relative paths. Absolute paths are interpreted relative to the server root directory. Relative paths are interpreted relative to the location of the push manifest file itself (i.e. the build subdirectory), so that they do not need to know which build subdirectory they are being served from. Push manifests generated by

polymer-cli

Link preload headers

prpl-server is designed to be used behind an HTTP/2 reverse proxy, and currently does not generate push responses itself. Instead it sets preload link headers, which are intercepted by cooperating reverse proxy servers and upgraded into push responses. Servers that implement this upgrading behavior include Apache, nghttpx, and Google App Engine.

If a build with a push manifest is served to a browser that does not support push according to the browser-capabilities support matrix, then a

nopush

Testing push locally

To confirm your push manifest is working during local development, you can look for

Link: ; rel=preload

To see genuine push locally, you will need to run a local HTTP/2 reverse proxy such as nghttpx:

• Install nghttpx (Homebrew, Ubuntu, source).
• Generate a self-signed TLS certificate, e.g.

  openssl req -newkey rsa:2048 -x509 -nodes -keyout server.key -out server.crt

• Start prpl-server (assuming default

  127.0.0.1:8080

  ).
• Start nghttpx:

  nghttpx -f127.0.0.1,8443 -b127.0.0.1,8080 server.key server.crt --no-ocsp

• Visit

  https://localhost:8443

  . In Chrome, Push responses will show up in the Network tab as Initiator: Push / Other.

Note that Chrome will not allow a service worker to be registered over HTTPS with a self-signed certificate. You can enable chrome://flags/#allow-insecure-localhost to bypass this check. See this page for more tips on developing service workers in Chrome.

Service Workers

Scope header

prpl-server sets the

Service-Worker-Allowed

/

service-worker.js

register('service-worker.js', {scope: '/'})

404 handling

prpl-server automatically serves a tiny self-unregistering service worker for any request path ending with

service-worker.js

404 Not Found

unregisterMissingServiceWorkers: false

This can be useful when the location of a service worker has changed, as it will prevent clients from getting stuck with an old service worker indefinitely.

This problem arises because when a service worker updates, a

404

HTTPS

Your apps should always be served over HTTPS. It protects your user's data, and is required for features like service workers and HTTP/2.

If the

--https-redirect

301 Moved Permanently

https://

prpl-server trusts

X-Forwarded-Proto

X-Forwarded-Host

X-Forwarded-*

You should always use

--https-redirect

Caching

By default, prpl-server sets the

Cache-Control

max-age=60

max-age=0

ETag

To change this default for non-entrypoint resources, set the

cacheControl

--cache-control

Cache-Control

--cache-control=no-cache

For more advanced caching behavior, use prpl-server as a library with Express and register a middleware that sets the

Cache-Control

Cache-Control

app.get('/images/*', (req, res, next) => {
  res.setHeader('Cache-Control', 'public, max-age=31536000');
  next();
});

app.get('/*', prpl.makeHandler('.', config))

Choosing the right cache headers for your application can be complex. See Caching best practices & max-age gotchas for one starting point.

HTTP Errors

By default, if a

404 Not Found

text/plain

forwardErrors: true

app.get('/*', prpl.makeHandler('.', {
  builds: [ ... ],
  forwardErrors: true
}));

app.use((err, req, res, next) => {
  if (err.status === 404) {
    res.status(404).sendFile('my-custom-404.html', {root: rootDir});
  } else {
    next();
  }
});

Rendering for Bots

Many bots don't execute JavaScript when processing your application. This can cause your application to not render correctly when crawled by some search engines, social networks, and link rendering bots.

One solution to this problem is Rendertron. Rendertron is a server which runs headless Chrome to render and serialize web pages for these bots, so all the content is contained in one network request. Use the

--bot-proxy

Note that you can also use the Rendertron middleware directly if you have a custom Express server.

Google App Engine Quickstart

Google App Engine is a managed server platform that supports Node.js. You can deploy prpl-server to App Engine standard environment with a few steps:

1. Follow these instructions to set up a Google Cloud project and install the Google Cloud SDK. As instructed, run the

   gcloud init

   command to authenticate and choose your project ID.

2. cd

   to the directory you want to serve (e.g. your app's

   build/

   directory if you are using polymer-cli).

3. Run

   npm init

   and follow the prompts to create your

   package.json

   .

4. Run

   npm install --save prpl-server

   to add prpl-server as a dependency.

5. Edit your

   package.json

   to add a

   start

   script. This is the command App Engine runs when your app starts. Configure

   prpl-server

   to listen on all hosts, and to redirect HTTP connections to HTTPS. You should also specify the version of Node your app requires via the

   engines

   section.

{
  "scripts": {
    "start": "prpl-server --host 0.0.0.0 --https-redirect"
  },
  "engines": {
    "node": "8.x.x"
  }
}

1. Create an

   app.yaml

   file. This tells App Engine that you want to use Node.js in the App Engine standard environment:

runtime: nodejs8

1. Run

   gcloud app deploy

   to deploy to your App Engine project.

   gcloud

   will tell you the URL your app is being served from. For next steps, check out the Node.js in the App Engine standard environment documentation.