{"id":14563804,"url":"https://github.com/refraction-networking/water","last_synced_at":"2025-04-10T13:05:28.023Z","repository":{"id":216404079,"uuid":"668118585","full_name":"refraction-networking/water","owner":"refraction-networking","description":"WebAssembly Transport Executables Runtime","archived":false,"fork":false,"pushed_at":"2024-07-22T02:56:42.000Z","size":3532,"stargazers_count":25,"open_issues_count":10,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-08T02:43:12.574Z","etag":null,"topics":["censorship-circumvention","computer-networks","pluggable-transports","proxy","transport","wasi","webassembly","webassembly-runtime"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/refraction-networking.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-19T04:28:13.000Z","updated_at":"2024-09-04T06:46:31.000Z","dependencies_parsed_at":"2024-03-18T18:26:41.291Z","dependency_job_id":"13f4bcfc-b73d-49b4-ae05-cc320458e6cc","html_url":"https://github.com/refraction-networking/water","commit_stats":null,"previous_names":["gaukas/water","refraction-networking/water"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fwater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fwater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fwater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fwater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/refraction-networking","download_url":"https://codeload.github.com/refraction-networking/water/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224573384,"owners_count":17333807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["censorship-circumvention","computer-networks","pluggable-transports","proxy","transport","wasi","webassembly","webassembly-runtime"],"created_at":"2024-09-07T02:04:42.948Z","updated_at":"2024-11-14T05:38:59.934Z","avatar_url":"https://github.com/refraction-networking.png","language":"Go","funding_links":[],"categories":["webassembly"],"sub_categories":[],"readme":"# W.A.T.E.R.: WebAssembly Transport Executables Runtime\n![Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-green)\n[![FOSSA](https://app.fossa.com/api/projects/git%2Bgithub.com%2Frefraction-networking%2Fwater.svg?type=shield\u0026issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Frefraction-networking%2Fwater?ref=badge_shield\u0026issueType=license)\n[![CI](https://github.com/refraction-networking/water/actions/workflows/water.yml/badge.svg?branch=master)](https://github.com/refraction-networking/water/actions/workflows/water.yml)\n[![Go Doc](https://pkg.go.dev/badge/github.com/refraction-networking/water.svg)](https://pkg.go.dev/github.com/refraction-networking/water)\n\n\u003cdiv style=\"width: 100%; height = 160px\"\u003e\n    \u003cdiv style=\"width: 75%; height: 150px; float: left;\"\u003e \n        WATER-go provides a Go runtime for WebAssembly Transport Modules(WATM) as a pluggable\n        application-layer transport protocol provider. It is designed to be highly portable and\n        lightweight, allowing for rapidly deployable pluggable transports. While other pluggable\n        transport implementations require a fresh client deployment (and app-store review) to update\n        their protocol WATER allows \u003cb\u003edynamic delivery of new transports\u003c/b\u003e in real time\n        over the network or out-of-band.\u003cbr /\u003e\n        \u003cbr /\u003e\n    \u003c/div\u003e\n    \u003cdiv style=\"margin-left: 80%; height: 150px;\"\u003e \n        \u003cimg src=\".github/assets/logo_v0.svg\" alt=\"WATER wasm transport\" align=\"right\"\u003e\n    \u003c/div\u003e\n\u003c/div\u003e\n\nTo build a WATM in Go, please refer to [watm](https://github.com/refraction-networking/watm) for examples and helper libraries interfacing Pluggable Transports-like interfaces. Official Go compiler is currently not supported until further notice.\n\nYou can contact one of developers personally via gaukas.wang@colorado.edu, or simply [opening an issue](https://github.com/refraction-networking/water/issues/new). \n\nThe Rust implementation of the runtime library and information about writing, building, and using WebAssembly Transport Modules(WATM) from Rust can be found in [water-rs](https://github.com/refraction-networking/water-rs). \n\n### Cite our work\n\nIf you quoted or used our work in your own project/paper/research, please cite our paper [Just add WATER: WebAssembly-based Circumvention Transports](https://www.petsymposium.org/foci/2024/foci-2024-0003.pdf), which is published in the proceedings of Free and Open Communications on the Internet (FOCI) in 2024 issue 1, pages 22-28.\n\n\u003cdetails\u003e\n  \u003csummary\u003eBibTeX\u003c/summary\u003e\n    \n  ```bibtex\n  @inproceedings{water-foci24,\n      author = {Erik Chi and Gaukas Wang and J. Alex Halderman and Eric Wustrow and Jack Wampler},\n      title = {Just add {WATER}: {WebAssembly}-based Circumvention Transports},\n      booktitle = {Free and Open Communications on the Internet},\n      publisher = {},\n      year = {2024},\n      url = {https://www.petsymposium.org/foci/2024/foci-2024-0003.pdf},\n  }\n  ```\n\u003c/details\u003e\n\n## Be Water\n\n\u003e 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.\n\u003e\n\u003e -- Bruce Lee\n\n# License\n\nThis project is licensed under Apache 2.0 license. \n\n## Contents\n\nThis repo contains a Go package `water`, which implements the runtime library used to interact with `.wasm` WebAssembly Transport Modules(WATM). \n\n# Usage\n\n\u003c!-- ## API  --\u003e\nBased on **WASI Snapshot Preview 1** (_wasip1_), currently W.A.T.E.R. provides a set of `net`-like APIs via `Dialer`, `Listener` and `Relay`.\n\n## Versioning\n\nW.A.T.E.R. is designed to be future-proof with the automated multi-version WebAssembly Transport Module(WATM) support. In order to minimize the size of compiled application binaries importing `water`, the support for each WATM version is implemented in separate sub-packages and by default none will be enabled. The developer MUST manually enable each version to be supported by importing the corresponding package: \n\n```go\nimport (\n\t// ...\n\n\t_ \"github.com/refraction-networking/water/transport/v0\"\n\n\t// ...\n)\n```\n\nOtherwise, it is possible that the W.A.T.E.R. runtime cannot determine the version of the WATM and therefore fail to select the corresponding runtime: \n\n```go\npanic: failed to listen: water: listener version not found\n```\n\n### Customizable Version\n\n_TODO: add documentations for customizable WATM version._\n\n## Components\n\n### Dialer\n\nA `Dialer` connects to a remote address and returns a `net.Conn` to the caller if the connection can\nbe successfully established. The `net.Conn` then provides tunnelled read and write to the remote\nendpoint with the WebAssembly module wrapping / encrypting / transforming the traffic.\n\n`Dialer` is used to encapsulate the caller's connection into an outbound, transport-wrapped\nconnection.\n\n```go\n\twasm, _ := os.ReadFile(\"./examples/v0/plain/plain.wasm\")\n\n\tconfig := \u0026water.Config{\n\t\tTransportModuleBin: wasm,\n\t}\n\n\tdialer, _ := water.NewDialerWithContext(context.Background(), config)\n\tconn, _ := dialer.DialContext(context.Background(),\"tcp\", remoteAddr)\n\t// ...\n```\n\n### Listener\n\nA `Listener` listens on a local address for incoming connections which  it `Accept()`s, returning\na `net.Conn` for the caller to handle. The WebAssembly Module is responsible for the initial\naccpt allowing it to implement both the server side handshake as well as any unwrap / decrypt\n/reform operations required to validate and re-assemble the stream. The `net.Conn` returned provides\nthe normalized stream, and allows the caller to write back to the client with the WebAssembly module\nencoding / encrypting / transforming traffic to be obfuscated on the wire on the way to the remote \nclient.\n\n\n`Listener` is used to decapsulate incoming transport-wrapped connections for the caller to handle,\nmanaging the tunnel obfuscation once a connection is established.\n\n```go\n\twasm, _ := os.ReadFile(\"./examples/v0/plain/plain.wasm\")\n\n\tconfig := \u0026water.Config{\n\t\tTransportModuleBin: wasm,\n\t}\n\n\tlis, _ := config.ListenContext(context.Background(), \"tcp\", localAddr)\n\tdefer lis.Close()\n\tlog.Printf(\"Listening on %s\", lis.Addr().String())\n\n\tfor {\n\t\tconn, err := lis.Accept()\n\t\thandleConn(conn)\n\t}\n\n\t// ...\n```\n\n### Relay\n\nA `Relay` combines the role of `Dialer` and `Listener`. It listens on a local address `Accept()`-ing\nincoming connections and `Dial()`-ing the remote endpoints on establishment. The connecions are\ntunneled through the WebAssembly Transport Module allowing the module to handshake, encode,\ntransform, pad, etc. without any caller interaction. The internal `Relay` manages  the incoming\nconnections as well as the associated outgoing connectons.\n\n`Relay` is a managed many-to-many handler for incoming connections that uses the WebAssemble module\nto tunnel traffic.\n\n```go\n\twasm, _ := os.ReadFile(\"./examples/v0/plain/plain.wasm\")\n\n\tconfig := \u0026water.Config{\n\t\tTransportModuleBin: wasm,\n\t}\n\n\trelay, _ := water.NewRelayWithContext(context.Background(), config)\n\n\trelay.ListenAndRelayTo(\"tcp\", localAddr, \"tcp\", remoteAddr) // blocking\n```\n\n## Example\n\nSee [examples](./examples) for example usecase of W.A.T.E.R. API, including `Dialer`, `Listener` and `Relay`.\n\n## Submodules\n\n`watm` has its own licensing policy, please refer to [watm](https://github.com/refraction-networking/watm) for more information.\n\n# Cross-platform Support\n\nW.A.T.E.R. is designed to be cross-platform (and cross-architecture). \nCurrently, it supports the following platforms: \n\n|       Target       | Compiles? | Tests Pass? |\n| ------------------ | --------- | ----------- | \n| linux/amd64        | ✅        | ✅         |\n| linux/arm64        | ✅        | ✅         |\n| linux/riscv64      | ✅        | ✅         |\n| macos/amd64        | ✅        | ✅         |\n| macos/arm64        | ✅        | ✅         |\n| windows/amd64      | ✅        | ✅         |\n| windows/arm64      | ✅        | ❓         |\n| others             | ❓        | ❓         |\n\n## Acknowledgments\n\n* We thank [GitHub.com](https://github.com) for providing GitHub Actions runners for all targets below:\n\t* `linux/amd64` on Ubuntu Latest\n\t* `linux/arm64` via [docker/setup-qemu-action](https://github.com/docker/setup-qemu-action)\n\t* `linux/riscv64` via [docker/setup-qemu-action](https://github.com/docker/setup-qemu-action)\n\t* `macos/amd64` on macOS 12\n\t* `macos/arm64` on macOS 14\n\t* `windows/amd64` on Windows Latest\n\n* We thank [FlyCI.net](https://www.flyci.net) for providing GitHub Actions runners on `macos/arm64` (Apple M1) _in the past_. (We switched to GitHub's `macos-14` runner as of Jan 31 2024)\n\nWe are currently actively looking for a CI provider for more target platforms. Please reach out and let us know if you would like to help.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefraction-networking%2Fwater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefraction-networking%2Fwater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefraction-networking%2Fwater/lists"}