README.md

Bridgestrap
===========

Bridgestrap implements an API (for machines) and a Web interface (for people)
to test Tor bridge lines by making a Tor instance fetch the bridges'
descriptor.

Installation
------------

First, install the Golang binary:

      go install

Then, run the binary:

      bridgestrap

By default, bridgestrap will listen on port 5000.  To use its Web interface
(don't forget to turn it on by using the `-web` switch), point your browser to
the address and port that bridgestrap is listening on.  Use the argument
`-addr` to listen to a custom address and port.

Input
-----

Clients send one or more bridge lines to the following API, using an HTTP GET
request, and place the bridge lines in the request body:

      https://HOST/bridge-state

The request body must look as follows:

      {"bridge_lines": ["BRIDGE_LINE_1", ..., "BRIDGE_LINE_N"]}

The "BRIDGE_LINE" strings in the list may contain any bridge line (excluding
the "Bridge" prefix) that tor accepts.  Here are a few examples:

* `1.2.3.4:1234`
* `1.2.3.4:1234 1234567890ABCDEF1234567890ABCDEF12345678`
* `obfs4 1.2.3.4:1234 cert=fJRlJc0T7i2Qkw3SyLQq+M6iTGs9ghLHK65LBy/MQewXJpNOKFq63Om1JHVkLlrmEBbX1w iat-mode=0`

You can test bridgestrap's API over the command line as follows:

      curl -X GET localhost:5000/bridge-state -d '{"bridge_lines": ["BRIDGE_LINE"]}'

You can also use the script test-bridge-lines in the "script" directory to test
a batch of bridge lines.

Output
------

The service responds with the following JSON:

      {
        "bridge_results": {
          "BRIDGE_LINE_1": {
            "functional": BOOL,
            "last_tested": "STRING",
            "error": "STRING", (only present if "functional" is false)
          },
          ...
          "BRIDGE_LINE_N": {
            ...
          }
        },
        "error": "STRING", (only present if the entire test failed)
        "time": FLOAT
      }

In a nutshell, the "bridge_results" dictionary maps bridge lines (as they were
provided in the request) to a dictionary consisting of three keys: "functional"
is set to "true" if tor could fetch the bridge's descriptor.  If tor was unable
to fetch the bridge's descriptor, "functional" is set to "false" and the
"error" key maps to an error string.  The key "last_tested" maps to a string
representation (in ISO 8601 format) of the UTC time and date the bridge was
last tested.

In addition to the "bridge_results" dictionary, the response may contain an
optional "error" key if the entire test failed (e.g. if bridgestrap failed to
communicate with its tor instance).  Finally, "time" is a float that represents
the number of seconds that the test took.

Here are a few examples:

    {
      "bridge_results": {
      },
      "error": "something truly ominous happened",
      "time": 0.32
    }

    {
      "bridge_results": {
        "obfs4 1.2.3.4:1234 cert=fJRlJc0T7i2Qkw3SyLQq+M6iTGs9ghLHK65LBy/MQewXJpNOKFq63Om1JHVkLlrmEBbX1w iat-mode=0": {
          "functional": true,
          "last_tested": "2020-11-12T19:42:16.736853122Z"
        },
        "1.2.3.4:1234": {
          "functional": false,
          "last_tested": "2020-11-10T09:44:45.877531581Z",
          "error": "timed out waiting for bridge descriptor"
        }
      },
      "time": 3.1824
    }

    {
      "bridge_results": {
        "1.2.3.4:1234 1234567890ABCDEF1234567890ABCDEF12345678": {
          "functional": false,
          "last_tested": "2020-11-10T09:44:45.877531581Z",
          "error": "timed out waiting for bridge descriptor"
        }
      },
      "time": 0
    }