connectivity test app (without android)

x/examples/outline-connectivity-app/.gitignore

@@ -0,0 +1,9 @@
+output
+node_modules
+.yarn/cache
+.yarn/sdks
+.yarn/unplugged
+.yarn/install-state.gz
+.pnp.*
+.DS_Store
+.vscode/settings.json

x/examples/outline-connectivity-app/.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "arcanis.vscode-zipfs"
+  ]
+}

x/examples/outline-connectivity-app/.vscode/settings.example.json

@@ -0,0 +1,8 @@
+{
+  "typescript.tsdk": "x/examples/outline-connectivity-app/.yarn/sdks/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "search.exclude": {
+    "**/.yarn": true,
+    "**/.pnp.*": true
+  }
+}

x/examples/outline-connectivity-app/.yarnrc.yml

@@ -0,0 +1,7 @@
+plugins:
+  - path: .yarn/plugins/@yarnpkg/plugin-typescript.cjs
+    spec: "@yarnpkg/plugin-typescript"
+  - path: .yarn/plugins/@yarnpkg/plugin-workspace-tools.cjs
+    spec: "@yarnpkg/plugin-workspace-tools"
+
+yarnPath: .yarn/releases/yarn-3.6.1.cjs

x/examples/outline-connectivity-app/README.md

@@ -0,0 +1,128 @@
+# Outline Connectivity App
+
+## Overview
+
+This is a simple cross-platform app to test connectivity to Outline servers, using the Outline SDK. It is built with [Wails](https://wails.app/) and [Capacitor](https://capacitorjs.com/).
+
+### Architecture
+
+The overarching goal of this application is to demonstrate how the Outline SDK enables you to write each line of business logic only once across all platforms.
+
+We achieve this by first writing a [`shared_backend`](./shared_backend) package in Go - which contains the UDP/TCP connectivity test implemented with the Outline SDK - and a [`shared_frontend`](./shared_frontend/) GUI built with TypeScript and Lit which contains an HTML form for entering the required connectivity test parameters.
+
+Each platform used - [Wails](https://wails.app/) for desktop and [Capacitor](https://capacitorjs.com/) for mobile - then has a thin wrapper around the shared code that handles the platform-specific details.
+
+```mermaid
+graph LR
+  subgraph Shared
+    A["shared_backend"]
+    B["shared_frontend"]
+  end
+  subgraph Build
+    C["SharedBackend.xcframework"]
+    D["SharedBackend.aar"]
+  end
+  subgraph app_desktop
+    H["index.html"]
+    G["DesktopBackend.Invoke()"]
+  end
+  subgraph app_mobile
+    subgraph ios
+      I["MobileBackendPlugin.swift"]
+    end
+    subgraph android
+      J["MobileBackendPlugin.kt"]
+    end
+    K["index.html"]
+    L["MobileBackend.Invoke()"]
+  end
+
+  A -.-> |gomobile| C
+  A -.-> |gomobile| D
+  A --> G
+  B --> H
+  B --> K
+  C --> I
+  D --> J
+  I --> L
+  J --> L
+  L --> K
+  G --> H
+
+  style K fill:blue;
+  style H fill:blue;
+```
+
+For Mobile, we use `gomobile` to build the `shared_backend` package into a `xcframework` for iOS and an `aar` for Android. You can see this for yourself by running `yarn shared_backend build`. For Desktop, Wails simply refers to the `shared_backend` package directly.
+
+Then we implement a small piece of middleware called `Invokable` that enables the frontend to speak to the backend via the given platform.
+
+```ts
+interface Invokable {
+  Invoke(parameters: { method: string; input: string; }): Promise<{ result: string; errors: string[] }>
+}
+```
+
+In an `Invoke` call, the frontend passes a `method` and `input` to the backend, and the backend returns a `result` and `errors`. The `method` is the name of a function in the `shared_backend` package, and the `input` is a JSON string that is passed to that function. The `result` is a JSON string returned by the function, and the `errors` are any errors that occurred during the function call.
+
+With this simple Invokable binding to whatever native backend the frontend is running on, we can then build the frontend convenience bindings with typing and examples, like so:
+
+```ts
+@customElement("app-main")
+export class AppMain extends LitElement {
+  backend = SharedBackend.from(MobileBackend)
+
+  render() {
+    // this.backend.connectivityTest's input is a ConnectivityTestParameters interface, output is a ConnectivityTestResult[]
+    return html`<connectivity-test-page .onSubmit=${this.backend.connectivityTest} />`;
+  }
+}
+```
+
+
+## Development
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/)
+- [Yarn](https://yarnpkg.com/)
+- [Go](https://golang.org/)
+- [Wails](https://wails.app/)
+- [Capacitor](https://capacitorjs.com/)
+- [CocoaPods](https://cocoapods.org/)
+- [Xcode](https://developer.apple.com/xcode/)
+- [Android SDK](https://developer.android.com/studio)
+- [Android NDK](https://developer.android.com/ndk)
+
+### Setup
+
+1. Clone this repo
+1. `cd` into the repo
+1. if using xcode, copy the `settings.example.json` to `settings.json` if it looks good to you
+1. `yarn`
+
+If at any point you run into issues during development, try `yarn reset`.
+
+### Development Server
+
+`yarn watch`
+
+### Build
+
+> NOTE: You will need credentials to build for iOS and Android. Talk to @jigsaw.
+
+`yarn build`
+
+### Needed Improvements
+
+1. **\[P1\]** android (in progress)
+1. **\[P1\]** read browser language on load (and only localize once)
+
+### Current Issues
+
+1. <span style="color:red">**\[P0\]** add server url to an ENV var somehow... pretty dumb capacitor...</span>
+1. **\[P1\]** Results dialog isn't rendering as intended (likely because of the `{ all: initial }`)
+1. **\[P2\]** `cap ___ run` breaks (have workaround and [issue filed](https://github.com/ionic-team/capacitor/issues/6791))
+1. **\[P2\]** Create a logo for the app
+1. **\[P2\]** Introducing some kind of tracing into the test
+1. <span style="color:gray">**\[P3\]** spurious lit localize TS error</span>

x/examples/outline-connectivity-app/app_desktop/app.go

@@ -0,0 +1,55 @@
+// Copyright 2023 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"github.com/Jigsaw-Code/outline-sdk/x/examples/outline-connectivity-app/shared_backend"
+)
+
+// App struct
+type App struct {
+	ctx context.Context
+}
+
+// NewApp creates a new App application struct
+func NewApp() *App {
+	return &App{}
+}
+
+// startup is called when the app starts. The context is saved
+// so we can call the runtime methods
+func (a *App) startup(ctx context.Context) {
+	a.ctx = ctx
+}
+
+func (a *App) Invoke(input shared_backend.CallInputMessage) shared_backend.CallOutputMessage {
+	rawInputMessage, marshallingError := json.Marshal(input)
+
+	if marshallingError != nil {
+		return shared_backend.CallOutputMessage{Result: "", Errors: []string{"Invoke: failed to serialize raw invocation input"}}
+	}
+
+	var outputMessage shared_backend.CallOutputMessage
+
+	unmarshallingError := json.Unmarshal(shared_backend.SendRawCall(rawInputMessage), &outputMessage)
+
+	if unmarshallingError != nil {
+		return shared_backend.CallOutputMessage{Result: "", Errors: []string{"Invoke: failed to parse invocation result"}}
+	}
+
+	return outputMessage
+}

x/examples/outline-connectivity-app/app_desktop/app.ts

@@ -0,0 +1,34 @@
+// Copyright 2023 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// backend
+import * as SharedBackend from "shared_backend";
+import * as DesktopBackend from "./generated/wailsjs/go/main/App";
+
+// frontend
+import * as SharedFrontend from "shared_frontend";
+import { LitElement, html } from "lit";
+import { customElement } from "lit/decorators.js";
+
+SharedFrontend.registerAllElements();
+
+// main
+@customElement("app-main")
+export class AppMain extends LitElement {
+  backend = SharedBackend.from(DesktopBackend);
+
+  render() {
+    return html`<connectivity-test-page .onSubmit=${this.backend.connectivityTest} />`;
+  }
+}

x/examples/outline-connectivity-app/app_desktop/generated/wailsjs/go/main/App.d.ts

@@ -0,0 +1,5 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+import {shared_backend} from '../models';
+
+export function Invoke(arg1:shared_backend.CallInputMessage):Promise<shared_backend.CallOutputMessage>;

x/examples/outline-connectivity-app/app_desktop/generated/wailsjs/go/main/App.js

@@ -0,0 +1,7 @@
+// @ts-check
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export function Invoke(arg1) {
+  return window['go']['main']['App']['Invoke'](arg1);
+}

x/examples/outline-connectivity-app/app_desktop/generated/wailsjs/go/models.ts

@@ -0,0 +1,33 @@
+export namespace shared_backend {
+
+	export class CallInputMessage {
+	    method: string;
+	    input: string;
+
+	    static createFrom(source: any = {}) {
+	        return new CallInputMessage(source);
+	    }
+
+	    constructor(source: any = {}) {
+	        if ('string' === typeof source) source = JSON.parse(source);
+	        this.method = source["method"];
+	        this.input = source["input"];
+	    }
+	}
+	export class CallOutputMessage {
+	    result: string;
+	    errors: string[];
+
+	    static createFrom(source: any = {}) {
+	        return new CallOutputMessage(source);
+	    }
+
+	    constructor(source: any = {}) {
+	        if ('string' === typeof source) source = JSON.parse(source);
+	        this.result = source["result"];
+	        this.errors = source["errors"];
+	    }
+	}
+
+}
+

x/examples/outline-connectivity-app/app_desktop/generated/wailsjs/runtime/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@wailsapp/runtime",
+  "version": "2.0.0",
+  "description": "Wails Javascript runtime library",
+  "main": "runtime.js",
+  "types": "runtime.d.ts",
+  "scripts": {
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wailsapp/wails.git"
+  },
+  "keywords": [
+    "Wails",
+    "Javascript",
+    "Go"
+  ],
+  "author": "Lea Anthony <lea.anthony@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/wailsapp/wails/issues"
+  },
+  "homepage": "https://github.com/wailsapp/wails#readme"
+}