Mobile relay v2: Durable Object transport with direct Stack auth and end-to-end session admission

.github/workflows/mobile-relay.yml

@@ -0,0 +1,123 @@
+# CI/CD for the mobile relay service (workers/mobile-relay).
+#
+# Manual runs test and deploy the service to Cloudflare. `wrangler deploy`
+# applies the Durable Object migrations declared in wrangler.toml atomically
+# with the code upload.
+#
+# The `target` input picks the worker: `prod` (default) deploys
+# `cmux-mobile-relay` on mr.cmux.dev; `dev` deploys `cmux-mobile-relay-dev`
+# from wrangler.dev.toml on workers.dev.
+#
+# Required repository secrets (deploy job):
+#   CLOUDFLARE_API_TOKEN   API token with Workers Scripts:Edit on the account
+#   CLOUDFLARE_ACCOUNT_ID  the Cloudflare account id
+#
+# The worker holds no secrets: connect auth verifies Stack access tokens
+# with the public project configuration in wrangler[.dev].toml [vars].
+
+name: mobile-relay
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Worker to deploy"
+        type: choice
+        options:
+          - prod
+          - dev
+        default: prod
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    defaults:
+      run:
+        working-directory: workers/mobile-relay
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+
+      # Wrangler requires Node >= 22; the Blacksmith ubuntu-2404 image ships
+      # Node 20, so pin it explicitly.
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Generated protocol drift check
+        run: bun run generate:check
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Unit tests
+        run: bun test
+
+      - name: Wrangler dry-run build
+        run: bunx wrangler deploy --dry-run --outdir dist
+
+  deploy:
+    if: github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main'
+    needs: test
+    runs-on: ${{ vars.LINUX_RUNNER || 'blacksmith-4vcpu-ubuntu-2404' }}
+    concurrency:
+      group: mobile-relay-deploy
+      cancel-in-progress: false
+    defaults:
+      run:
+        working-directory: workers/mobile-relay
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+
+      # Wrangler requires Node >= 22; Blacksmith ubuntu-2404 ships Node 20.
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Check Cloudflare secrets
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          missing=()
+          [ -n "$CLOUDFLARE_API_TOKEN" ] || missing+=(CLOUDFLARE_API_TOKEN)
+          [ -n "$CLOUDFLARE_ACCOUNT_ID" ] || missing+=(CLOUDFLARE_ACCOUNT_ID)
+          if [ "${#missing[@]}" -gt 0 ]; then
+            echo "::error::Mobile relay deploy needs repository secrets ${missing[*]}." \
+              "Create an API token with Workers Scripts:Edit on the Cloudflare" \
+              "account and add both secrets in repo Settings -> Secrets and" \
+              "variables -> Actions (see workers/mobile-relay/README.md)."
+            exit 1
+          fi
+
+      - name: Deploy (applies DO migrations atomically)
+        # The target reaches the shell via env, never template interpolation,
+        # and any value other than the two known targets fails closed.
+        run: |
+          case "$DEPLOY_TARGET" in
+            dev) bunx wrangler deploy --config wrangler.dev.toml ;;
+            prod) bunx wrangler deploy ;;
+            *) echo "::error::Unsupported deployment target '$DEPLOY_TARGET'"; exit 1 ;;
+          esac
+        env:
+          DEPLOY_TARGET: ${{ inputs.target }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/DiagnosticEventPresentation.swift

@@ -219,6 +219,7 @@ public struct DiagnosticEventPresentation: Sendable {
         case .automatic: localized("diagnostics.connectionMethod.automatic", defaultValue: "Auto-Connect (Iroh)")
         case .tailscale: localized("diagnostics.connectionMethod.tailscale", defaultValue: "Tailscale Only")
         case .direct: localized("diagnostics.connectionMethod.direct", defaultValue: "Direct")
+        case .relay: localized("diagnostics.connectionMethod.relay", defaultValue: "Relay")
         }
     }
 

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/DiagnosticTaxonomy.swift

@@ -854,6 +854,7 @@ public enum DiagnosticConnectionMethod: Int, Sendable, Codable, CaseIterable {
     case automatic = 0
     case tailscale = 1
     case direct = 2
+    case relay = 3
 }
 
 /// High-level lifecycle state for one phone-controlled Simulator stream.

Packages/Shared/CMUXMobileCore/Sources/CMUXMobileCore/Resources/Localizable.xcstrings

@@ -120,6 +120,23 @@
         }
       }
     },
+    "diagnostics.connectionMethod.relay": {
+      "extractionState": "manual",
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Relay"
+          }
+        },
+        "ja": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "リレー"
+          }
+        }
+      }
+    },
     "diagnostics.connectionMethod.tailscale": {
       "extractionState": "manual",
       "localizations": {

Packages/Shared/CmuxRelayTransport/Package.swift

@@ -0,0 +1,34 @@
+// swift-tools-version: 6.0
+
+import PackageDescription
+
+let package = Package(
+    name: "CmuxRelayTransport",
+    platforms: [
+        .iOS(.v18),
+        .macOS(.v14),
+    ],
+    products: [
+        .library(
+            name: "CmuxRelayTransport",
+            targets: ["CmuxRelayTransport"]
+        ),
+    ],
+    dependencies: [
+        .package(path: "../CMUXMobileCore"),
+    ],
+    targets: [
+        .target(
+            name: "CmuxRelayTransport",
+            dependencies: [
+                .product(name: "CMUXMobileCore", package: "CMUXMobileCore"),
+            ],
+            swiftSettings: [.swiftLanguageMode(.v6)]
+        ),
+        .testTarget(
+            name: "CmuxRelayTransportTests",
+            dependencies: ["CmuxRelayTransport"],
+            swiftSettings: [.swiftLanguageMode(.v6)]
+        ),
+    ]
+)

Packages/Shared/CmuxRelayTransport/Sources/CmuxRelayTransport/Generated/RelayProtocolGenerated.swift

@@ -0,0 +1,147 @@
+// GENERATED by workers/mobile-relay/tools/generate.ts — DO NOT EDIT.
+// Source of truth: workers/mobile-relay/src/protocol.ts (Effect Schema).
+// Regenerate with `bun run generate` in workers/mobile-relay.
+
+import Foundation
+
+/// Wire constants shared with the relay worker. See src/protocol.ts for the
+/// full contract (framing, session policy, close codes).
+public enum RelayProtocol {
+    public static let version = 2
+    public static let dataFrameType: UInt8 = 1
+    public static let dataHeaderBytes = 5
+    public static let hostSessionID: UInt32 = 0
+    public static let channelRPC: UInt8 = 0
+    public static let channelTerminal: UInt8 = 1
+    public static let channelSimulator: UInt8 = 2
+    public static let channelCredit: UInt8 = 3
+    public static let maxDataPayloadBytes = 262144
+    public static let maxControlBytes = 4096
+    public static let sessionMaxAgeMilliseconds = 3600000
+    public static let pingText = "ping"
+    public static let pongText = "pong"
+    public static let stackAccessHeaderName = "x-cmux-stack-access"
+    public static let roleHeaderName = "x-cmux-role"
+    public static let hostDeviceHeaderName = "x-cmux-host-device"
+    public static let deviceHeaderName = "x-cmux-device"
+    public static let connectPath = "/v1/connect"
+    public static let defaultRelayURL = "wss://mr.cmux.dev/v1/connect"
+    public static let byeSuperseded = "superseded"
+    public static let byeExpired = "expired"
+    public static let byeProtocolError = "protocol_error"
+    public static let byeAtCapacity = "at_capacity"
+    public static let byeHostClosed = "host_closed"
+}
+
+public enum RelayRole: String, Codable, Sendable {
+    case host
+    case client
+}
+
+public struct RelayWelcome: Codable, Sendable, Equatable {
+    public static let type = "welcome"
+    public var t: String = Self.type
+    public var v: Int
+    public var role: RelayRole
+    public var sessionId: Int
+    public var deadline: Double
+    public var hostPresent: Bool
+    public init(v: Int, role: RelayRole, sessionId: Int, deadline: Double, hostPresent: Bool) {
+        self.v = v
+        self.role = role
+        self.sessionId = sessionId
+        self.deadline = deadline
+        self.hostPresent = hostPresent
+    }
+}
+
+public struct RelayPeerJoined: Codable, Sendable, Equatable {
+    public static let type = "peer_joined"
+    public var t: String = Self.type
+    public var sessionId: Int
+    public var deviceId: String
+    public init(sessionId: Int, deviceId: String) {
+        self.sessionId = sessionId
+        self.deviceId = deviceId
+    }
+}
+
+public struct RelayPeerLeft: Codable, Sendable, Equatable {
+    public static let type = "peer_left"
+    public var t: String = Self.type
+    public var sessionId: Int
+    public var reason: String
+    public init(sessionId: Int, reason: String) {
+        self.sessionId = sessionId
+        self.reason = reason
+    }
+}
+
+public struct RelayRefreshAck: Codable, Sendable, Equatable {
+    public static let type = "refresh_ack"
+    public var t: String = Self.type
+    public var deadline: Double
+    public init(deadline: Double) {
+        self.deadline = deadline
+    }
+}
+
+public struct RelayBye: Codable, Sendable, Equatable {
+    public static let type = "bye"
+    public var t: String = Self.type
+    public var code: String
+    public var reason: String
+    public init(code: String, reason: String) {
+        self.code = code
+        self.reason = reason
+    }
+}
+
+public struct RelayRefresh: Codable, Sendable, Equatable {
+    public static let type = "refresh"
+    public var t: String = Self.type
+    public var accessToken: String
+    public init(accessToken: String) {
+        self.accessToken = accessToken
+    }
+}
+
+public struct RelayCloseSession: Codable, Sendable, Equatable {
+    public static let type = "close_session"
+    public var t: String = Self.type
+    public var sessionId: Int
+    public init(sessionId: Int) {
+        self.sessionId = sessionId
+    }
+}
+
+/// Every message the relay can send. Decode with `RelayServerMessage.decode(_:)`;
+/// unknown or malformed input returns nil (a same-version relay never sends it).
+public enum RelayServerMessage: Sendable, Equatable {
+    case welcome(RelayWelcome)
+    case peerJoined(RelayPeerJoined)
+    case peerLeft(RelayPeerLeft)
+    case refreshAck(RelayRefreshAck)
+    case bye(RelayBye)
+
+    private struct Probe: Decodable { let t: String }
+
+    public static func decode(_ data: Data) -> RelayServerMessage? {
+        let decoder = JSONDecoder()
+        guard let probe = try? decoder.decode(Probe.self, from: data) else { return nil }
+        switch probe.t {
+        case RelayWelcome.type:
+            return (try? decoder.decode(RelayWelcome.self, from: data)).map(RelayServerMessage.welcome)
+        case RelayPeerJoined.type:
+            return (try? decoder.decode(RelayPeerJoined.self, from: data)).map(RelayServerMessage.peerJoined)
+        case RelayPeerLeft.type:
+            return (try? decoder.decode(RelayPeerLeft.self, from: data)).map(RelayServerMessage.peerLeft)
+        case RelayRefreshAck.type:
+            return (try? decoder.decode(RelayRefreshAck.self, from: data)).map(RelayServerMessage.refreshAck)
+        case RelayBye.type:
+            return (try? decoder.decode(RelayBye.self, from: data)).map(RelayServerMessage.bye)
+        default:
+            return nil
+        }
+    }
+}