fix(mobileproxy): improve documentation (#291)

Jigsaw-Code · Sep 26, 2024 · f521e2b · f521e2b
1 parent fe5dc64
commit f521e2b
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -8,13 +8,15 @@
 <img src="https://github.com/Jigsaw-Code/outline-brand/blob/main/assets/powered_by_outline/color/logo.png?raw=true" width=400pt />
 </p>
 
-> ⚠️ **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
@@ -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
@@ -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: