@limrun/api 0.59.0 → 0.60.0

package/src/destination-tunnel.ts

@@ -136,6 +136,8 @@ export type DestinationTunnelClientMessage =
       inspection: DestinationTunnelInspectionConfig;
       /** Default per-flow receive window this client grants. */
       window: number;
+      /** Persistent tunnel this session serves. The instance only echoes it in status. */
+      name?: string;
     }
   | {
       type: 'openOk';
@@ -160,6 +162,8 @@ export type DestinationTunnelServerMessage =
       tunnelId: string;
       selectors: DestinationTunnelSelectorReport[];
       configHash: string;
+      /** The persistent tunnel name the client sent in start, echoed back. */
+      name?: string;
     }
   | {
       type: 'open';
@@ -466,6 +470,7 @@ export function encodeDestinationTunnelClientMessage(message: DestinationTunnelC
         selectors,
         inspection,
         window: readWindow(record),
+        ...readOptionalString(record, 'name'),
       });
     }
     case 'openOk':
@@ -510,6 +515,7 @@ export function decodeDestinationTunnelServerMessage(value: unknown): Destinatio
           readSelectorReport(value, `selector-${index + 1}`),
         ),
         configHash: readString(message, 'configHash'),
+        ...readOptionalString(message, 'name'),
       };
     case 'open':
       return {

package/src/index.ts

@@ -13,6 +13,12 @@ export {
   type DestinationTcpTunnel,
   type DestinationTcpTunnelOptions,
 } from './destination-tunnel-dialer';
+export {
+  runTunnel,
+  type TunnelConnector,
+  type TunnelConnectorEvent,
+  type TunnelConnectorOptions,
+} from './tunnel-connector';
 export {
   decodeDestinationTunnelInspectionSSEEvent,
   deriveDestinationTunnelInspectionURL,

package/src/internal/destination-tunnel-management.ts

@@ -1,6 +1,12 @@
 import { nodeProxyTransport } from './proxy-transport';
 import { deriveDestinationTunnelStatusURL, deriveDestinationTunnelStopURL } from './destination-tunnel-url';
-import { readArray, readNonEmptyString, readRecord, readString } from './destination-tunnel-wire-reader';
+import {
+  readArray,
+  readNonEmptyString,
+  readOptionalString,
+  readRecord,
+  readString,
+} from './destination-tunnel-wire-reader';
 import {
   normalizeDestinationTunnelInspection,
   type DestinationTunnelBindReport,
@@ -11,6 +17,8 @@ import {
 export interface DestinationTunnelStatus {
   active?: {
     tunnelId: string;
+    /** Persistent tunnel the session serves, absent for a one-instance tunnel. */
+    name?: string;
     state: 'starting' | 'ready' | 'stopping';
     selectors: DestinationTunnelSelectorReport[];
     inspection: DestinationTunnelInspectionConfig;
@@ -28,12 +36,16 @@ export interface DestinationTunnelStatus {
   };
 }
 
+/** Status and stop answer at once; a wedged instance must not hold its caller for minutes. */
+const MANAGEMENT_TIMEOUT_MS = 10_000;
+
 export async function getDestinationTunnelStatus(
   apiUrl: string,
   token: string,
 ): Promise<DestinationTunnelStatus> {
   const response = await nodeProxyTransport.fetch(deriveDestinationTunnelStatusURL(apiUrl).toString(), {
     headers: { Authorization: `Bearer ${token}` },
+    signal: AbortSignal.timeout(MANAGEMENT_TIMEOUT_MS),
   });
   if (!response.ok) {
     throw new Error(`getTunnelStatus failed: ${response.status} ${await response.text()}`);
@@ -50,6 +62,7 @@ export async function stopDestinationTunnel(apiUrl: string, token: string, tunne
     {
       method: 'DELETE',
       headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(MANAGEMENT_TIMEOUT_MS),
     },
   );
   if (!response.ok) {
@@ -80,6 +93,7 @@ function readActiveTunnel(value: unknown): NonNullable<DestinationTunnelStatus['
   }
   return {
     tunnelId: readNonEmptyString(active, 'tunnelId'),
+    ...readOptionalString(active, 'name'),
     state,
     selectors: readArray(active, 'selectors').map((selector, index) =>
       readSelectorReport(selector, `selector-${index + 1}`),

package/src/internal/destination-tunnel-url.ts

@@ -1,4 +1,4 @@
-/** The endpoint at `path` under an instance URL, without query or fragment. */
+/** The endpoint at `path` under a base URL, without query or fragment. */
 function deriveEndpointURL(apiUrl: string, path: string): URL {
   const url = new URL(apiUrl);
   if (
@@ -26,7 +26,20 @@ export function deriveAdbHttpURL(adbUrl: string, path: string): URL {
 }
 
 export function deriveDestinationTunnelURL(apiUrl: string): string {
-  const url = deriveEndpointURL(apiUrl, 'tunnel');
+  return webSocketURL(deriveEndpointURL(apiUrl, 'tunnel'));
+}
+
+/** The control WebSocket of a persistent tunnel, under the Limrun API base URL. */
+export function deriveTunnelConnectURL(baseURL: string, organizationId: string, name: string): string {
+  return webSocketURL(
+    deriveEndpointURL(
+      baseURL,
+      `v1/organizations/${encodeURIComponent(organizationId)}/tunnels/${encodeURIComponent(name)}/connect`,
+    ),
+  );
+}
+
+function webSocketURL(url: URL): string {
   url.protocol = url.protocol === 'https:' || url.protocol === 'wss:' ? 'wss:' : 'ws:';
   return url.toString();
 }

package/src/ios-client.ts

@@ -450,21 +450,23 @@ export type AppWatch = {
   stop: () => Promise<void>;
 };
 
-type LaunchAppExitOptions = {
+type LaunchAppCommonOptions = {
+  /** App environment variables. Requires relaunch; reserved keys and existing launch variables are ignored. */
+  env?: Record<string, string>;
   /** Called once when the launched app exits, crashes, or is terminated. */
   onExit?: LaunchAppExitCallback;
 };
 
-type StandardLaunchAppOptions = LaunchAppExitOptions & {
+type StandardLaunchAppOptions = LaunchAppCommonOptions & {
   /**
    * Launch behavior when the app may already be running.
-   * Defaults to `ForegroundIfRunning` server-side.
+   * Defaults to `ForegroundIfRunning`, or `RelaunchIfRunning` when env is nonempty.
    */
   mode?: LaunchAppMode;
   runtime?: undefined;
 };
 
-type RuntimeLaunchAppOptions = LaunchAppExitOptions & {
+type RuntimeLaunchAppOptions = LaunchAppCommonOptions & {
   /** Runtime launches must relaunch so runtime injection is applied. */
   mode?: Extract<LaunchAppMode, 'RelaunchIfRunning'>;
   /** Optional app runtime to attach during launch. */
@@ -2368,7 +2370,11 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
           new Error('launchApp runtime launches require RelaunchIfRunning so runtime injection is applied.'),
         );
       }
-      const mode = launchOptions.runtime ? 'RelaunchIfRunning' : launchOptions.mode;
+      const hasEnvironment = Object.keys(launchOptions.env ?? {}).length > 0;
+      const mode =
+        launchOptions.runtime ? 'RelaunchIfRunning' : (
+          launchOptions.mode ?? (hasEnvironment ? 'RelaunchIfRunning' : undefined)
+        );
       const onExit = launchOptions.onExit;
       const execId = onExit ? generateId() : undefined;
       if (execId && onExit) {
@@ -2378,6 +2384,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         bundleId,
         mode,
         runtime: launchOptions.runtime,
+        env: launchOptions.env,
         execId,
       }).catch((error) => {
         if (execId) {

package/src/ios-launch-environment.ts

@@ -0,0 +1,11 @@
+/** Parse repeatable KEY=VALUE entries; the last occurrence of a key wins. */
+export function parseLaunchEnvironment(entries: string[]): Record<string, string> {
+  const env = Object.fromEntries(
+    entries.map((entry) => {
+      const separator = entry.indexOf('=');
+      if (separator < 1) throw new Error('launch environment must use KEY=VALUE');
+      return [entry.slice(0, separator), entry.slice(separator + 1)];
+    }),
+  );
+  return env;
+}

package/src/resources/android-instances.ts

@@ -88,6 +88,13 @@ export namespace AndroidInstance {
      * 10m, 3h. Default is "0" which means no hard timeout.
      */
     hardTimeout?: string;
+
+    /**
+     * Names a persistent tunnel (`lim tunnel run --name`) that serves this
+     * instance. Creation fails while that tunnel is offline, and the instance
+     * becomes ready only after the tunnel attaches.
+     */
+    tunnel?: string;
   }
 
   export interface Status {
@@ -241,6 +248,13 @@ export namespace AndroidInstanceCreateParams {
     region?: string;
 
     sandbox?: Spec.Sandbox;
+
+    /**
+     * Names a persistent tunnel (`lim tunnel run --name`) that serves this
+     * instance. Creation fails while that tunnel is offline, and the instance
+     * becomes ready only after the tunnel attaches.
+     */
+    tunnel?: string;
   }
 
   export namespace Spec {

package/src/resources/ios-instances.ts

@@ -88,6 +88,13 @@ export namespace IosInstance {
      * 10m, 3h. Default is "0" which means no hard timeout.
      */
     hardTimeout?: string;
+
+    /**
+     * Names a persistent tunnel (`lim tunnel run --name`) that serves this
+     * instance. Creation fails while that tunnel is offline, and the instance
+     * becomes ready only after the tunnel attaches.
+     */
+    tunnel?: string;
   }
 
   export interface Status {
@@ -230,6 +237,13 @@ export namespace IosInstanceCreateParams {
      *   the first.
      */
     region?: string;
+
+    /**
+     * Names a persistent tunnel (`lim tunnel run --name`) that serves this
+     * instance. Creation fails while that tunnel is offline, and the instance
+     * becomes ready only after the tunnel attaches.
+     */
+    tunnel?: string;
   }
 
   export namespace Spec {