RELEASE.md documentation and small fixes

.travis.yml

@@ -4,6 +4,7 @@ branches:
   except:
     - /^greenkeeper.*/
 node_js:
+  - 12
   - 10
   - 8
   - 6

Dockerfile

@@ -1,4 +1,5 @@
 FROM node:12.13-alpine
+# ref: https://hub.docker.com/_/node?tab=tags&name=12
 
 LABEL maintainer="Jupyter Project <[email protected]>"
 
@@ -10,6 +11,12 @@ COPY . /srv/configurable-http-proxy
 WORKDIR /srv/configurable-http-proxy
 RUN npm install -g
 
+# Switch from the root user to the nobody user
 USER 65534
 
+# Expose the proxy for traffic to be proxied (8000) and the
+# REST API where it can be configured (8001)
+EXPOSE 8000
+EXPOSE 8001
+
 ENTRYPOINT ["/srv/configurable-http-proxy/chp-docker-entrypoint"]

README.md

@@ -1,7 +1,8 @@
-# configurable-http-proxy
+# [configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy)
 
-[![Build Status](https://travis-ci.org/jupyterhub/configurable-http-proxy.svg?branch=master)](https://travis-ci.org/jupyterhub/configurable-http-proxy)
-[![npm](https://img.shields.io/npm/v/configurable-http-proxy.svg)](https://www.npmjs.com/package/configurable-http-proxy)
+[![TravisCI Build status](https://img.shields.io/travis/jupyterhub/configurable-http-proxy/master.svg?logo=travis)](https://travis-ci.org/jupyterhub/configurable-http-proxy)
+[![Docker Build status](https://img.shields.io/docker/build/jupyterhub/configurable-http-proxy?logo=docker&label=build)](https://hub.docker.com/r/jupyterhub/configurable-http-proxy/tags)
+[![npm](https://img.shields.io/npm/v/configurable-http-proxy.svg?logo=npm)](https://www.npmjs.com/package/configurable-http-proxy)
 
 **configurable-http-proxy** (CHP) provides you with a way to update and manage
 a proxy table using a command line interface or REST API.
@@ -102,11 +103,9 @@ configurable-http-proxy --default-target=http://localhost:8888
 Usage: configurable-http-proxy [options]
 
 Options:
-
   -V, --version                      output the version number
   --ip <ip-address>                  Public-facing IP of the proxy
   --port <n> (defaults to 8000)      Public-facing port of the proxy
-
   --ssl-key <keyfile>                SSL key to use, if any
   --ssl-cert <certfile>              SSL certificate to use, if any
   --ssl-ca <ca-file>                 SSL certificate authority, if any
@@ -116,21 +115,18 @@ Options:
   --ssl-ciphers <ciphers>            `:`-separated ssl cipher list. Default excludes RC4
   --ssl-allow-rc4                    Allow RC4 cipher for SSL (disabled by default)
   --ssl-dhparam <dhparam-file>       SSL Diffie-Helman Parameters pem file, if any
-
   --api-ip <ip>                      Inward-facing IP for API requests (default: "localhost")
   --api-port <n>                     Inward-facing port for API requests (defaults to --port=value+1)
   --api-ssl-key <keyfile>            SSL key to use, if any, for API requests
   --api-ssl-cert <certfile>          SSL certificate to use, if any, for API requests
   --api-ssl-ca <ca-file>             SSL certificate authority, if any, for API requests
   --api-ssl-request-cert             Request SSL certs to authenticate clients for API requests
   --api-ssl-reject-unauthorized      Reject unauthorized SSL connections (only meaningful if --api-ssl-request-cert is given)
-
   --client-ssl-key <keyfile>         SSL key to use, if any, for proxy to client requests
   --client-ssl-cert <certfile>       SSL certificate to use, if any, for proxy to client requests
   --client-ssl-ca <ca-file>          SSL certificate authority, if any, for proxy to client requests
   --client-ssl-request-cert          Request SSL certs to authenticate clients for API requests
   --client-ssl-reject-unauthorized   Reject unauthorized SSL connections (only meaningful if --client-ssl-request-cert is given)
-
   --default-target <host>            Default proxy target (proto://host[:port])
   --error-target <host>              Alternate server for handling proxy errors (proto://host[:port])
   --error-path <path>                Alternate server for handling proxy errors (proto://host[:port])
@@ -143,14 +139,15 @@ Options:
   --auto-rewrite                     Rewrite the Location header host/port in redirect responses
   --change-origin                    Changes the origin of the host header to the target URL
   --protocol-rewrite <proto>         Rewrite the Location header protocol in redirect responses to the specified protocol
-  --custom-headers <headers>         Comma separated list of custom headers to add to proxied requests (k1:v1,k2:v2,...)
+  --custom-header <header>           Custom header to add to proxied requests. Use same option for multiple headers (--custom-header k1:v1 --custom-header k2:v2)
+                                     (default: [])
   --insecure                         Disable SSL cert verification
   --host-routing                     Use host routing (host as first level of path)
-
   --statsd-host <host>               Host to send statsd statistics to
   --statsd-port <port>               Port to send statsd statistics to
   --statsd-prefix <prefix>           Prefix to use for statsd statistics
   --log-level <loglevel>             Log level (debug, info, warn, error) (default: "info")
+  --timeout <n>                      Timeout (in millis) when proxy drops connection for a request.
   --proxy-timeout <n>                Timeout (in millis) when proxy receives no response from target.
   --storage-backend <storage-class>  Define an external storage class. Defaults to in-MemoryStore.
   -h, --help                         output usage information

RELEASE.md

@@ -0,0 +1,66 @@
+# How to make a release
+
+`configurable-http-proxy` is available as a _npm package_ [available on
+npmjs](https://www.npmjs.com/package/configurable-http-proxy) and a _Docker
+image_ available on
+[DockerHub](https://hub.docker.com/r/jupyterhub/configurable-http-proxy). The
+Docker image is automatically built and published on changes to the git
+repository as is configured
+[here](https://hub.docker.com/repository/docker/jupyterhub/configurable-http-proxy/builds).
+
+To make a tagged release follow the instructions below, but first make sure you
+meet the prerequisites:
+- To be a collaborator of the [npmjs
+  project](https://www.npmjs.com/package/configurable-http-proxy).
+- To have push rights to the [configurable-http-proxy GitHub
+  repository](https://github.com/jupyterhub/configurable-http-proxy).
+- To have [`bump2version`](https://github.com/c4urself/bump2version) installed
+  (`pip install bump2version`).
+
+## Steps to make a release
+
+1. Update [CHANGELOG.md](CHANGELOG.md) if it is not up to date, and verify
+   [README.md](README.md) has an updated output of running `--help`. Make a PR
+   to review the CHANGELOG notes.
+
+1. Once the changelog is up to date, checkout master and make sure it is up to
+   date and clean.
+
+   ```bash
+   ORIGIN=${ORIGIN:-origin} # set to the canonical remote, e.g. 'upstream' if 'origin' is not the official repo
+   git checkout master
+   git fetch $ORIGIN master
+   git reset --hard $ORIGIN/master
+   # WARNING! This next command deletes any untracked files in the repo
+   git clean -xfd
+   ```
+
+1. Update the version with `bump2version` to not include the -dev suffix and let
+   it make a git commit and tag as well for us.
+
+   ```bash
+   # optionally first bump a minor or major version, but
+   # don't bump the patch version, that's already done.
+   # bump2version --no-commit minor
+   # bump2version --no-commit major
+   bump2version --tag release
+   ```
+
+1. Publish to NPM.
+
+   ```bash
+   npm publish
+   ```
+
+1. Reset the version to the next development version with `bump2version`.
+
+   ```bash
+   bump2version --no-tag patch
+   ```
+
+1. Push your release related commits to master along with the annotated tags
+   referencing commits on the master branch.
+
+   ```
+   git push --follow-tags $ORIGIN master
+   ```

package.json

@@ -16,7 +16,7 @@
     "winston": "~3.2.0"
   },
   "devDependencies": {
-    "jasmine": "^3.0.0",
+    "jasmine": "^3.5.0",
     "jshint": "^2.10.2",
     "nyc": "^14.0.0",
     "prettier": "^1.4.4",

test/proxy_spec.js

@@ -216,7 +216,9 @@ describe("Proxy Tests", function() {
     };
     expect(() => {
       const cp = new ConfigurableProxy(options);
-    }).toThrow(new Error("Cannot find module 'mybackend'"));
+    }).toThrowMatching(function(e) {
+      return e.message.includes("Cannot find module 'mybackend'");
+    });
     done();
   });