http2server/README.md

Simple HTTP/2 push server

# http2server
*Serve single page apps with HTTP/2 Push.*

## Installation
```
npm i -g http2server
```

## Usage
```
Usage: http2server <path> [options]

Commands:
  path  Directory to serve

Options:
  --cors        Set `Access-Control-Allow-Origin`     [boolean] [default: false]
  --max         Limit the number of pushed dependencies           [default: 100]
  -p, --port    Port to listen on                                [default: 8080]
  -C, --cert    Path to ssl cert file                      [default: "cert.pem"]
  -K, --key     Path to ssl key file                        [default: "key.pem"]
  -I, --index   HTML fallback for single page apps       [default: "index.html"]
  -s, --silent  Suppress log messages from output     [boolean] [default: false]
  -h, --help    Show help                                              [boolean]
```

## What does HTTP/2 Push do for me?

### Simpler Workflow
No more concatenating JavaScript and CSS files, splicing images into spritesheets, nor stacking icons into fonts or SVG layers.

### Faster Speed
This is the network latency holy grail. Serve all static assets using a single round trip.

## How does this work?
When a user requests your `index.html` single page app entry point, `http2server` uses HTTP/2 Push Streams to pre-emptively send the user entire directory of dependency files like CSS, JS, font, and image assets.

## And now the bad news...

### An SSL certificate is required
While the HTTP/2 specification allows unencrypted connections, web browsers strictly enforce HTTPS. A certificate and key are required to enable HTTPS. only support HTTP/2 Generate a TLS self-signed certificate.

In production use [Let's Encrypt](https://letsencrypt.org) or a paid certificate.

For development use a self-signed certificate. This command is all you need. 
```shell
openssl req -newkey rsa:2048 -new -nodes -sha256 -x509 -days 365 -keyout key.pem -out cert.pem
```

### Browsers are pretty bad at HTTP/2 Push
Turns out this feature hasn't been used much and support in browsers is lacking.

- Firefox slows down and finally chokes after about 3,800+ push streams. This is a problem when pushing, for example, and entire `node_modules` tree. A browser restart seems to be required to flush the pipes.
- Chrome only accepts the first 1,000 push streams and rejects any further. Fortunately it does accept the response body so you still see the page.
- Safari does not support HTTP/2 Push.
- Internet Explorer has not yet been tested. Help needed.

It is not easy to debug, or even verify, what happens to the pushed dependencies. The network tab shows business as usual, which is failse. Use Chrome's <chrome://net-internals#http2> to see the low level details. Notice that no requests are received by the server for subsequent assets.

### Work in progress

**Caching** and pushing of only changed dependencies. This will be a significant performance improvement over traditional file concatenation.

**Filtering** dependencies based on glob patterns or other strategies. For example only push the CSS and JS files, not the images.

**Prioritising** to send certain assets earlier on, allowing the browser to parse and partially render the page as soon as possible.

### This is an experimental learning project
If you use this in production you're gonna have a bad time.