From f521e2b520d1ea93d4987b159c8b217ce8ea9e65 Mon Sep 17 00:00:00 2001 From: Vinicius Fortuna Date: Wed, 25 Sep 2024 22:34:39 -0400 Subject: [PATCH] fix(mobileproxy): improve documentation (#291) --- README.md | 23 ++++++----- x/examples/smart-proxy/config.json | 62 +----------------------------- x/mobileproxy/README.md | 14 ++++++- 3 files changed, 27 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 04371ced..90b58782 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,15 @@

-> ⚠️ **Warning**: This code is in early stages and is not guaranteed to be stable. If you are +> [!Note] +> This code is under active development and not guaranteed to be stable. If you are > interested in integrating with it, we'd love your [feedback](https://github.com/Jigsaw-Code/outline-sdk/issues/new). The Outline SDK allows you to: - Create tools to protect against network-level interference. -- Add network-level interference protection to existing apps, such as content or communication apps. +- [Add network-level interference protection to existing apps](#add-the-sdk-to-your-app), such as content or communication apps. +- Troubleshoot connectivity and measure interference with a collection of [command-line tools](#command-line-tools). ## Advantages @@ -86,9 +88,12 @@ The Outline Client uses a **generated mobile library** on Android, iOS and macOS Below we provide more details on each integration approach. For more details about setting up and using Outline SDK features, see the [Discussions tab](https://github.com/Jigsaw-Code/outline-sdk/discussions). + ### Generated Mobile Library -To integrate the SDK into a mobile app, follow these steps: +See our [MobileProxy page](./x/mobileproxy/) to learn about the easiest way to integrate the Outline SDK into a mobile app. It runs a local forward proxy that implements resillience strategies that you can use to configure your app's networking libraries. + +For advanced users, it is possible to generate your own mobile library, following these steps: 1. **Create a Go library**: Create a Go package that wraps the SDK functionalities you need. 1. **Generate mobile library**: Use [`gomobile bind`](https://pkg.go.dev/golang.org/x/mobile/cmd/gomobile) to generate Android Archives (AAR) and Apple Frameworks with Java and Objective-C bindings. @@ -98,8 +103,6 @@ To integrate the SDK into a mobile app, follow these steps: > **Note**: You must use `gomobile bind` on the package you create, not directly on the SDK packages. -An easy way to integrate with the SDK in a mobile app is by using the [`x/mobileproxy` library](./x/mobileproxy/) -to run a local web proxy that you can use to configure your app's networking libraries. ### Side Service @@ -144,7 +147,7 @@ They all take a `-transport` flag with a config that specifies what transport sh The config format can be found in [x/config](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/config). -### DNS Query +### Resolve a Domain Name The [`resolve` tool](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/examples/resolve) resolves a domain name, similar to `dig`: @@ -157,7 +160,7 @@ $ go run github.com/Jigsaw-Code/outline-sdk/x/examples/resolve@latest -type A -t ``` -### HTTP Fetch +### Fetch a Web Page The [`fetch` tool](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/examples/fetch) fetches a URL, similar to `curl`. The example below would bypass blocking of `meduza.io` in Russia: @@ -177,7 +180,7 @@ $ go run github.com/Jigsaw-Code/outline-sdk/x/examples/fetch@latest -transport " [DEBUG] 2023/12/28 18:44:56.491273 main.go:105: Cf-Cache-Status: [DYNAMIC] ``` -### Local Proxy Forwarder +### Run a Local Forward Proxy The [`http2transport` tool](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/examples/http2transport) runs a local proxy that creates connections according to the transport. It's effectively a circumvention tool. @@ -210,7 +213,7 @@ cf-ray: 83cdb579bbec4376-EWR alt-svc: h3=":443"; ma=86400 ``` -### Proxy Connectivity Test +### Test Proxy Connectivity The [`test-connectivity` tool](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/examples/test-connectivity) is useful to test connectivity to a proxy. It uses DNS resolutions over TCP and UDP using the transport to test if there is stream and datagram connectivity. @@ -223,7 +226,7 @@ $ go run github.com/Jigsaw-Code/outline-sdk/x/examples/test-connectivity@latest success ``` -### Speed Test +### Test Download Speed The [`fetch-speed` tool](https://pkg.go.dev/github.com/Jigsaw-Code/outline-sdk/x/examples/fetch-speed) fetches a URL, similar to `curl` and calculates the download speed. It could be used for troubleshooting. diff --git a/x/examples/smart-proxy/config.json b/x/examples/smart-proxy/config.json index 8fa3a168..316218fe 100644 --- a/x/examples/smart-proxy/config.json +++ b/x/examples/smart-proxy/config.json @@ -2,105 +2,45 @@ "dns": [ {"https": {"name": "2620:fe::fe"}, "//": "Quad9"}, {"https": {"name": "9.9.9.9"}}, - {"https": {"name": "149.112.112.112"}}, {"https": {"name": "2001:4860:4860::8888"}, "//": "Google"}, {"https": {"name": "8.8.8.8"}}, - {"https": {"name": "2001:4860:4860::8844"}}, - {"https": {"name": "8.8.4.4"}}, {"https": {"name": "2606:4700:4700::1111"}, "//": "Cloudflare"}, {"https": {"name": "1.1.1.1"}}, - {"https": {"name": "2606:4700:4700::1001"}}, - {"https": {"name": "1.0.0.1"}}, - {"https": {"name": "cloudflare-dns.com.", "address": "cloudflare.net."}}, - - {"https": {"name": "2620:119:35::35"}, "//": "OpenDNS"}, - {"https": {"name": "208.67.220.220"}}, - {"https": {"name": "2620:119:53::53"}}, - {"https": {"name": "208.67.222.222"}}, {"https": {"name": "2001:67c:930::1"}, "//": "Wikimedia DNS"}, {"https": {"name": "185.71.138.138"}}, - {"https": {"name": "doh.dns.sb", "address": "cloudflare.net:443"}, "//": "DNS.SB"}, - - {"tls": {"name": "2620:fe::fe"}, "//": "Quad9"}, {"tls": {"name": "9.9.9.9"}}, - {"tls": {"name": "149.112.112.112"}}, {"tls": {"name": "2001:4860:4860::8888"}, "//": "Google"}, {"tls": {"name": "8.8.8.8"}}, - {"tls": {"name": "2001:4860:4860::8844"}}, - {"tls": {"name": "8.8.4.4"}}, {"tls": {"name": "2606:4700:4700::1111"}, "//": "Cloudflare"}, {"tls": {"name": "1.1.1.1"}}, - {"tls": {"name": "2606:4700:4700::1001"}}, - {"tls": {"name": "1.0.0.1"}}, - - {"tls": {"name": "2620:119:35::35"}, "//": "OpenDNS"}, - {"tls": {"name": "208.67.220.220"}}, - {"tls": {"name": "2620:119:53::53"}}, - {"tls": {"name": "208.67.222.222"}}, {"tls": {"name": "2001:67c:930::1"}, "//": "Wikimedia DNS"}, {"tls": {"name": "185.71.138.138"}}, - {"tcp": {"address": "2620:fe::fe"}, "//": "Quad9"}, {"tcp": {"address": "9.9.9.9"}}, - {"tcp": {"address": "149.112.112.112"}}, - {"tcp": {"address": "[2620:fe::fe]:9953"}}, - {"tcp": {"address": "9.9.9.9:9953"}}, - {"tcp": {"address": "149.112.112.112:9953"}}, {"tcp": {"address": "2001:4860:4860::8888"}, "//": "Google"}, {"tcp": {"address": "8.8.8.8"}}, - {"tcp": {"address": "2001:4860:4860::8844"}}, - {"tcp": {"address": "8.8.4.4"}}, {"tcp": {"address": "2606:4700:4700::1111"}, "//": "Cloudflare"}, {"tcp": {"address": "1.1.1.1"}}, - {"tcp": {"address": "2606:4700:4700::1001"}}, - {"tcp": {"address": "1.0.0.1"}}, - - {"tcp": {"address": "2620:119:35::35"}, "//": "OpenDNS"}, - {"tcp": {"address": "208.67.220.220"}}, - {"tcp": {"address": "2620:119:53::53"}}, - {"tcp": {"address": "208.67.222.222"}}, - {"tcp": {"address": "[2620:119:35::35]:443"}}, - {"tcp": {"address": "208.67.220.220:443"}}, - {"tcp": {"address": "[2620:119:35::35]:5353"}}, - {"tcp": {"address": "208.67.220.220:5353"}}, - - + {"udp": {"address": "2620:fe::fe"}, "//": "Quad9"}, {"udp": {"address": "9.9.9.9"}}, - {"udp": {"address": "149.112.112.112"}}, - {"udp": {"address": "[2620:fe::fe]:9953"}}, - {"udp": {"address": "9.9.9.9:9953"}}, - {"udp": {"address": "149.112.112.112:9953"}}, {"udp": {"address": "2001:4860:4860::8888"}, "//": "Google"}, {"udp": {"address": "8.8.8.8"}}, - {"udp": {"address": "2001:4860:4860::8844"}}, - {"udp": {"address": "8.8.4.4"}}, {"udp": {"address": "2606:4700:4700::1111"}, "//": "Cloudflare"}, {"udp": {"address": "1.1.1.1"}}, - {"udp": {"address": "2606:4700:4700::1001"}}, - {"udp": {"address": "1.0.0.1"}}, - - {"udp": {"address": "2620:119:35::35"}, "//": "OpenDNS"}, - {"udp": {"address": "208.67.220.220"}}, - {"udp": {"address": "2620:119:53::53"}}, - {"udp": {"address": "208.67.222.222"}}, - {"udp": {"address": "[2620:119:35::35]:443"}}, - {"udp": {"address": "208.67.220.220:443"}}, - {"udp": {"address": "[2620:119:35::35]:5353"}}, - {"udp": {"address": "208.67.220.220:5353"}} ], "tls": [ diff --git a/x/mobileproxy/README.md b/x/mobileproxy/README.md index 16ae5418..0456f5b9 100644 --- a/x/mobileproxy/README.md +++ b/x/mobileproxy/README.md @@ -1,7 +1,19 @@ -# Mobileproxy: Local Proxy Library for Mobile Apps +# MobileProxy: Local Proxy Library for Mobile Apps This package enables the use Go Mobile to generate a mobile library to run a local proxy and configure your app networking libraries. +**Content app without MobileProxy:** +![image](https://github.com/user-attachments/assets/d96b209c-2198-4382-8bba-12efd8f75dbb) + +**Content app with MobileProxy:** +![image](https://github.com/user-attachments/assets/8b07c0b6-7948-4b61-a6b2-fe2fafdb1a33) + +The integration typically consists of the following steps: +1. Build the mobile native library using Go Mobile. +1. Add the library to your application. +1. Configure and run MobileProxy within your app. +1. Update your networking code to proxy traffic through the local MobileProxy. + ## Build the Go Mobile binaries with [`go build`](https://pkg.go.dev/cmd/go#hdr-Compile_packages_and_dependencies) From the `x/` directory: