mcfarljw / outline-sdk

SDK to build network tools based on Outline components.

Outline SDK (Beta)

⚠️ Warning: This code is in early stages and is not guaranteed to be stable. If you are interested in integrating with it, we'd love your feedback.

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.

Advantages

Multi-Platform	Proven Technology	Composable
Supports Android, iOS, Windows, macOS and Linux.	Field-tested in the Outline Client and Server, helping millions to access the internet under harsh conditions.	Designed for modularity and reuse, allowing you to craft custom transports.

Integration Methods

Choose from one of the following methods to integrate the Outline SDK into your project:

• Generated Mobile Library: For Android, iOS, and macOS apps. Uses gomobile bind to generate Java and Objective-C bindings.
• Side Service: For desktop and Android apps. Runs a standalone Go binary that your application communicates with (not available on iOS due to subprocess limitations).
• Go Library: Directly import the SDK into your Go application. API Reference.
• Generated C Library: Generate C bindings using go build.

The Outline Client uses a generated mobile library on Android, iOS and macOS (based on Cordova) and a side service on Windows and Linux (based on Electron).

Below we provide more details on each integration approach. For more details about setting up and using Outline SDK features, see the Discussions tab.

Generated Mobile Library

To integrate the SDK into a mobile app, follow these steps:

1. Create a Go library: Create a Go package that wraps the SDK functionalities you need.
2. Generate mobile library: Use gomobile bind to generate Android Archives (AAR) and Apple Frameworks with Java and Objective-C bindings.
   • Android examples: Outline Android Archive, Intra Android Archive.
   • Apple examples: Outline iOS Framework, Outline macOS Framework.
3. Integrate into your app: Add the generated library to your app. For more details, see Go Mobile's SDK applications and generating bindings.

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 to run a local web proxy that you can use to configure your app's networking libraries.

Side Service

To integrate the SDK as a side service, follow these steps:

1. Define IPC mechanism: Choose an inter-process communication (IPC) mechanism (for example, sockets, standard I/O).
2. Build the service: Create a Go binary that includes the server-side of the IPC and used the SDK.
   • Examples: Outline Electron backend code, Outline Windows Client backend build, Outline Linux Client backend build.
3. Bundle the service: Include the Go binary in your application bundle.
   • Examples: Outline Windows Client, Outline Linux Client
4. Start the service: Launch the Go binary as a subprocess from your application.
   • Example: Outline Electron Clients
5. Service Calls: Add code to your app for communication with the service.

Go Library

To integrate the Outline SDK as a Go library, you can directly import it into your Go application. See the API Reference for what's available.

This approach is suitable for both command-line and GUI-based applications. You can build GUI-based applications in Go with frameworks like Wails, Fyne.io, Qt for Go, or Go Mobile app.

For examples, see x/examples.

Generated C Library

This approach is suited for applications that require C bindings. It is similar to the Generated Mobile Library approach, where you need to first create a Go library to generate bindings for.

Steps:

1. Create a Go library: Create a Go package that wraps the SDK functionalities you need. Functions to be exported must be marked with //export, as described in the cgo documentation.
2. Generate C library: Use go build with the appropriate -buildmode flag. Anternatively, you can use SWIG.
3. Integrate into your app: Add the generated C library to your application, according to your build system.

Tentative Roadmap

This launch is currently in Beta. Most of the code is not new. It's the same code that is currently being used by the production Outline Client and Server. The SDK repackages code from outline-ss-server and outline-go-tun2socks in a way that is easier to reuse and extend.

Features

• Network-level libraries

  • IP Device abstraction (v0.0.2)
  • IP Device implementation based on go-tun2socks (LWIP) (v0.0.2)
  • UDP handler to fallback to DNS-over-TCP (v0.0.2)
  • DelegatePacketProxy for runtime PacketProxy replacement (v0.0.2)

• Proxy protocols

  • TCP and UDP Dialers (v0.0.2)
  • Shadowsocks wrappers and Dialers (reference) (v0.0.2)
  • SOCKS5 StreamDialer (reference) (v0.0.6)
  • SOCKS5 PacketDialer (coming soon)
  • HTTP Connect (coming soon)

• Transport protocols

  • Stream (TCP) split (reference) (v0.0.6)
  • TLS connection wrapper and StreamDialer (reference)

• Name resolution

  • Resilient DNS (coming soon)
  • Encrypted DNS (coming soon)

• Integration resources

  • For Mobile apps
    • Library to run a local SOCKS5 or HTTP-Connect proxy (source, example Go usage, example mobile usage).
    • Documentation on how to integrate the SDK into mobile apps
    • Connectivity Test mobile app (iOS and Android) using Capacitor
  • For Go apps
    • Connectivity Test example Wails graphical app
    • Connectivity Test example command-line app (source)
    • Outline Client example command-line app (source)
    • Page fetch example command-line app (source)
    • Local proxy example command-line app (source)