From ed6169d99c79b1b52e382ac1fda2db90b16fe415 Mon Sep 17 00:00:00 2001 From: chad Date: Mon, 28 Aug 2023 17:47:59 -0700 Subject: [PATCH 1/2] docs(multidim-interop): Update instructions for getting started (#282) --- multidim-interop/README.md | 65 ++++++++++++++++++++++++-------------- 1 file changed, 41 insertions(+), 24 deletions(-) diff --git a/multidim-interop/README.md b/multidim-interop/README.md index ac190c6b4..da353684d 100644 --- a/multidim-interop/README.md +++ b/multidim-interop/README.md @@ -29,39 +29,56 @@ environment variables. The current parameters are: The test should do two different things depending on if it's the dialer or listener. -## Running Locally +## Running Tests Locally using Docker images -In some cases you may want to run locally when debugging, such as modifying internal dependencies. +1. Build the images of the implementations -1. To run the test locally, you'll also need to have docker installed in order to run the redis instance. Once docker is running, you can run the following command to start the redis instance: + ```bash + make + ``` -```bash -docker run --rm -p 6379:6379 redis:7-alpine -``` - -This will start a redis instance on port 6379. +2. Install the dependencies -2. Next, you'll need to install the dependencies and build the implementation for the test. In this and the next step we are using a JS implementation as an example, so you would run the following command: + ```bash + npm install + ``` +3. Run the tests + ```bash + npm run test + ``` +**Note**: +You may only want to run specific versions, you can do so by passing the `--test-filter` flag ```bash -cd impl/js/v0.xx.xx/ && make +npm run test -- --test-filter=js-libp2p-head ``` - -3. Then you can run a listener by running the following command in this case we are running a rust listener: - +You can also ignore specific versions by passing the `--test-ignore` flag ```bash - RUST_LOG=yamux=trace transport=tcp muxer=yamux security=noise is_dialer=false ip="0.0.0.0" redis_addr=localhost:6379 cargo run --package interop-tests - ``` - -3. Finally you can run a dialer by running the following command, ensure that you pass the required environment variables, as well as any that may be of use for debugging: - -```bash -DEBUG=*:yamux:trace transport=tcp muxer=yamux security=noise is_dialer=true npm run test -- -t node +npm run test -- --test-ignore=js-libp2p-head ``` -For more details on how to run a dialer vs a listener, see the sections below. - -## Dialer +## Adding an implementation + +1. Add the implementation to new subdirectory in [`impl/*`](./impl/). + - For a new implementation, create a folder `impl//` e.g. `go-libp2p` + - For a new version of an existing implementation, create a folder `impl//`. + - In that folder include a `Makefile` that builds a docker image and stores it as `image.json` + - Requirements for the executable: +2. Add the implementation to [`versions.ts`](./versions.ts). +3. Add the implementation (and it's subdirectories) [`Makefile`](./Makefile). +4. The implementation must implement a [ping](https://github.com/libp2p/specs/blob/50db89f3a71a87b096b0994a43a2dce0d251aeec/ping/ping.md) test, where it listens for a ping + and responds with a pong. The test runner will measure the round trip time + and the time it takes to establish the connection. +5. The implementation must accept the a `transport` flag which specifies which transport to use. e.g. `tcp`, `ws`, `quic`, `quic-v1`, `webtransport`. +6. The implementation must accept the a `muxer` flag which specifies which muxer to use. e.g. `mplex`, `yamux`. +7. The implementation may accept an `ip` flag which specifies which IP address to bind to. If not specified, the implementation should bind to `0.0.0.0` +8. The implementation must accept a `redis_addr` flag which specifies which address to connect to redis. If not specified, the implementation should connect to `redis:6379` +9. The implementation must accept a `test_timeout_seconds` flag which specifies the timeout of the test. If not specified, the implementation should use a default of 180 seconds. +10. The implementation must accept an `is_dialer` flag which specifies whether the implementation should dial or listen. + +Below is a more detailed description of the test spec. + +### Dialer The dialer should emit all diagnostic logs to `stderr`. Only the final JSON string result should be emitted to `stdout`. @@ -80,7 +97,7 @@ string result should be emitted to `stdout`. On error, the dialer should return a non-zero exit code. -## Listener +### Listener The listener should emit all diagnostic logs to `stderr`. From 262563be0b7a9efa4ae49c5622d5a045e4ca62e0 Mon Sep 17 00:00:00 2001 From: chad Date: Mon, 28 Aug 2023 17:54:20 -0700 Subject: [PATCH 2/2] docs: update test filter parameter (#282) --- multidim-interop/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/multidim-interop/README.md b/multidim-interop/README.md index da353684d..8d708e797 100644 --- a/multidim-interop/README.md +++ b/multidim-interop/README.md @@ -37,7 +37,7 @@ listener. make ``` -2. Install the dependencies +2. Install the dependencies need to run the tests ```bash npm install @@ -48,13 +48,13 @@ listener. npm run test ``` **Note**: -You may only want to run specific versions, you can do so by passing the `--test-filter` flag +You may only want to run specific versions, you can do so by passing the `--name-filter` flag ```bash -npm run test -- --test-filter=js-libp2p-head +npm run test -- --name-filter js-libp2p-head ``` -You can also ignore specific versions by passing the `--test-ignore` flag +You can also ignore specific versions by passing the `--name-ignore` flag ```bash -npm run test -- --test-ignore=js-libp2p-head +npm run test -- --name-filter js-libp2p-head ``` ## Adding an implementation