the-handbrake v0.7.0

handbrake

Permanently cache HTTP responses from other servers.

USAGE

    hb serve <server> [--port=<local port>] [--database-file=<file>] [--ignore=<header>]...
    hb ls [<id>] [--database-file=<file>]
    hb (--help | --version)

INSTALL

    npm install -g the-handbrake

SYNOPSIS

the handbrake is a proxy server that locally caches responses from the server we're proxying to. Therefore, any subsequent request that matches one prior will be served said cached response.

This is useful when you need to rapidly test against slow APIs and the like and you don't mind getting stale data, but it must be real world and semantically valid: make the request once, the handbrake caches it, and serves said response henceforth.

See the MOTIVATION section for more information.

the handbrake stops HTTP Requests. the handbrake stops all.

TERMINOLOGY

Request Profile

An object consisting of a HTTP Method, a specific URL, any number of header:value request pairs, and a cached response {status code, headers, body}.

Matching

Each time a request to the handbrake is made, it is compared to all Request Profiles in the database, and if the method, url, and all of the request headers are the same as a specific Request Profile, the request is considered to have 'matched' said Request Profile.

N.B.: If a request matches a Request Profile's method and url, but the set of respective headers differ, the request does not match the Request Profile.

Ignoring

Sometimes, when matching requests to Request Profiles, you want to ignore common headers that can vary from environment to environment and aren't really relevant to a returned response. Once such example is the User-Agent header, which varies from browser to browser, but generally isn't relevant when testing HTTP APIs.

If you would like to tell the handbrake to ignore such headers, when starting an instance with `serve`, specify one or more `--ignore` (or `-i`) flags like so:

    $ hb serve http://bizbang.example -i Accept -i User-Agent

MOTIVATION

Testing HTTP APIs is hard and unfun. Testing slow HTTP APIs is even less fun. the handbrake tries to remedy that by standing in-between you and your slow API server: the first time you request a URL, the handbrake forwards your request to the target server, then caches that response and serves it for all subsequent requests that match that initial request (cf. TERMINOLOGY section: matching).

And/or, once you populated the handbrake database with a relevant collection of endpoints, you can use the handbrake for unit testing: point your unit test requests (with the same set of headers/credentials/body/etc. that you would normally use for real-world requests) at a running handbrake instance, and it will return the stored mocked responses. Instead of testing against a potentially constantly changing (and/or slow) production API, you can use the handbrake to test against prior-received, ideally real-world data.

Additionally, as a side-effect of how the handbrake works, you can also use it to cache pages of your choice offline: first, just visit all of the desired pages through the handbrake proxy, and then just disconnect from the internet and connect again to the same handbrake database. Cached requests stay in the database forever (unless deleted), and if you get a cache hit, your request is short-circuited to the handbrake, and actually doesn't need to hit the internet.

EXAMPLES

Proxies (and then caches the responses to) requests from localhost:8001 to https://foobar.example:564 using the default database file location (creating one if one does not exist at said location):

    $ hb serve https://foobar.example:564

Proxies (and then caches the responses to) requests from localhost:9999 to http://192.168.56.102:1234, using '/tmp/hb.db' as the database file (creating one if one does not exist at said location), ignoring the 'Accept' and 'User-Agent' header values when matching requests:

    $ hb serve 192.168.56.102:1234 -p 9999 -d /tmp/hb.db -i Accept -i User-Agent

List all Request Profiles (sans their response bodies) using the database file located at '/tmp/hb.db':

    $ hb ls --database-file=/tmp/hb.db

List the Request Profile HTTP Response for id 052fd15c-0009-11e8-84a8-6fe2898c8078 using the default database:

    $ hb ls 052fd15c-0009-11e8-84a8-6fe2898c8078:

COMMANDS

serve <server> [--port=<local port>] [--database-file=<file>] [--ignore=<header>]...

Starts up a server listening on localhost:$port that proxies (and then caches the responses to) requests sent to $server, ignoring the given user-specified header values and saving the Request Profiles to the given $database-file.

You can also specify a port for the $server in the conventional manner, i.e.:

    example.com:8080

The default database file location is one of:

• $XDG_CONFIG_HOME/handbrake/rp.db, if $XDG_CONFIG_HOME exists or
• $HOME/.config/handbrake/rp.db if it does not.

ls [<id>] [--database-file=<file>]

Pretty-print Request Profiles to stdout.

If the $id argument is given, the entire Request Profile HTTP Response is printed.

See the serve command section for more information about the --database-file option.

OPTIONS

    -p, --port=<local port>    The local port you want the handbrake to listen for request on [default: 8001].
    -d, --database-file=<file> The database file you would like to use (default: '$XDG_CONFIG_HOME/handbrake/rp.db', if $XDG_CONFIG_HOME is set, or '$HOME/.config/handbrake/rp.db').
    -i, --ignore=<header>      Specify that the given header should be ignored when matching requests to Request Profiles.
    -h, --help                 Show this help text.
    -v, --version              Provide version information.