github.com/network-quality/goresponsiveness@v0.0.0-20240129151524-343954285090/README.md (about)

     1  # Go Responsiveness
     2  
     3  In late 2021 and early 2022, researchers at Apple took to heart the internet-wide call for giving users more actionable information about the state of their network connections and proposed a new metric, RPM:
     4  
     5  > This document specifies the "RPM Test" for measuring responsiveness. It uses common protocols and mechanisms to measure user experience especially when the network is under working conditions. The measurement is expressed as "Round-trips Per Minute" (RPM) and should be included with throughput (up and down) and idle latency as critical indicators of network quality.
     6  
     7  Apple wrote and released an implementation of the test in its iOS and macOS operating systems in [versions 15 and Monterey](https://support.apple.com/en-gb/HT212313), respectively.
     8  
     9  The researchers at Apple, in collaboration with others throughout the internet-measurement community, proposed RPM as an [IETF RFC](https://github.com/network-quality/draft-ietf-ippm-responsiveness/blob/master/draft-ietf-ippm-responsiveness.txt).
    10  
    11  ## Independent Implementation
    12  
    13  To become a Draft Standard, "at least two independent and interoperable implementation[s]" must exist [RFC2026]. The goal of this implementation of the standard is to satisfy that requirement.
    14  
    15  ## Operation
    16  
    17  ### Requirements
    18  
    19  1. Go (1.21 -- see below)
    20  2. The source code
    21  
    22  **Note**: When go 1.22 is released, this client will upgrade to that version of go. There is an important fix to the runtime ([see here](https://github.com/golang/go/commit/7830180dcd13c028a1619f41bed0ac5e10a720e7)) that we need to incorporate for correctness.
    23  
    24  ### Satisfy Requirements
    25  
    26  To install Go, follow the excellent documentation [online](https://go.dev/doc/install).
    27  
    28  To get the source code, 
    29  
    30  ```console
    31  $ git clone https://github.com/network-quality/goresponsiveness.git
    32  ```
    33  
    34  For the remainder of the instructions, we will assume that `${RSPVNSS_SOURCE_DIR}` is the location of the source code.
    35  
    36  ### Build
    37  
    38  From `${RSPVNSS_SOURCE_DIR}` grab all the required modules:
    39  ```console
    40  $ go mod download
    41  ```
    42  
    43  And then build:
    44  ```console
    45  $ go build networkQuality.go
    46  ```
    47  
    48  That will create an executable in `${RSPVNSS_SOURCE_DIR}` named `networkQuality`.
    49  
    50  > As a bonus, there are now `make`able targets (`all`, `build`, `test`, `clean`) in case that's easier to remember!
    51  
    52  ### Run
    53  
    54  From `${RSPVNSS_SOURCE_DIR}`, running the client is straightforward. Simply 
    55  
    56  ```console
    57  $ ./networkQuality
    58  ```
    59  
    60  Without any options, the tool will attempt to contact `networkquality.example.com` on port 4043 to conduct a measurement. That's likely *not* what you intended. To find out all the options for configuring the execution of the tool, specify the `--help` option:
    61  
    62  ```console
    63  $ ./networkQuality --help
    64  ```
    65  
    66  `networkQuality` with the `-help` option will generate the following output:
    67  
    68  ```
    69    -config string
    70      	name/IP of responsiveness configuration server. (default "networkquality.example.com")
    71    -debug
    72      	Enable debugging.
    73    -path string
    74      	path on the server to the configuration endpoint. (default "config")
    75    -port int
    76      	port number on which to access responsiveness configuration server. (default 4043)
    77    -profile string
    78      	Enable client runtime profiling and specify storage location. Disabled by default.
    79    -ssl-key-file string
    80      	Store the per-session SSL key files in this file.
    81    -sattimeout int
    82      	Maximum time to spend measuring saturation. (default 20)
    83    -rpmtimeout int
    84        Maximum time to spend calculating RPM. (default 10)
    85  ```
    86  
    87  To facilitate testing, you may want to use the open-source RPM server available from [Apple on GitHub](https://github.com/network-quality/server/tree/main/go).
    88  
    89  You can also test against the Apple infrastructure using:
    90  
    91  ```console
    92  $ ./networkQuality --config mensura.cdn-apple.com --port 443 --path /api/v1/gm/config
    93  ```
    94  
    95  ## Dockerfile
    96  
    97  This repo contains a Dockerfile for running the binary so you
    98  don't have to install any languages or build tools.
    99  To use it:
   100  
   101  ```bash
   102  # build the container
   103  docker build -t goresp .   
   104  
   105  # run the RPM test
   106  docker run --rm goresp     
   107  
   108  # run the RPM test with full options, testing against Apple infrastructure
   109  docker run --rm goresp --config mensura.cdn-apple.com --port 443 --path /api/v1/gm/config --debug
   110  ```
   111  
   112  ## Contributing
   113  
   114  We *love* contributions. Before submitting a patch, first format your code with `go fmt`. Then, run `golines`:
   115  
   116  ```console
   117  $ golines -w .
   118  ```
   119  
   120  You can easily install `golines` in to your `${GOPATH}` with
   121  
   122  ```console
   123  $ go install github.com/segmentio/golines@latest
   124  ```
   125  
   126  As a bonus, there are unit tests to check for regressions:
   127  
   128  ```console
   129  $ go test ./timeoutat ./ms ./utilities  ./traceable
   130  ```
   131  
   132  ### IDE Configuration
   133  
   134  If you are developing with VSCode, you can use `ide/settings.json` as the
   135  [workspace's](https://code.visualstudio.com/docs/editor/workspaces) `settings.json` file
   136  in order to meet the project's existing style. In particular, this file will configure
   137  VSCode to use an alternate go formatter known as [`gofumpt`](https://github.com/mvdan/gofumpt)
   138  and, in turn, give `gofumpt` specific configuration directives.
   139  
   140  To use the included `settings.json` file, simply drop it in the `.vscode` directory of the folder
   141  containing this `README.md` file.
   142  
   143  >Note: If you have existing workspace settings, you may be required to take additional
   144  steps to incorporate the information in the given `settings.json` file.
   145  
   146  > You may have to create the `.vscode` directory if it does not already exist.
   147  
   148  ## References
   149  
   150  [RFC2026] https://datatracker.ietf.org/doc/html/rfc2026