...

Text file src/cloud.google.com/go/httpreplay/cmd/httpr/README.md

Documentation: cloud.google.com/go/httpreplay/cmd/httpr

     1# httpr, a Record/Replay Proxy
     2
     3httpr is an HTTP proxy that records and replays traffic. It is designed
     4specifically for Google APIs that use HTTP exclusively. These include the Google
     5Cloud Storage and BigQuery clients, as well as the clients in the
     6`github.com/google/google-api-*-client` repos.
     7
     8If you are writing Go code, you should use the `cloud.google.com/go/httpreplay` package, which
     9is a simpler way to use the proxy.
    10
    11## Using a Record/Replay Proxy
    12
    13A record/replay proxy lets you run an "integration" test that accesses a
    14backend like a Google service and record the interaction. Subsequent runs of the
    15test can replay the server's responses without actually contacting the server,
    16turning the integration test into a fast and inexpensive unit test.
    17
    18## Usage
    19
    20First, obtain the `httpr` binary. If you have the Go toolchain, you can run `go
    21get -u cloud.google.com/go/httpreplay/cmd/httpr`. Otherwise, precompiled
    22binaries for various architectures and operating systems are available from [the
    23releases page](https://github.com/googleapis/google-cloud-go/releases).
    24
    25### Recording
    26
    271. Start `httpr` in record mode by passing it the `-record` flag with a filename:
    28   ```
    29   httpr -record myclient.replay
    30   ```
    31   By default, `httpr` will run on port 8080, and open a control port on 8181.
    32   You can change these with the `-port` and `-control-port` flags.
    33   You will want to run `httpr` in the background or in another window.
    341. In order for `httpr` to record HTTPS traffic, your client must trust it. It
    35   does so by installing a CA certificate created by `httpr` during the
    36   recording session. To obtain the certificate in PEM form, GET the URL
    37   `http://localhost:8181/authority.cer`. (If you changed the control port, use
    38   it in place of 8181.)  Consult your language to determine
    39   how to install the certificate. Note that the certificate is different for each run
    40   of `httpr`.
    411. Arrange for your test program to use `httpr` as a proxy. This may be as
    42   simple as setting the `HTTPS_PROXY` environment variable.
    431. Run your test program, using whatever authentication for your Google API
    44   clients that you wish.
    451. Send `httpr` a SIGINT signal (`kill -2`). `httpr` will write
    46   the replay file, then exit.
    47
    48### Replaying
    49
    501. Start `httpr` in replay mode, in the background or another window:
    51   ```
    52   httpr -replay myclient.replay
    53   ```
    541. Install the CA certificate as described above.
    551. Have your test program treat `httpr` as a proxy, as described above.
    561. Run your test program. Your Google API clients should use no authentication.
    57
    58## Tips
    59
    60You must remove all randomness from your interaction while recording,
    61so that the replay is fully deterministic.
    62
    63Note that BigQuery clients choose random values for job IDs and insert ID if you
    64do not supply them. Either supply your own, or seed the client's random number
    65generator if possible.
    66
    67## Examples
    68
    69Examples of running `httpr` can be found in `examples` under this file's directory.
    70
    71

View as plain text