Updates on config, tests, and docs (#24)

* update: remove bypass flag for non-ss WATM & changed some doc

* update: switch crate name to WATM & update test names

* update: readme for new citation + link to WATM in Go [ci skip]

.github/workflows/rust.yml

@@ -32,7 +32,7 @@ jobs:
     - name: Lint
       run: cargo clippy --workspace --all-targets --verbose --all-features
 
-  build:
+  test_amd64:
     name: Test and Build WASM
     needs: format
     # needs: [format, lint]

README.md

@@ -12,27 +12,30 @@
     </div>
 </div>
 
-The Go implementation of the runtime library can be found in [water-go](https://github.com/gaukas/water). 
+The Go implementation of the runtime library can be found in [water-go](https://github.com/gaukas/water). We now also support building WATM in Go, please refer to [watm](https://github.com/gaukas/watm) for examples and helper libraries interfacing Pluggable Transports-like interfaces. Official Go compiler is currently not supported ([watm#4](https://github.com/gaukas/watm/issues/4)).
 
-### Citation Information
+### Cite our work
 
-If you quoted or used our work, please cite our paper [Just add WATER: WebAssembly-based Circumvention Transports](https://arxiv.org/pdf/2312.00163.pdf) in your work.
+If you quoted or used our work in your own project/paper/research, please cite our paper [Just add WATER: WebAssembly-based Circumvention Transports](https://arxiv.org/pdf/2312.00163.pdf).
 
 <details>
   <summary>BibTeX</summary>
 
   ```bibtex
-  @misc{chi2023just,
-    title={Just add WATER: WebAssembly-based Circumvention Transports}, 
-    author={Erik Chi and Gaukas Wang and J. Alex Halderman and Eric Wustrow and Jack Wampler},
-    year={2023},
-    eprint={2312.00163},
-    archivePrefix={arXiv},
-    primaryClass={cs.CR}
+  @inproceedings{water-foci24,
+	  author = {Chi, Erik and Wang, Gaukas and Halderman, J. Alex and Wustrow, Eric and Wampler, Jack},
+	  year = {2024},
+	  month = {02},
+	  title = {Just add {WATER}: {WebAssembly}-based Circumvention Transports},
+	  address = {Virtual Event},
+	  series = {FOCI '24},
+	  booktitle = {Free and Open Communications on the Internet},
   }
   ```
 </details>
 
+**Update**: our paper has been accepted by FOCI and will appear at [FOCI 2024](https://foci.community/foci24.html) on Feb 19, 2024!
+
 ## Be Water
 
 > Empty your mind, be formless, shapeless, like water. If you put water into a cup, it becomes the cup. You put water into a bottle and it becomes the bottle. You put it in a teapot, it becomes the teapot. Now, water can flow or it can crash. Be water, my friend.

crates/water/README.md

@@ -18,8 +18,7 @@ Library docs will be availale soon on `docs.rs`, for now you can run `cargo doc
 // 		"remote_address": "127.0.0.1",
 // 		"remote_port": 8080,
 // 		"local_address": "127.0.0.1",
-// 		"local_port": 8088,
-//      "bypass": false
+// 		"local_port": 8088
 // 	}
 
 // construct the config

crates/wasm/Cargo.toml → crates/watm/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
-name = "water-wasm"
+name = "water-watm"
 version = "0.1.0"
 authors.workspace = true
 description.workspace = true
 edition.workspace = true
 
 [lib]
-name = "water_wasm"
+name = "water_watm"
 path = "src/lib.rs"
 crate-type = ["cdylib", "lib"]
 

crates/wasm/src/config.rs → crates/watm/src/config.rs

@@ -5,14 +5,13 @@
 
 use super::*;
 
-/// A Config currently contains the local + remote ip & port + bypass flag
+/// A Config currently contains the local + remote ip & port
 #[derive(Debug, Deserialize, Clone)]
 pub struct Config {
     pub remote_address: String,
     pub remote_port: u32,
     pub local_address: String,
     pub local_port: u32,
-    pub bypass: bool,
 }
 
 impl Default for Config {
@@ -29,7 +28,6 @@ impl Config {
             remote_port: 8082,
             local_address: String::from("127.0.0.1"),
             local_port: 8080,
-            bypass: false,
         }
     }
 }

crates/wasm_v0/Cargo.toml → crates/watm_v0/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
-name = "water-wasm-v0"
+name = "water-watm-v0"
 version = "0.1.0"
 authors.workspace = true
 description.workspace = true
 edition.workspace = true
 
 [lib]
-name = "water_wasm_v0"
+name = "water_watm_v0"
 path = "src/lib.rs"
 crate-type = ["cdylib", "lib"]
 

examples/clients/cli/README.md

@@ -20,7 +20,13 @@ you should see `> CONNECTED` in the terminal of running WASM, then you can conne
        {
            "server": "127.0.0.1",
            "server_port": 8388,
-           "password": "Test!23",
+
+           // match the password in the config passed into WATER-cli [remove the comment when copying]
+           "password": "WATERisAwesome!",
+
+           // for now, this is a global variable set in the ShadowSocks WATM, will add the config for it later
+           // the global var is set here: https://github.com/erikziyunchi/water-rs/blob/48716579a3ff69a5de5e4f69c47ff2a80470d96d/examples/water_bins/ss_client_wasm_v1/src/lib.rs#L2
+           // [remove these comment lines when copying]
            "method": "chacha20-ietf-poly1305"
        }
        ```

examples/clients/cli/demo_configs/ss_config.json

@@ -3,5 +3,6 @@
     "remote_port": 8388,
     "local_address": "127.0.0.1",
     "local_port": 8080,
+    "password": "WATERisAwesome!",
     "bypass": false
 }

examples/clients/cli/demo_configs/v0_listener_config.json

@@ -2,6 +2,5 @@
     "remote_address": "127.0.0.1",
     "remote_port": 8088,
     "local_address": "127.0.0.1",
-    "local_port": 8888,
-    "bypass": false
+    "local_port": 8888
 }

examples/clients/cli/demo_configs/v0_relay_config.json

@@ -2,6 +2,5 @@
     "remote_address": "127.0.0.1",
     "remote_port": 8888,
     "local_address": "127.0.0.1",
-    "local_port": 8080,
-    "bypass": false
+    "local_port": 8080
 }

examples/water_bins/echo_client/Cargo.toml

@@ -28,4 +28,4 @@ url = { version = "2.2.2", features = ["serde"] }
 libc = "0.2.147"
 
 # water wasm lib import
-water-wasm = { path = "../../../crates/wasm/", version = "0.1.0" }
+water-watm = { path = "../../../crates/watm/", version = "0.1.0" }

examples/water_bins/echo_client/src/lib.rs

@@ -6,7 +6,7 @@ use bincode::{self};
 use lazy_static::lazy_static;
 use tracing::{info, Level};
 
-use water_wasm::*;
+use water_watm::*;
 
 pub mod async_socks5_listener;
 

examples/water_bins/plain_v0/Cargo.toml

@@ -22,4 +22,4 @@ tracing = "0.1"
 tracing-subscriber = "0.3.17"
 
 # water wasm lib import
-water-wasm-v0 = { path = "../../../crates/wasm_v0/", version = "0.1.0" }
+water-watm-v0 = { path = "../../../crates/watm_v0/", version = "0.1.0" }

examples/water_bins/plain_v0/src/lib.rs

@@ -1,4 +1,4 @@
-use water_wasm_v0::*;
+use water_watm_v0::*;
 
 use lazy_static::lazy_static;
 use std::ops::DerefMut;

examples/water_bins/reverse_v0/Cargo.toml

@@ -18,5 +18,8 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 tokio = { version = "1.33.0", default-features = false, features = ["fs", "net", "rt", "macros", "io-util", "io-std", "time", "sync"] }
 
+tracing = "0.1"
+tracing-subscriber = "0.3.17"
+
 # water wasm lib import
-water-wasm-v0 = { path = "../../../crates/wasm_v0/", version = "0.1.0" }
+water-watm-v0 = { path = "../../../crates/watm_v0/", version = "0.1.0" }

examples/water_bins/reverse_v0/src/lib.rs

@@ -1,4 +1,4 @@
-use water_wasm_v0::*;
+use water_watm_v0::*;
 
 use lazy_static::lazy_static;
 use std::ops::DerefMut;
@@ -11,6 +11,8 @@ use tokio::{
 };
 use v0plus::ConnPair;
 
+use tracing::Level;
+
 const READ_BUFFER_SIZE: usize = 1024; // 1KB is shorter than common MTU but longer than common TCP MSS
 
 lazy_static! {
@@ -28,7 +30,11 @@ pub static VERSION: i32 = v0plus::VERSION;
 
 // version-independent API
 #[export_name = "_water_init"]
-pub fn _init() -> i32 {
+pub fn _init(debug: bool) -> i32 {
+    if debug {
+        tracing_subscriber::fmt().with_max_level(Level::INFO).init();
+    }
+
     // do all the initializing work here AND pull config from host
     sleep(Duration::from_millis(10)); // sleep for 10ms
     error::Error::None.i32()

examples/water_bins/ss_client_wasm_v1/Cargo.toml

@@ -38,4 +38,4 @@ futures = "0.3.28"
 pin-project = "1.1.2"
 
 # water wasm lib import
-water-wasm = { path = "../../../crates/wasm/", version = "0.1.0" }
+water-watm = { path = "../../../crates/watm/", version = "0.1.0" }

examples/water_bins/ss_client_wasm_v1/src/lib.rs

@@ -46,7 +46,7 @@ use config::*;
 use crypto_io::*;
 use socks5::*;
 use utils::*;
-use water_wasm::*;
+use water_watm::*;
 
 // =================== SHADOWSOCKS_CRYPTO ===================
 use shadowsocks_crypto::{v1::random_iv_or_salt, v1::Cipher, CipherKind};

scripts/build_wasm_targets.sh

@@ -2,7 +2,8 @@
 set -e  # Exit on any error
 
 members=(
-    "crates/wasm"
+    "crates/watm"
+    "crates/watm_v0"
     "examples/water_bins/ss_client_wasm_v1"
     "examples/water_bins/echo_client"
     "examples/water_bins/plain_v0"

tests/Cargo.toml

@@ -8,7 +8,7 @@ publish = false
 
 
 [dev-dependencies]
-water-wasm = { path = "../crates/wasm" }
+water-watm = { path = "../crates/watm" }
 water = { path = "../crates/water" }
 
 tracing = "0.1"

tests/test_data/config.json

@@ -2,6 +2,5 @@
     "remote_address": "127.0.0.1",
     "remote_port": 8080,
     "local_address": "127.0.0.1",
-    "local_port": 8088,
-    "bypass": false
+    "local_port": 8088
 }

tests/tests/echo_tests.rs

@@ -18,8 +18,7 @@ fn test_echo() -> Result<(), Box<dyn std::error::Error>> {
 		"remote_address": "127.0.0.1",
 		"remote_port": 8080,
 		"local_address": "127.0.0.1",
-		"local_port": 8088,
-        "bypass": false
+		"local_port": 8088
 	}
 	"#;
     // Create a directory inside of `std::env::temp_dir()`.
@@ -30,7 +29,6 @@ fn test_echo() -> Result<(), Box<dyn std::error::Error>> {
 
     let test_message = b"hello";
     let handle = std::thread::spawn(|| {
-        // let listener = TcpListener::bind("127.0.0.1:8080").await.unwrap();
         let listener = TcpListener::bind(("127.0.0.1", 8080)).unwrap();
         let (mut socket, _) = listener.accept().unwrap();
         let mut buf = [0; 1024];
@@ -46,6 +44,9 @@ fn test_echo() -> Result<(), Box<dyn std::error::Error>> {
     });
 
     let conf = config::WATERConfig::init(
+        // Source code of echo_client.wasm:
+        // https://github.com/erikziyunchi/water-rs/tree/main/examples/water_bins/echo_client
+        //
         String::from("./test_wasm/echo_client.wasm"),
         String::from("_water_init"),
         String::from(file_path.to_string_lossy()),

tests/tests/ss_testing.rs

@@ -146,6 +146,9 @@ async fn wasm_managed_shadowsocks_async() -> Result<(), Box<dyn std::error::Erro
 
     // ==== setup WASM Shadowsocks client ====
     let conf = config::WATERConfig::init(
+        // Source code of ss_client_wasm.wasm:
+        // https://github.com/erikziyunchi/water-rs/tree/main/examples/water_bins/ss_client_wasm_v1
+        //
         String::from("./test_wasm/ss_client_wasm.wasm"),
         String::from("v1_listen"),
         // Currently using a temp file to pass config to WASM client
@@ -223,7 +226,7 @@ async fn wasm_managed_shadowsocks_bypass_async() -> Result<(), Box<dyn std::erro
 
     let mut water_client = runtime::client::WATERClient::new(conf).unwrap();
 
-    // ==== spawn a thread to run WASM Shadowsocks client ====
+    // spawn a thread to run WASM Shadowsocks client
     thread::spawn(move || {
         water_client.execute().unwrap();
     });
@@ -236,7 +239,6 @@ async fn wasm_managed_shadowsocks_bypass_async() -> Result<(), Box<dyn std::erro
     // ==== test WASM Shadowsocks client ====
     // currently only support connect by ip,
     // get the ip of detectportal.firefox.com
-
     let mut addrs = "detectportal.firefox.com:80".to_socket_addrs()?;
     let ip = addrs
         .find(|addr| addr.is_ipv4())
@@ -266,41 +268,3 @@ async fn wasm_managed_shadowsocks_bypass_async() -> Result<(), Box<dyn std::erro
 
     Ok(())
 }
-
-// Here is a test that runs the ss_client that has to be ended with signal
-// #[test]
-fn execute_wasm_shadowsocks_client() -> Result<(), Box<dyn std::error::Error>> {
-    tracing_subscriber::fmt().with_max_level(Level::INFO).init();
-
-    let cfg_str = r#"
-	{
-		"remote_address": "138.197.211.159",
-		"remote_port": 5201,
-		"local_address": "127.0.0.1",
-		"local_port": 8080,
-        "bypass": true
-	}
-	"#;
-
-    // Create a directory inside of `std::env::temp_dir()`.
-    let dir = tempdir()?;
-    let file_path = dir.path().join("temp-config.txt");
-    let mut file = File::create(&file_path)?;
-    writeln!(file, "{}", cfg_str)?;
-
-    // ==== setup WASM Shadowsocks client ====
-    let conf = config::WATERConfig::init(
-        String::from("./test_wasm/ss_client_wasm.wasm"),
-        String::from("v1_listen"),
-        String::from(file_path.to_string_lossy()),
-        config::WaterBinType::Runner,
-        false,
-    )
-    .unwrap();
-
-    let mut water_client = runtime::client::WATERClient::new(conf).unwrap();
-
-    water_client.execute().unwrap();
-
-    Ok(())
-}