@goliapkg/smix 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goliapkg/smix",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Playwright-shape iOS Simulator / Android emulator UI automation SDK for React Native + Expo + Detox-compatible TypeScript test runners.",
   "type": "module",
   "license": "Apache-2.0 OR MIT",

package/src/HttpRunner.ts

@@ -62,6 +62,24 @@ export class HttpSimRuntime implements SmixSimRuntime {
    */
   readonly labelsResolver: LabelsResolver
 
+  /**
+   * v1.0.3 — session id sent as `Session-Id` header on every request
+   * when non-null. Set via {@link setSessionId}; when set, the runner
+   * short-circuits per-request `.activate()` and reuses the cached
+   * XCUIApplication binding. Typically managed by the {@link Session}
+   * class — direct callers rarely need to touch this.
+   */
+  private sessionId: string | null = null
+
+  /**
+   * v1.0.3 — public alias for the wrapped fetch implementation.
+   * Consumed by the {@link Session} class which drives `/session/*`
+   * routes through the same transport.
+   */
+  get fetch(): HttpFetch {
+    return this.fetchImpl
+  }
+
   constructor(
     public readonly baseUrl: string,
     public readonly fetchImpl: HttpFetch = globalThis.fetch as unknown as HttpFetch,
@@ -76,6 +94,15 @@ export class HttpSimRuntime implements SmixSimRuntime {
     }
   }
 
+  /**
+   * v1.0.3 — attach / clear the `Session-Id` header on every subsequent
+   * request. Called by {@link Session.open} / {@link Session.close};
+   * consumers who manage sessions manually can call this directly.
+   */
+  setSessionId(id: string | null): void {
+    this.sessionId = id
+  }
+
   /**
    * v7.7 c1 — direct match-count via dedicated FFI fn (avoid allocating
    * the full ids list when callers only need count). Mirrors Rust
@@ -155,9 +182,15 @@ export class HttpSimRuntime implements SmixSimRuntime {
 
   private async post(path: string, body: unknown): Promise<unknown> {
     const url = `${this.baseUrl}${path}`
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+    }
+    if (this.sessionId !== null) {
+      headers['session-id'] = this.sessionId
+    }
     const resp = await this.fetchImpl(url, {
       method: 'POST',
-      headers: { 'content-type': 'application/json' },
+      headers,
       body: JSON.stringify(body),
     })
     if (!resp.ok) {

package/src/Session.ts

@@ -0,0 +1,134 @@
+// v1.0.3 — Session lifecycle wrapper.
+//
+// Session lifecycle addresses the runner-side "activation storm": pre-
+// v1.0.2 runners called `.activate()` on every request whose
+// `App-Activate: true` header was set, exhausting XCTest process
+// arbitration on long-running gates. Sessions replace that with a
+// one-shot lifecycle — open once, every subsequent request carries
+// the `Session-Id` header, runner reuses its cached XCUIApplication
+// binding, no per-request activation.
+//
+// Consumer flow:
+//
+// ```ts
+// import { Smix, HttpRunnerClient, HttpSimRuntime, HttpSelectorResolver } from '@goliapkg/smix'
+//
+// const runner = new HttpRunnerClient('http://127.0.0.1:22087')
+// const runtime = new HttpSimRuntime(runner)
+// const resolver = new HttpSelectorResolver(runner)
+// const session = await Session.open(runner, 'com.example.app', { activate: true })
+// try {
+//   const app = await Smix.launchApp(bundleId('com.example.app'), runtime, resolver)
+//   // ... use `app` normally; every request carries Session-Id ...
+// } finally {
+//   await session.close()
+// }
+// ```
+
+import type { HttpFetch } from './HttpRunner.js'
+
+interface HttpRunnerLike {
+  readonly baseUrl: string
+  readonly fetch: HttpFetch
+  setSessionId(id: string | null): void
+}
+
+export interface SessionOpenOptions {
+  /** If true, runner calls `.activate()` on the target once at open time. */
+  activate?: boolean
+}
+
+/**
+ * Runner-side session guard. Use `Session.open()` to acquire, always
+ * pair with `session.close()` in a `finally` block.
+ *
+ * While the Session is open, every runner request from the same
+ * `HttpRunnerClient` carries a `Session-Id` header. The runner
+ * short-circuits per-request `.activate()` and reuses the session's
+ * cached binding.
+ */
+export class Session {
+  private constructor(
+    private readonly runner: HttpRunnerLike,
+    public readonly sessionId: string,
+    public readonly activatedOnce: boolean,
+    public readonly serverTimeMs: number,
+  ) {}
+
+  static async open(
+    runner: HttpRunnerLike,
+    bundleId: string,
+    options: SessionOpenOptions = {},
+  ): Promise<Session> {
+    const activate = options.activate ?? false
+    const res = await runner.fetch(`${runner.baseUrl}/session/open`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ bundleId, activate }),
+    })
+    if (!res.ok) {
+      const body = await res.text()
+      throw new Error(`Session.open ${bundleId}: HTTP ${res.status}: ${body}`)
+    }
+    const json = (await res.json()) as {
+      sessionId?: string
+      activatedOnce?: boolean
+      serverTimeMs?: number
+    }
+    if (typeof json.sessionId !== 'string' || json.sessionId.length === 0) {
+      throw new Error(`Session.open ${bundleId}: response missing sessionId`)
+    }
+    runner.setSessionId(json.sessionId)
+    return new Session(
+      runner,
+      json.sessionId,
+      json.activatedOnce ?? false,
+      json.serverTimeMs ?? 0,
+    )
+  }
+
+  /**
+   * Ask the runner to re-issue `.activate()` on the session's cached
+   * binding. Subject to a runner-side 2 s rate limit per session; when
+   * rate-limited, returns `false` (no-op, session still healthy).
+   *
+   * Use when the client detects target-app drift (e.g. tree returned
+   * empty payload, foreground steal by system UI).
+   */
+  async renewActivation(): Promise<boolean> {
+    const res = await this.runner.fetch(
+      `${this.runner.baseUrl}/session/renew-activation`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sessionId: this.sessionId }),
+      },
+    )
+    if (!res.ok) {
+      const body = await res.text()
+      throw new Error(
+        `Session.renewActivation ${this.sessionId}: HTTP ${res.status}: ${body}`,
+      )
+    }
+    const json = (await res.json()) as { ok?: boolean; activated?: boolean }
+    return json.activated ?? false
+  }
+
+  /**
+   * Release the session. Sends `POST /session/close` (idempotent),
+   * clears the `Session-Id` header from the client. Subsequent client
+   * requests go via the legacy per-request rebind path (rate-limited).
+   */
+  async close(): Promise<void> {
+    try {
+      await this.runner.fetch(`${this.runner.baseUrl}/session/close`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sessionId: this.sessionId }),
+      })
+    } finally {
+      // Clear the client header regardless of runner-side outcome.
+      this.runner.setSessionId(null)
+    }
+  }
+}

package/src/index.ts

@@ -74,3 +74,9 @@ export {
   type A11yRole,
   type Rect,
 } from './A11yNode.js'
+
+// v1.0.3 — session lifecycle. Wraps runner-side `/session/*` routes.
+export {
+  Session,
+  type SessionOpenOptions,
+} from './Session.js'