@pickleball/expo-sdk 0.2.0 → 1.0.0

package/src/resume-policy.ts

@@ -0,0 +1,85 @@
+/**
+ * Luật quyết định khi nối lại một phiên server còn giữ cho máy này.
+ *
+ * Chuyển từ apps/device-streamer (src/resume-policy.ts) vào SDK để app đối tác
+ * không phải học lại từng cái bẫy đã đo được trên fleet.
+ *
+ * Vì sao cần tách riêng: bản đầu coi MỌI thất bại là "phiên đã chết" và bỏ cuộc
+ * vĩnh viễn sau đúng một lần thử. Hệ quả: máy khởi động lại lúc wifi chưa kịp
+ * lên là mất luôn cơ hội nối lại — đúng ca hay gặp nhất, vì máy vừa mở nguồn
+ * thì wifi luôn lên chậm hơn app.
+ *
+ * Phân biệt hai loại thất bại là toàn bộ giá trị của module này:
+ * - "gone": server nói phiên không còn. Thử lại bao nhiêu cũng vô ích.
+ * - "retry": mạng chưa lên, server trục trặc, phản hồi méo. Phiên có thể vẫn sống.
+ *
+ * Nghi ngờ thì chọn "retry": đoán nhầm thành "gone" là mất phiên vĩnh viễn (link
+ * xem đổi, VOD tách đôi); đoán nhầm thành "retry" chỉ tốn vài request, và đã có
+ * lưới server dọn phiên mồ côi.
+ */
+
+/** Phân loại phản hồi HTTP của endpoint refresh. */
+export type ResumeVerdict = "ok" | "gone" | "retry";
+
+/**
+ * 404 = phiên biến mất hẳn. 409 = phiên đã kết thúc (mọi namespace trả
+ * SESSION_CONFLICT cho thao tác trên phiên ended, và grant bị thay cũng là 409).
+ * 410 = Gone theo chuẩn HTTP. Mọi mã khác — kể cả 401/403 — đều là "retry":
+ * token có thể được cấp lại ở nhịp sau, và một lỗi xác thực tạm thời không phải
+ * bằng chứng phiên đã chết.
+ */
+export function classifyResumeStatus(status: number): ResumeVerdict {
+  if (status === 404 || status === 409 || status === 410) return "gone";
+  if (status >= 200 && status < 300) return "ok";
+  return "retry";
+}
+
+/**
+ * Nhịp thử lại. Nhịp đầu 1 giây vì ca điển hình là "app mở trước khi wifi lên" —
+ * chờ vài giây là xong. Trần 15 giây để một máy chết hẳn không nện server mãi;
+ * số lần thì KHÔNG giới hạn: thà thử mãi còn hơn mất phiên, và lưới server
+ * (1 giờ cho live, 30 phút cho standby) mới là thứ quyết định lúc nào bỏ cuộc.
+ */
+export const RESUME_RETRY_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 15_000];
+
+export function resumeRetryDelayMs(attempt: number): number {
+  const index = Math.min(Math.max(attempt, 0), RESUME_RETRY_DELAYS_MS.length - 1);
+  return RESUME_RETRY_DELAYS_MS[index];
+}
+
+/**
+ * Bất kỳ ai định TẠO PHIÊN MỚI tự động (AutoTournament của fleet, useStandbySession
+ * của app đối tác) phải NHƯỜNG khi còn phiên chờ nhận lại — nhìn CẢ HAI nguồn.
+ *
+ * Bản đầu chỉ nhìn serverSession (heartbeat, về SAU vài giây); adoptableSessionId
+ * (dấu trên đĩa) có mặt ngay từ lúc engine khởi động xong. Khe hở vài giây đó là
+ * đủ để một lượt arm nổ súng trước AutoResume: hoặc đụng chốt marker (app đứng
+ * màn LỖI), hoặc tệ hơn — lách qua trong đúng cửa sổ race và tạo phiên chờ THỨ
+ * HAI đè phiên live cũ (đo thật đêm 18/08/2026).
+ */
+export function resumeBlocksArm(input: {
+  adoptableSessionId: string | null;
+  serverSessionId: string | null;
+  engineSessionId: string | null;
+}): boolean {
+  if (input.engineSessionId !== null) return false;
+  return input.adoptableSessionId !== null || input.serverSessionId !== null;
+}
+
+/** Quy ước externalSessionId của lượt start NHẬN LẠI — engine chỉ cho lượt này qua chốt marker. */
+export function resumeExternalSessionId(sessionId: string): string {
+  return `resume-${sessionId}`;
+}
+
+/**
+ * Grant nối lại chỉ được tiêu thụ cho ĐÚNG phiên nó được cấp. AutoResume có thể
+ * bắn nhiều lượt (retry, đổi nguồn); không kiểm khớp thì một grant cũ còn sót có
+ * thể bị lượt start của phiên khác nuốt — engine nối vào nhầm phiên, đúng loại lỗi
+ * âm thầm khó truy nhất.
+ */
+export function resumeGrantMatches(
+  externalSessionId: string | undefined,
+  grantSessionId: string,
+): boolean {
+  return externalSessionId === resumeExternalSessionId(grantSessionId);
+}

package/src/resume.ts

@@ -0,0 +1,132 @@
+import type {
+  LivestreamSessionProvider,
+  SdkSessionGrant,
+  StartLivestreamInput,
+} from "./contracts";
+import { isSdkRemoteConfig } from "./contracts";
+import { classifyResumeStatus, resumeGrantMatches } from "./resume-policy";
+import { isFiniteNumber, isRecord, isTelemetryCredentials, type Fetch } from "./session-grant";
+
+/**
+ * Nhận lại phiên sau khi app bị kill/mở lại — phần PROVIDER.
+ *
+ * Kịch bản: máy đang phát, app biến mất (sụp nguồn, OEM giết, vuốt tắt). Server
+ * còn giữ phiên. Lần mở sau engine thấy dấu trên đĩa (adoptableSessionId) nhưng
+ * KHÔNG có grant trong bộ nhớ — phải hỏi server cấp lại credentials của đúng
+ * phiên đó rồi start bằng grant ấy thay vì tạo phiên mới. Link xem và VOD nhờ
+ * vậy liền một mạch.
+ */
+
+export type ResumeAttempt =
+  | { kind: "grant"; grant: SdkSessionGrant; live: boolean }
+  | { kind: "gone" }
+  | { kind: "retry" };
+
+export interface ResumableSessionProvider extends LivestreamSessionProvider {
+  /** Đặt grant cho lượt start kế tiếp có externalSessionId `resume-<id>`. */
+  adoptResumeGrant(grant: SdkSessionGrant): void;
+  /** Hỏi server cấp lại grant cho phiên còn sống. */
+  resume(sessionId: string): Promise<ResumeAttempt>;
+}
+
+/**
+ * Bọc provider: `start()` ưu tiên grant nhận lại nếu khớp phiên, còn lại tạo phiên
+ * mới như thường. Grant chờ nằm trong closure (không biến module) nên hai provider
+ * trong cùng app không dẫm nhau.
+ */
+export function withResume(
+  provider: LivestreamSessionProvider,
+  resume: (sessionId: string) => Promise<ResumeAttempt>,
+): ResumableSessionProvider {
+  let pending: SdkSessionGrant | null = null;
+  return {
+    bootstrap: provider.bootstrap.bind(provider),
+    refresh: provider.refresh.bind(provider),
+    end: provider.end.bind(provider),
+    publish: provider.publish?.bind(provider),
+    unpublish: provider.unpublish?.bind(provider),
+    async start(input: StartLivestreamInput) {
+      const grant = pending;
+      if (grant && resumeGrantMatches(input.externalSessionId, grant.sessionId)) {
+        pending = null;
+        return grant;
+      }
+      return provider.start(input);
+    },
+    adoptResumeGrant(grant) {
+      pending = grant;
+    },
+    resume,
+  };
+}
+
+/** Biến phản hồi refresh (đầy đủ) thành grant; méo → null để caller coi là retry. */
+export function grantFromRefreshPayload(data: unknown): SdkSessionGrant | null {
+  if (
+    !isRecord(data) ||
+    typeof data.sessionId !== "string" ||
+    typeof data.serverUrl !== "string" ||
+    typeof data.participantToken !== "string" ||
+    !isFiniteNumber(data.tokenExpiresAt) ||
+    !isTelemetryCredentials(data.telemetry) ||
+    !isSdkRemoteConfig(data.config)
+  ) {
+    return null;
+  }
+  return {
+    sessionId: data.sessionId,
+    serverUrl: data.serverUrl,
+    participantToken: data.participantToken,
+    playbackUrl: typeof data.playbackUrl === "string" ? data.playbackUrl : null,
+    tokenExpiresAt: data.tokenExpiresAt,
+    telemetry: data.telemetry,
+    config: data.config,
+  };
+}
+
+export interface HttpResumeFetcherOptions {
+  /** URL endpoint refresh của phiên — namespace nào cũng được, miễn trả grant đầy đủ + status. */
+  url(sessionId: string): string;
+  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+  fetch?: Fetch;
+  timeoutMs?: number;
+}
+
+/**
+ * Gọi endpoint refresh để dựng lại grant. Trả về PHÂN LOẠI chứ không phải
+ * null-cho-mọi-thứ (xem resume-policy): mất mạng/5xx/méo = retry, 404/409/410 =
+ * gone. Chỉ phát tiếp khi server xác nhận phiên ĐANG live — thiếu trường status
+ * coi như không phát: để camera tự lên sóng nhầm còn tệ hơn là chờ một lệnh nữa.
+ */
+export function createHttpResumeFetcher(
+  options: HttpResumeFetcherOptions,
+): (sessionId: string) => Promise<ResumeAttempt> {
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  return async (sessionId) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const headers =
+        typeof options.headers === "function" ? await options.headers() : (options.headers ?? {});
+      const response = await fetchImplementation(options.url(sessionId), {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify({}),
+        signal: controller.signal,
+      });
+      const verdict = classifyResumeStatus(response.status);
+      if (verdict !== "ok") return { kind: verdict };
+      const envelope = (await response.json().catch(() => null)) as { data?: unknown } | null;
+      const grant = grantFromRefreshPayload(envelope?.data);
+      if (!grant) return { kind: "retry" };
+      const status = (envelope?.data as { status?: unknown }).status;
+      return { kind: "grant", grant, live: status === "live" };
+    } catch {
+      // fetch ném = mất mạng. Đây CHÍNH LÀ ca hay gặp nhất khi máy vừa mở nguồn.
+      return { kind: "retry" };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}

package/src/rtmp-room-adapter.ts

@@ -5,6 +5,7 @@ import type {
   RoomConnection,
   RoomEvent,
 } from "./engine";
+import { VIDEO_BITRATE_BPS } from "./uplink-check";
 
 /**
  * Trạng thái từ tầng RTMP native (trùng NativeRtmpStatus của @pickleball/rtmp-native).
@@ -14,6 +15,13 @@ export type RtmpStatus =
   | { readonly status: "disconnected"; readonly reason?: string }
   | { readonly status: "error"; readonly code: string; readonly message: string };
 
+/** Phản hồi băng thông từ native (trùng NativeRtmpBandwidth của rtmp-native). */
+export interface RtmpBandwidth {
+  /** false = encoder đang đẩy nhanh hơn đường truyền chịu được. */
+  readonly sufficient: boolean;
+  readonly videoBitrate: number;
+}
+
 /**
  * Dấu hiệu để UI biết render nguồn nào. LiveKit trả về một track object; RTMP
  * không có "track" ở JS (khung hình đi thẳng trong native), nên trả marker này
@@ -25,7 +33,23 @@ export interface RtmpPreviewMarker {
 
 /** Bề mặt native mà adapter cần — tiêm vào để test được không cần thiết bị thật. */
 export interface NativeRtmpBindings {
-  prepare(options: { quality: 720 | 1080; landscape: boolean }): Promise<void>;
+  prepare(options: {
+    quality: 720 | 1080;
+    landscape: boolean;
+    /** fps mong muốn (24 tiết kiệm băng thông, 30 mặc định) — thiếu = native tự chọn. */
+    frameRate?: 24 | 30 | 60;
+    /**
+     * Camera mở ngay từ đầu. Thiếu = native dùng camera sau mặc định. Đặt ở đây
+     * thay vì gọi selectCamera sau prepare để không phải mở camera hai lần.
+     */
+    cameraId?: string;
+  }): Promise<void>;
+  /**
+   * Xin quyền camera/mic bằng API quyền thuần (PermissionsAndroid, ...).
+   * Không có thì engine rơi về getUserMedia của WebRTC — thứ mở camera thật
+   * và đụng HaishinKit trên máy Android chỉ cho một camera mở cùng lúc.
+   */
+  requestPermissions?(): Promise<boolean>;
   /** Hướng cầm máy hiện tại — cùng nguồn mà LiveKitRoomAdapter dùng. */
   isLandscape?(): boolean;
   connect(options: {
@@ -42,6 +66,10 @@ export interface NativeRtmpBindings {
   setVideoBitrate(bitsPerSecond: number): Promise<void>;
   dispose(): Promise<void>;
   addStatusListener(listener: (event: RtmpStatus) => void): { remove(): void };
+  /** Optional: bản native cũ chưa phát onBandwidth thì adapter bỏ qua thích ứng. */
+  addBandwidthListener?(
+    listener: (event: RtmpBandwidth) => void,
+  ): { remove(): void };
 }
 
 /**
@@ -49,10 +77,50 @@ export interface NativeRtmpBindings {
  * (720p 3–6 Mbps, 1080p 6–9 Mbps). Thấp hơn khoảng này thì thể thao chuyển động
  * nhanh như pickleball bị bể khối rất rõ.
  */
-const VIDEO_BITRATE: Record<720 | 1080, number> = {
-  720: 3_500_000,
-  1080: 6_000_000,
-};
+const VIDEO_BITRATE: Readonly<Record<720 | 1080, number>> = VIDEO_BITRATE_BPS;
+
+/**
+ * Thích ứng bitrate theo phản hồi băng thông của native (thay cho BWE mà
+ * WebRTC cho không). VIDEO_BITRATE là TRẦN, không phải điều kiện: máy/mạng
+ * không kham nổi 6 Mbps thì hạ dần xuống tới sàn và VẪN PHÁT — thà mờ còn
+ * hơn đứng hình hay tràn hàng đợi rồi rớt luồng.
+ *
+ * Hạ nhanh (×0.7 mỗi tín hiệu nghẽn ~2s), hồi chậm (×1.15 sau
+ * RECOVER_AFTER_SUFFICIENT tín hiệu tốt liên tiếp ~10s) — mô hình AIMD.
+ */
+export const BITRATE_FLOOR = 800_000;
+export const DEGRADE_FACTOR = 0.7;
+export const RECOVER_FACTOR = 1.15;
+export const RECOVER_AFTER_SUFFICIENT = 5;
+
+export interface AdaptiveBitrateState {
+  readonly current: number;
+  readonly ceiling: number;
+  readonly sufficientStreak: number;
+}
+
+/** Bước chuyển thuần — tách khỏi adapter để test không cần thiết bị. */
+export function nextBitrateState(
+  state: AdaptiveBitrateState,
+  event: Pick<RtmpBandwidth, "sufficient">,
+): AdaptiveBitrateState {
+  if (!event.sufficient) {
+    return {
+      ...state,
+      current: Math.max(BITRATE_FLOOR, Math.round(state.current * DEGRADE_FACTOR)),
+      sufficientStreak: 0,
+    };
+  }
+  const streak = state.sufficientStreak + 1;
+  if (streak < RECOVER_AFTER_SUFFICIENT || state.current >= state.ceiling) {
+    return { ...state, sufficientStreak: Math.min(streak, RECOVER_AFTER_SUFFICIENT) };
+  }
+  return {
+    ...state,
+    current: Math.min(state.ceiling, Math.round(state.current * RECOVER_FACTOR)),
+    sufficientStreak: 0,
+  };
+}
 
 /**
  * Adapter cho mode deliveryMode="device-rtmp".
@@ -65,21 +133,68 @@ const VIDEO_BITRATE: Record<720 | 1080, number> = {
  * dashboard đi đường khác (deviceControl trên Convex) — xem device-agent.
  */
 export class RtmpRoomAdapter implements RoomAdapter {
+  /**
+   * RTMP không tự hồi: native chỉ phát hiện đứt (watchdog iOS / onDisconnect
+   * Android) và báo "disconnected" — không tự quay số lại. Engine thấy cờ này
+   * là chạy vòng redial backoff. Thiếu cờ: phiên ngồi chờ "reconnected" không
+   * bao giờ tới rồi chết network_timeout sau 30s (prod 17/08/2026).
+   */
+  readonly needsManualReconnect = true;
+
   private readonly listeners = new Set<(event: RoomEvent) => void>();
   private nativeSubscription?: { remove(): void };
+  private bandwidthSubscription?: { remove(): void };
   private quality: 720 | 1080 = 1080;
   private connected = false;
+  private prepared = false;
+  /** Khung người dùng chọn trên UI (9:16/16:9) — ưu tiên hơn hướng cầm máy. */
+  private captureOrientation?: CaptureOrientation;
+  private bitrateState?: AdaptiveBitrateState;
+
+  /**
+   * Chỉ tồn tại khi bindings hỗ trợ — engine kiểm tra truthiness để quyết định
+   * fallback về runtime.requestPermissions() (getUserMedia), nên KHÔNG được
+   * khai báo method luôn-có rồi tự fallback bên trong.
+   */
+  readonly requestPermissions?: () => Promise<boolean>;
 
-  constructor(private readonly bindings: NativeRtmpBindings) {}
+  constructor(
+    private readonly bindings: NativeRtmpBindings,
+    private readonly options: { frameRate?: 24 | 30 | 60; cameraId?: string } = {},
+  ) {
+    const request = bindings.requestPermissions?.bind(bindings);
+    if (request) this.requestPermissions = request;
+  }
+
+  /**
+   * Phần tuỳ chọn của prepare(). Giữ dạng spread có điều kiện: truyền
+   * `frameRate: undefined` xuống Expo Record là ghi đè mặc định của native
+   * bằng null chứ không phải "bỏ qua trường".
+   */
+  private prepareOverrides(): { frameRate?: 24 | 30 | 60; cameraId?: string } {
+    return {
+      ...(this.options.frameRate !== undefined
+        ? { frameRate: this.options.frameRate }
+        : {}),
+      ...(this.options.cameraId !== undefined
+        ? { cameraId: this.options.cameraId }
+        : {}),
+    };
+  }
 
   async preparePreview(quality: 720 | 1080): Promise<RtmpPreviewMarker> {
     this.quality = quality;
-    // Mặc định ngang khi binding không cài: sân pickleball quay ngang là chính,
-    // và đó cũng là kích thước capture mặc định của HaishinKit.
+    // Khung người dùng chọn (9:16/16:9) là nguồn sự thật; chỉ khi chưa chọn mới
+    // đoán theo hướng cầm máy (mặc định ngang: sân pickleball quay ngang là
+    // chính, và đó cũng là kích thước capture mặc định của HaishinKit).
     await this.bindings.prepare({
       quality,
-      landscape: this.bindings.isLandscape?.() ?? true,
+      landscape: this.captureOrientation
+        ? this.captureOrientation === "landscape"
+        : (this.bindings.isLandscape?.() ?? true),
+      ...this.prepareOverrides(),
     });
+    this.prepared = true;
     // Khung hình do PickleballRtmpPreviewView vẽ ở tầng native; JS chỉ cần biết
     // "đã có preview và là nguồn RTMP" để chọn đúng component hiển thị.
     return { kind: "rtmp" };
@@ -106,6 +221,13 @@ export class RtmpRoomAdapter implements RoomAdapter {
       publish: input.publish !== false,
     });
     this.connected = true;
+    // Trần theo mức chất lượng của phiên; phản hồi băng thông sẽ điều chỉnh
+    // trong khoảng [BITRATE_FLOOR, trần] mà không bao giờ chặn phát.
+    this.bitrateState = {
+      current: VIDEO_BITRATE[this.quality],
+      ceiling: VIDEO_BITRATE[this.quality],
+      sufficientStreak: 0,
+    };
   }
 
   async setPublishing(enabled: boolean) {
@@ -115,6 +237,7 @@ export class RtmpRoomAdapter implements RoomAdapter {
   async disconnect(_stopTracks?: boolean) {
     if (!this.connected) return;
     this.connected = false;
+    this.bitrateState = undefined;
     await this.bindings.disconnect();
   }
 
@@ -147,9 +270,19 @@ export class RtmpRoomAdapter implements RoomAdapter {
     await this.bindings.setVideoBitrate(bitsPerSecond);
   }
 
-  async setCaptureOrientation(_orientation: CaptureOrientation) {
-    // Khung hình do camera quyết định; không đổi giữa luồng RTMP vì sẽ buộc
-    // khởi động lại encoder và làm thủng segment HLS.
+  async setCaptureOrientation(orientation: CaptureOrientation) {
+    this.captureOrientation = orientation;
+    // Đang preview (chưa phát): prepare lại để đổi khung 9:16 ↔ 16:9 ngay —
+    // native chỉ đổi screen.frame + gắn lại camera, encoder chưa chạy.
+    // Đã kết nối thì KHÔNG đổi giữa luồng: buộc khởi động lại encoder và làm
+    // thủng segment HLS; lựa chọn sẽ áp cho lần prepare kế tiếp.
+    if (this.prepared && !this.connected) {
+      await this.bindings.prepare({
+        quality: this.quality,
+        landscape: orientation === "landscape",
+        ...this.prepareOverrides(),
+      });
+    }
   }
 
   subscribe(listener: (event: RoomEvent) => void) {
@@ -160,6 +293,11 @@ export class RtmpRoomAdapter implements RoomAdapter {
         if (mapped) this.emit(mapped);
       });
     }
+    if (!this.bandwidthSubscription && this.bindings.addBandwidthListener) {
+      this.bandwidthSubscription = this.bindings.addBandwidthListener((event) =>
+        this.handleBandwidth(event),
+      );
+    }
     return () => {
       this.listeners.delete(listener);
     };
@@ -168,11 +306,25 @@ export class RtmpRoomAdapter implements RoomAdapter {
   async dispose() {
     this.nativeSubscription?.remove();
     this.nativeSubscription = undefined;
+    this.bandwidthSubscription?.remove();
+    this.bandwidthSubscription = undefined;
     this.listeners.clear();
     this.connected = false;
+    this.bitrateState = undefined;
     await this.bindings.dispose();
   }
 
+  private handleBandwidth(event: RtmpBandwidth) {
+    const state = this.bitrateState;
+    if (!this.connected || !state) return;
+    const next = nextBitrateState(state, event);
+    this.bitrateState = next;
+    if (next.current !== state.current) {
+      // Fire-and-forget: chỉnh bitrate lỗi thì giữ mức cũ chứ không rớt luồng.
+      void this.bindings.setVideoBitrate(next.current).catch(() => undefined);
+    }
+  }
+
   private emit(event: RoomEvent) {
     for (const listener of this.listeners) listener(event);
   }