@raydiant/playlist-window-manager 0.29.1 → 0.30.0

package/src/SurfaceBroker.test.ts

@@ -0,0 +1,278 @@
+import SurfaceBroker, {
+  SurfaceRefusal,
+  SURFACE_FIRST_FRAME_DEADLINE_MS,
+  SURFACE_OPEN_DEADLINE_MS,
+} from './SurfaceBroker';
+import { VideoOptions, VideoSurface } from './surfaces';
+import { createFakeSurfaceHost, createLogger } from './testUtils';
+
+jest.useFakeTimers();
+
+// Lets promise callbacks run under fake timers.
+const settle = async () => {
+  for (let i = 0; i < 20; i += 1) {
+    await Promise.resolve();
+  }
+};
+
+const options = (label: string): VideoOptions => ({
+  url: `https://cdn.test/${label}.mp4`,
+  bounds: { x: 0, y: 0, width: 1920, height: 1080 },
+  muted: true,
+  label,
+});
+
+function setup(hostOpts?: Parameters<typeof createFakeSurfaceHost>[0]) {
+  const host = createFakeSurfaceHost(hostOpts);
+  const warn = jest.fn();
+  const broker = new SurfaceBroker(host.surfaces, createLogger({ warn }));
+  const onEvent = jest.fn();
+  const onRefused = jest.fn();
+  const open = (windowId: string) =>
+    broker.open(windowId, options(windowId), onEvent, onRefused);
+  const opens = () => host.calls.filter((c) => c.method === 'openVideo');
+  const refusalsLogged = (reason: string) =>
+    warn.mock.calls.filter(
+      ([, context]) => context && context.reason === reason
+    ).length;
+  return {
+    host,
+    broker,
+    warn,
+    onEvent,
+    onRefused,
+    open,
+    opens,
+    refusalsLogged,
+  };
+}
+
+// Records the outcome of an open without letting a rejection go unhandled.
+function track(promise: Promise<VideoSurface>) {
+  const result: { surface?: VideoSurface; reason?: string } = {};
+  promise.then(
+    (surface) => {
+      result.surface = surface;
+    },
+    (err: SurfaceRefusal) => {
+      result.reason = err.reason;
+    }
+  );
+  return result;
+}
+
+describe('a refusal is answered', () => {
+  test.each(['no_decoder', 'unsupported'] as const)(
+    'the host refusing %s is a refusal with that reason, logged once',
+    async (reason) => {
+      const { open, refusalsLogged } = setup({ refuse: reason });
+
+      const result = track(open('w1'));
+      await settle();
+
+      expect(result.reason).toBe(reason);
+      expect(refusalsLogged(reason)).toBe(1);
+    }
+  );
+
+  test('an open past its deadline is refused, and a late handle is closed at once', async () => {
+    const { host, open, refusalsLogged } = setup({ hang: true });
+
+    const result = track(open('w1'));
+    await settle();
+    expect(result.reason).toBeUndefined();
+
+    jest.advanceTimersByTime(SURFACE_OPEN_DEADLINE_MS);
+    await settle();
+    expect(result.reason).toBe('deadline');
+    expect(refusalsLogged('deadline')).toBe(1);
+
+    host.releaseHung();
+    await settle();
+    const lateId = host.lastId();
+    expect(
+      host.calls.filter((c) => c.id === lateId).map((c) => c.method)
+    ).toEqual(['close']);
+    expect(host.liveIds()).toEqual([]);
+  });
+
+  test('a first frame past its deadline closes the surface and is refused', async () => {
+    const { host, open, onRefused, onEvent, refusalsLogged } = setup();
+
+    const result = track(open('w1'));
+    await settle();
+    expect(result.surface).toBeDefined();
+
+    jest.advanceTimersByTime(SURFACE_FIRST_FRAME_DEADLINE_MS);
+    await settle();
+
+    expect(onRefused).toHaveBeenCalledWith('deadline');
+    expect(refusalsLogged('deadline')).toBe(1);
+    expect(host.liveIds()).toEqual([]);
+
+    // A first frame after the deadline is not forwarded.
+    host.emit(host.lastId(), {
+      type: 'first_frame',
+      width: 1920,
+      height: 1080,
+      durationS: 10,
+    });
+    expect(onEvent).not.toHaveBeenCalled();
+  });
+
+  test('a first frame in time is forwarded and stops the deadline', async () => {
+    const { host, open, onRefused, onEvent } = setup();
+
+    track(open('w1'));
+    await settle();
+    const frame = {
+      type: 'first_frame' as const,
+      width: 1920,
+      height: 1080,
+      durationS: 10,
+    };
+    host.emit(host.lastId(), frame);
+    jest.advanceTimersByTime(SURFACE_FIRST_FRAME_DEADLINE_MS * 2);
+    await settle();
+
+    expect(onEvent).toHaveBeenCalledWith(frame);
+    expect(onRefused).not.toHaveBeenCalled();
+    expect(host.liveIds()).toEqual([host.lastId()]);
+  });
+
+  test('no_decoder while a close is pending is tried once more after it', async () => {
+    const { host, broker, open, opens, refusalsLogged } = setup();
+
+    const first = track(open('w1'));
+    await settle();
+    const surface = first.surface as VideoSurface;
+    // A close the host takes 100 ms to finish.
+    const realClose = surface.close.bind(surface);
+    (surface as { close: () => Promise<void> }).close = () =>
+      new Promise((resolve) => setTimeout(() => resolve(realClose()), 100));
+
+    // The second open reaches the host before the close starts, and the host
+    // answers no_decoder while the close is still pending.
+    let rejectOpen: (err: Error) => void = () => undefined;
+    const realOpen = host.surfaces.openVideo;
+    host.surfaces.openVideo = (opts: VideoOptions) => {
+      host.surfaces.openVideo = realOpen;
+      host.calls.push({ method: 'openVideo', args: [opts], seq: 0 });
+      return new Promise((_, reject) => {
+        rejectOpen = reject;
+      });
+    };
+    const second = track(open('w2'));
+    await settle();
+    broker.close('w1');
+    rejectOpen(new Error('no_decoder'));
+    await settle();
+    expect(opens()).toHaveLength(2);
+
+    jest.advanceTimersByTime(100);
+    await settle();
+
+    expect(opens()).toHaveLength(3);
+    expect(second.surface).toBeDefined();
+    expect(refusalsLogged('no_decoder')).toBe(0);
+  });
+
+  test('no_decoder with no close pending is refused at once', async () => {
+    const { open, opens, refusalsLogged } = setup({ refuse: 'no_decoder' });
+
+    const result = track(open('w1'));
+    await settle();
+
+    expect(result.reason).toBe('no_decoder');
+    expect(opens()).toHaveLength(1);
+    expect(refusalsLogged('no_decoder')).toBe(1);
+  });
+});
+
+describe('two at most; an open waits for a close', () => {
+  test('a third open with none closing or leaving is refused with no host call', async () => {
+    const { host, open, opens, refusalsLogged } = setup();
+
+    track(open('w1'));
+    track(open('w2'));
+    await settle();
+    const third = track(open('w3'));
+    await settle();
+
+    expect(third.reason).toBe('no_decoder');
+    expect(opens()).toHaveLength(2);
+    expect(refusalsLogged('no_decoder')).toBe(1);
+    expect(host.violations).toEqual([]);
+  });
+
+  test('a third open with a surface leaving waits for its close', async () => {
+    const { host, broker, open, opens } = setup();
+
+    track(open('w1'));
+    track(open('w2'));
+    await settle();
+    broker.leaving('w1');
+    const third = track(open('w3'));
+    await settle();
+    expect(opens()).toHaveLength(2);
+    expect(third.surface).toBeUndefined();
+
+    await broker.close('w1');
+    await settle();
+
+    expect(opens()).toHaveLength(3);
+    expect(third.surface).toBeDefined();
+    expect(host.violations).toEqual([]);
+  });
+
+  test('a third open with a close in flight waits for that close', async () => {
+    const { host, broker, open, opens } = setup();
+
+    const first = track(open('w1'));
+    track(open('w2'));
+    await settle();
+    const surface = first.surface as VideoSurface;
+    const realClose = surface.close.bind(surface);
+    (surface as { close: () => Promise<void> }).close = () =>
+      new Promise((resolve) => setTimeout(() => resolve(realClose()), 100));
+
+    broker.close('w1');
+    const third = track(open('w3'));
+    await settle();
+    expect(opens()).toHaveLength(2);
+
+    jest.advanceTimersByTime(100);
+    await settle();
+
+    expect(opens()).toHaveLength(3);
+    expect(third.surface).toBeDefined();
+    expect(host.violations).toEqual([]);
+  });
+
+  test('an open given up before the host answers closes the handle', async () => {
+    const { host, broker, open } = setup({ hang: true });
+
+    const result = track(open('w1'));
+    await settle();
+    await broker.close('w1');
+    host.releaseHung();
+    await settle();
+
+    expect(result.reason).toBe('closed');
+    expect(host.liveIds()).toEqual([]);
+  });
+
+  test('close is idempotent and closeAll closes every surface', async () => {
+    const { host, broker, open } = setup();
+
+    track(open('w1'));
+    track(open('w2'));
+    await settle();
+    await broker.close('w1');
+    await broker.close('w1');
+    await broker.closeAll();
+
+    expect(host.liveIds()).toEqual([]);
+    expect(host.calls.filter((c) => c.method === 'close')).toHaveLength(2);
+  });
+});

package/src/SurfaceBroker.ts

@@ -0,0 +1,281 @@
+import { Logger } from './types';
+import {
+  SurfaceHost,
+  VideoEvent,
+  VideoOptions,
+  VideoSurface,
+  VideoRefusalReason,
+} from './surfaces';
+
+// How long the host's openVideo may take to resolve.
+export const SURFACE_OPEN_DEADLINE_MS = 2000;
+// From openVideo resolving to first_frame. Inside the 30-second ready timeout,
+// with time left for the app to fall back to <video> and still be ready.
+export const SURFACE_FIRST_FRAME_DEADLINE_MS = 10000;
+// One playing and one prepared.
+export const MAX_LIVE_SURFACES = 2;
+// How long a surface swap waits for the incoming window's first paint, and
+// how long showing a surface may take, when closeWindowDelayMs is not set:
+// 1000 ms, the closeWindowDelayMs the player passes.
+export const DEFAULT_SURFACE_SWAP_DELAY_MS = 1000;
+// SurfaceHost.showAfterRevealMs when the player sets none. On the Signage
+// Stick (Fire OS 8.4, Amazon WebView 136, portrait) the WebView takes about
+// 80-120 ms longer than a surface to put a reveal on screen: 60 ms left the
+// theme trailing the picture by up to 35 ms, and 100 ms put it ahead by up
+// to 54 ms.
+export const DEFAULT_SHOW_AFTER_REVEAL_MS = 80;
+
+export type SurfaceRefusalReason = Exclude<VideoRefusalReason, 'not_offered'>;
+
+// Rejects an open. `closed` means the window gave the surface up before the
+// open finished, which needs no answer to the app.
+export class SurfaceRefusal extends Error {
+  constructor(public reason: SurfaceRefusalReason | 'closed') {
+    super(`Video surface refused: ${reason}`);
+    this.name = 'SurfaceRefusal';
+    Object.setPrototypeOf(this, SurfaceRefusal.prototype);
+  }
+}
+
+interface Entry {
+  windowId: string;
+  label?: string;
+  surface: VideoSurface | null;
+  state: 'opening' | 'open' | 'closing' | 'closed';
+  // A swap has started and this surface's close follows.
+  leaving: boolean;
+  firstFrameTimer: ReturnType<typeof setTimeout> | null;
+  closePromise: Promise<void> | null;
+  // Resolves once the surface is closed, or the open is given up.
+  closed: Promise<void>;
+  markClosed: () => void;
+}
+
+// The host rejects with an Error whose message is a short machine code.
+const reasonOf = (err: unknown): SurfaceRefusalReason => {
+  if (err instanceof SurfaceRefusal && err.reason !== 'closed') {
+    return err.reason;
+  }
+  const code =
+    typeof err === 'string'
+      ? err
+      : err && typeof err === 'object'
+      ? (err as { message?: unknown }).message
+      : undefined;
+  return code === 'no_decoder' ? 'no_decoder' : 'unsupported';
+};
+
+// Holds every video surface one window manager has open, so the manager never
+// asks the host for more than two at once and opens the next only after the
+// outgoing one has closed, leaving the host an idle decoder to reuse.
+export default class SurfaceBroker {
+  private entries: Record<string, Entry> = {};
+
+  constructor(private host: SurfaceHost, private logger: Logger) {}
+
+  // Resolves once the host has opened a hidden surface. Rejects with a
+  // SurfaceRefusal. A first frame later than its deadline closes the surface
+  // and reports it through onRefused instead.
+  public async open(
+    windowId: string,
+    opts: VideoOptions,
+    onEvent: (e: VideoEvent) => void,
+    onRefused: (reason: SurfaceRefusalReason) => void
+  ): Promise<VideoSurface> {
+    let markClosed = () => undefined as void;
+    const closed = new Promise<void>((resolve) => {
+      markClosed = resolve;
+    });
+    const entry: Entry = {
+      windowId,
+      label: opts.label,
+      surface: null,
+      state: 'opening',
+      leaving: false,
+      firstFrameTimer: null,
+      closePromise: null,
+      closed,
+      markClosed,
+    };
+    this.entries[windowId] = entry;
+
+    // A close pending or a surface leaving is waited for, so the host has an
+    // idle decoder by the time it is asked. Two live with neither is a refusal
+    // the host is never asked for.
+    for (;;) {
+      this.throwIfGivenUp(entry);
+      const pending = this.pendingCloses(entry);
+      if (pending.length > 0) {
+        await Promise.all(pending);
+        continue;
+      }
+      if (this.liveOthers(entry).length >= MAX_LIVE_SURFACES) {
+        throw this.refuse(entry, 'no_decoder');
+      }
+      break;
+    }
+
+    let surface: VideoSurface;
+    let retried = false;
+    for (;;) {
+      this.throwIfGivenUp(entry);
+      try {
+        surface = await this.openWithDeadline(opts);
+        break;
+      } catch (err) {
+        this.throwIfGivenUp(entry);
+        const reason = reasonOf(err);
+        const pending = this.pendingCloses(entry);
+        // The one retry: a close the page sent is still pending.
+        if (reason === 'no_decoder' && !retried && pending.length > 0) {
+          retried = true;
+          await Promise.all(pending);
+          continue;
+        }
+        throw this.refuse(entry, reason);
+      }
+    }
+
+    if (entry.state === 'closed') {
+      surface.close();
+      throw new SurfaceRefusal('closed');
+    }
+
+    entry.surface = surface;
+    entry.state = 'open';
+    entry.firstFrameTimer = setTimeout(() => {
+      entry.firstFrameTimer = null;
+      this.warnRefusal(entry, 'deadline');
+      this.close(windowId);
+      onRefused('deadline');
+    }, SURFACE_FIRST_FRAME_DEADLINE_MS);
+
+    surface.onEvent((e) => {
+      if (entry.state !== 'open') return;
+      if (e.type === 'first_frame') {
+        if (!entry.firstFrameTimer) return;
+        clearTimeout(entry.firstFrameTimer);
+        entry.firstFrameTimer = null;
+      }
+      onEvent(e);
+    });
+
+    return surface;
+  }
+
+  // A swap has started for this window's surface; its close follows.
+  public leaving(windowId: string): void {
+    const entry = this.entries[windowId];
+    if (entry) entry.leaving = true;
+  }
+
+  // Closes the window's surface, or gives up its open. Idempotent.
+  public close(windowId: string): Promise<void> {
+    const entry = this.entries[windowId];
+    if (!entry) return Promise.resolve();
+    if (entry.closePromise) return entry.closePromise;
+
+    if (entry.firstFrameTimer) {
+      clearTimeout(entry.firstFrameTimer);
+      entry.firstFrameTimer = null;
+    }
+
+    const surface = entry.surface;
+    if (!surface) {
+      // Still opening: open() closes a handle that resolves from here on.
+      this.forget(entry);
+      return Promise.resolve();
+    }
+
+    entry.state = 'closing';
+    entry.closePromise = surface
+      .close()
+      .catch((err) => {
+        this.logger.warn(
+          `Failed to close video surface for window '${windowId}' with '${
+            err && err.message
+          }'`,
+          { windowId, presentationId: entry.label }
+        );
+      })
+      .then(() => this.forget(entry));
+    return entry.closePromise;
+  }
+
+  public async closeAll(): Promise<void> {
+    await Promise.all(Object.keys(this.entries).map((id) => this.close(id)));
+  }
+
+  // A window's hole opened or closed.
+  public onHole(open: boolean): void {
+    this.host.onHole(open);
+  }
+
+  private openWithDeadline(opts: VideoOptions): Promise<VideoSurface> {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        settled = true;
+        reject(new SurfaceRefusal('deadline'));
+      }, SURFACE_OPEN_DEADLINE_MS);
+
+      new Promise<VideoSurface>((r) => r(this.host.openVideo(opts))).then(
+        (surface) => {
+          if (settled) {
+            // A late handle never holds a decoder nobody uses.
+            surface.close();
+            return;
+          }
+          settled = true;
+          clearTimeout(timer);
+          resolve(surface);
+        },
+        (err) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+
+  private throwIfGivenUp(entry: Entry) {
+    if (entry.state === 'closed') {
+      throw new SurfaceRefusal('closed');
+    }
+  }
+
+  private liveOthers(entry: Entry): Entry[] {
+    return Object.keys(this.entries)
+      .map((id) => this.entries[id])
+      .filter((e) => e !== entry && e.state !== 'closed');
+  }
+
+  private pendingCloses(entry: Entry): Promise<void>[] {
+    return this.liveOthers(entry)
+      .filter((e) => e.state === 'closing' || e.leaving)
+      .map((e) => e.closed);
+  }
+
+  private refuse(entry: Entry, reason: SurfaceRefusalReason) {
+    this.forget(entry);
+    this.warnRefusal(entry, reason);
+    return new SurfaceRefusal(reason);
+  }
+
+  private warnRefusal(entry: Entry, reason: SurfaceRefusalReason) {
+    this.logger.warn(
+      `Sending 'video_refused' to window '${entry.windowId}', reason=${reason}`,
+      { windowId: entry.windowId, presentationId: entry.label, reason }
+    );
+  }
+
+  private forget(entry: Entry) {
+    entry.state = 'closed';
+    if (this.entries[entry.windowId] === entry) {
+      delete this.entries[entry.windowId];
+    }
+    entry.markClosed();
+  }
+}

package/src/__snapshots__/PlaylistWindowManager.test.ts.snap

@@ -0,0 +1,26 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`no surface host a two-presentation swap keeps the renderer call sequence 1`] = `
+Array [
+  "createWindow w1",
+  "muteWindow w1",
+  "loadWindow w1",
+  "sendMessageString w1 render",
+  "createWindow w2",
+  "muteWindow w2",
+  "loadWindow w2",
+  "sendMessageString w2 render",
+  "showWindow w2",
+  "unMuteWindow w2",
+  "sendMessageString w2 play",
+  "showWindow w1",
+  "unMuteWindow w1",
+  "muteWindow w2",
+  "sendMessageString w1 play",
+  "createWindow w3",
+  "muteWindow w3",
+  "loadWindow w3",
+  "sendMessageString w3 render",
+  "removeWindow w2",
+]
+`;

package/src/index.ts

@@ -11,3 +11,4 @@ export * from './PresentationWindow';
 export { PresentationWindow };
 
 export * from './types';
+export * from './surfaces';

package/src/surfaces.ts

@@ -0,0 +1,82 @@
+// The video contract's types, copied verbatim (exported, and kept out of
+// prettier so the copy stays diffable against the source) from the device
+// video contract that the Signage Stick's host builds to. A surface is a video
+// the host draws outside the browser, under the page, in a hole the page
+// clears.
+
+// prettier-ignore
+export type VideoOptions = {
+  url: string;                   // fetched through the native cache like any page request
+  bounds: Rect;                  // the hole the page clears, in CSS px of the main frame,
+                                 // converted with the view's own page scale, never the
+                                 // platform density; the host fills it edge to edge. The
+                                 // page re-sends them on its resize
+  fit?: 'cover' | 'stretch';     // cover (default): the picture fills the hole, cropped;
+                                 // stretch: scaled to it. A letterbox is the page's: it
+                                 // sizes the hole to the picture from first_frame
+  loop?: boolean;                // default false
+  muted?: boolean;               // default true; the page unmutes when it owns the audio
+  label?: string;                // the page's own name for the surface, written beside
+                                 // the host's id in its logs and events
+};
+
+// prettier-ignore
+export interface VideoSurface {
+  readonly id: number;           // the host's handle, for logs
+  show(opts?: { fadeMs?: number }): Promise<void>;  // last shown is on top. Resolves
+                                                    // once on screen, after any fade
+  hide(opts?: { fadeMs?: number }): Promise<void>;  // the picture stays decoded, so a
+                                                    // later show costs no first frame
+  play(): Promise<void>;         // from the current position; a new surface starts at 0
+  pause(): Promise<void>;
+  seek(seconds: number): Promise<void>;
+  setBounds(r: Rect): Promise<void>;
+  setMuted(m: boolean): Promise<void>;
+  close(): Promise<void>;        // frees the decoder slot. Idempotent, and every call on
+                                 // a closed handle resolves and does nothing
+  onEvent(fn: (e: VideoEvent) => void): void;       // one listener; the last set wins.
+                                 // Events raised before any listener is set are kept
+                                 // and handed to the first one, in order
+}
+
+// prettier-ignore
+export type Rect = { x: number; y: number; width: number; height: number };
+// prettier-ignore
+export type VideoEvent =
+  | { type: 'first_frame'; width: number; height: number; durationS: number | null }
+                                 // null: a stream, or a container that states no length
+  | { type: 'playing' }          // after play, and after a stall ends
+  | { type: 'stalled' }          // the decoder is waiting on bytes
+  | { type: 'ended' }            // never fires with loop
+  | { type: 'error'; reason: 'fetch' | 'decode' | 'unsupported' | 'closed' };
+
+// What the player hands the window manager when its host can draw a surface.
+export interface SurfaceHost {
+  // The host's openVideo, bound by the player.
+  openVideo(opts: VideoOptions): Promise<VideoSurface>;
+  // A window's hole opened or closed. Called once with true and once with
+  // false per surface, so the player can count open holes.
+  onHole(open: boolean): void;
+  // On a swap whose incoming app opened its hole while hidden, how long
+  // after the incoming frame's reveal its surface is shown, so the picture
+  // and the frame's theme reach the screen together. A surface puts a change
+  // on screen sooner than the WebView, by an amount that depends on the
+  // device, so the player sets this per device class. Default 80.
+  showAfterRevealMs?: number;
+}
+
+// The messages an app sends to ask for, size, reveal and give up a surface.
+export const VIDEO_REQUESTS = [
+  'open_video',
+  'video_bounds',
+  'video_hole_open',
+  'close_video',
+];
+
+// Why the window manager answered an app's request with video_refused. The
+// app keeps <video> on every one.
+export type VideoRefusalReason =
+  | 'no_decoder'
+  | 'unsupported'
+  | 'deadline'
+  | 'not_offered';