@goliapkg/smix 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goliapkg/smix",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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

@@ -46,7 +46,14 @@ import type { LabelsResolver, SelectorResolver } from './SelectorResolver.js'
 export type HttpFetch = (
   input: string,
   init: { method: 'POST'; headers: Record<string, string>; body: string },
-) => Promise<{ ok: boolean; status: number; json(): Promise<unknown>; text(): Promise<string> }>
+) => Promise<{
+  ok: boolean
+  status: number
+  json(): Promise<unknown>
+  text(): Promise<string>
+  /** v1.0.4 §D7 — optional; used to parse `X-Sim-Health` response header. */
+  headers?: { get(name: string): string | null }
+}>
 
 /**
  * SmixSimRuntime + SelectorResolver wrapper around the smix-runner HTTP
@@ -62,6 +69,32 @@ 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.4 §D7 — setter installed by {@link Session.open} so this
+   * client can push `X-Sim-Health` header transitions back to the
+   * session's state machine. `null` when no session is open (legacy
+   * per-request path).
+   */
+  private sessionStateSetter: ((state: SessionState) => void) | 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 +109,24 @@ 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
+  }
+
+  /**
+   * v1.0.4 §D7 — register a callback the client invokes on every
+   * response that carries `X-Sim-Health`. Session.open() wires this
+   * so consumers can subscribe via `session.on('state', ...)`.
+   */
+  attachSessionState(setter: (state: SessionState) => void): void {
+    this.sessionStateSetter = setter
+  }
+
   /**
    * v7.7 c1 — direct match-count via dedicated FFI fn (avoid allocating
    * the full ids list when callers only need count). Mirrors Rust
@@ -155,11 +206,32 @@ 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),
     })
+    // v1.0.4 §D7 — parse X-Sim-Health header and forward to the
+    // attached session state setter (if any). Runs BEFORE the
+    // ok-check so state transitions are visible on error paths too.
+    const simHealthHeader = resp.headers?.get?.('x-sim-health')
+    if (simHealthHeader && this.sessionStateSetter) {
+      const normalized = simHealthHeader.trim().toLowerCase()
+      if (
+        normalized === 'healthy' ||
+        normalized === 'degraded' ||
+        normalized === 'cycling' ||
+        normalized === 'dead'
+      ) {
+        this.sessionStateSetter(normalized as SessionState)
+      }
+    }
     if (!resp.ok) {
       const text = await resp.text()
       throw new Error(`smix-runner ${path} → HTTP ${resp.status}: ${text}`)
@@ -173,6 +245,9 @@ export class HttpSimRuntime implements SmixSimRuntime {
   }
 }
 
+/** v1.0.4 §D7 — re-export from Session.ts so this file's use compiles. */
+export type SessionState = 'healthy' | 'degraded' | 'cycling' | 'dead'
+
 function base64ToBytes(b64: string): Uint8Array {
   if (typeof globalThis.atob === 'function') {
     const bin = globalThis.atob(b64)

package/src/Session.ts

@@ -0,0 +1,204 @@
+// 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
+  /** v1.0.4 §D7 — optional hook so the client can push state
+   * transitions parsed from `X-Sim-Health` headers back to the
+   * Session. Legacy runners omit the header; state stays `healthy`. */
+  attachSessionState?(setter: (state: SessionState) => void): void
+}
+
+export interface SessionOpenOptions {
+  /** If true, runner calls `.activate()` on the target once at open time. */
+  activate?: boolean
+}
+
+/**
+ * v1.0.4 §D7 — session-scoped sim health classification observed via
+ * the runner's `X-Sim-Health` response header. Consumers subscribe
+ * via {@link Session.on}.
+ */
+export type SessionState = 'healthy' | 'degraded' | 'cycling' | 'dead'
+
+type StateListener = (state: SessionState) => void
+
+/**
+ * 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 {
+  /** v1.0.4 §D7 — current classification; updated on every response
+   * that carries `X-Sim-Health`. */
+  private _state: SessionState = 'healthy'
+  private readonly listeners = new Set<StateListener>()
+
+  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)
+    const session = new Session(
+      runner,
+      json.sessionId,
+      json.activatedOnce ?? false,
+      json.serverTimeMs ?? 0,
+    )
+    // v1.0.4 §D7 — wire the runner's X-Sim-Health parse into this
+    // session's state machine. Legacy runner-clients without the
+    // attachSessionState hook keep working; the session's state stays
+    // 'healthy'.
+    runner.attachSessionState?.((next) => session.updateState(next))
+    return session
+  }
+
+  /** v1.0.4 §D7 — current sim-health classification. */
+  get state(): SessionState {
+    return this._state
+  }
+
+  /** v1.0.4 §D7 — subscribe to state transitions. Returns an
+   * unsubscribe function. */
+  on(_event: 'state', listener: StateListener): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  /** v1.0.4 §D14 — instruct the runner to `terminate()` + `launch()`
+   * the session's cached `XCUIApplication` in place. Preserves the
+   * session id and XCUITest binding. Returns wall-clock ms. */
+  async relaunchApp(): Promise<number> {
+    const res = await this.runner.fetch(
+      `${this.runner.baseUrl}/session/relaunch-app`,
+      {
+        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.relaunchApp ${this.sessionId}: HTTP ${res.status}: ${body}`,
+      )
+    }
+    const json = (await res.json()) as { ok?: boolean; wallMs?: number }
+    return json.wallMs ?? 0
+  }
+
+  private updateState(next: SessionState) {
+    if (next === this._state) return
+    this._state = next
+    for (const listener of this.listeners) {
+      try {
+        listener(next)
+      } catch {
+        // Consumer callbacks must not break the runner-response path.
+      }
+    }
+  }
+
+  /**
+   * 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'