feat: add powerSaveBlocker via macOS IOPMAssertion and Linux ScreenSaver inhibition

Author: ipfizz

src/main/api/power-save-blocker.ts

@@ -0,0 +1,121 @@
+import { currentPlatform } from '../../common/platform';
+import { linuxPowerSaveBlockerBackend } from '../platform/linux/linux-power-save-blocker';
+import { cocoaPowerSaveBlockerBackend } from '../platform/macos/cocoa-power-save-blocker';
+
+/**
+ * Block system/display sleep — a drop-in subset of Electron's `powerSaveBlocker`.
+ *
+ * A start/stop REGISTRY (not an emitter): {@link PowerSaveBlockerImpl.start} takes a
+ * blocker `type`, asks the platform backend to {@link PowerSaveBlockerBackend.acquire} a
+ * native blocker, stores it under a fresh incrementing id, and returns that id;
+ * {@link PowerSaveBlockerImpl.stop} releases the native blocker and forgets the id.
+ *
+ * Backends: macOS holds an IOKit `IOPMAssertion` (synchronous, no run loop); Linux holds
+ * an `org.freedesktop.ScreenSaver` inhibition cookie over the deadlock-safe bounded GDBus
+ * method-call primitive (gated behind `SAMBAR_ENABLE_LINUX_POWER_BLOCKER`; a clean no-op
+ * when there is no session bus).
+ *
+ * NO-MECHANISM SEMANTICS (matches Electron, which "always returns an integer identifying
+ * the power save blocker"): when {@link PowerSaveBlockerBackend.acquire} returns null (no
+ * native mechanism — headless CI, or the gate is off), `start()` STILL returns a real id;
+ * the block is simply a documented no-op (`isStarted` true, `stop` true, nothing native to
+ * release). Callers never get -1.
+ */
+
+/** Electron's two power-save-blocker types. */
+export type PowerSaveBlockerType = 'prevent-app-suspension' | 'prevent-display-sleep';
+
+/** An opaque, platform-owned native blocker handle (a CFTypeRef id, a D-Bus cookie, …). */
+export type NativeBlocker = unknown;
+
+/**
+ * The native operations the registry drives — injectable so the id-bookkeeping is
+ * unit-tested with a fake (no FFI). `acquire` returns null when no mechanism is available
+ * (the block becomes a no-op); `release` is best-effort and never throws.
+ */
+export type PowerSaveBlockerBackend = {
+  acquire: (type: PowerSaveBlockerType) => NativeBlocker | null;
+  release: (handle: NativeBlocker) => void;
+};
+
+/** A no-op backend (no native power management on this platform). */
+const noopBackend: PowerSaveBlockerBackend = {
+  acquire: () => null,
+  release: () => undefined,
+};
+
+const platformBackend = (): PowerSaveBlockerBackend => {
+  const platform = currentPlatform();
+  if (platform === 'macos') {
+    return cocoaPowerSaveBlockerBackend;
+  }
+  if (platform === 'linux') {
+    return linuxPowerSaveBlockerBackend;
+  }
+  return noopBackend;
+};
+
+type Entry = { readonly type: PowerSaveBlockerType; readonly nativeHandle: NativeBlocker | null };
+
+export class PowerSaveBlockerImpl {
+  readonly #backend: PowerSaveBlockerBackend;
+  readonly #blockers = new Map<number, Entry>();
+  #nextId = 1;
+
+  /** `backend` is injectable so the registry is unit-testable with a fake (no FFI). */
+  constructor(backend: PowerSaveBlockerBackend = platformBackend()) {
+    this.#backend = backend;
+  }
+
+  /**
+   * Start a power-save blocker of `type`. Returns the blocker id (ALWAYS a real id, even
+   * when no native mechanism is available — the block is then a no-op). Ids are unique for
+   * the process lifetime and never reused.
+   */
+  start(type: PowerSaveBlockerType): number {
+    const id = this.#nextId++;
+    let nativeHandle: NativeBlocker | null = null;
+    try {
+      nativeHandle = this.#backend.acquire(type);
+    } catch {
+      nativeHandle = null; // acquire must never take down the caller; treat as a no-op.
+    }
+    this.#blockers.set(id, { type, nativeHandle });
+    return id;
+  }
+
+  /**
+   * Stop the blocker with `id`, releasing the native handle. Returns true if `id` referred
+   * to a live blocker (now stopped), false for an unknown/already-stopped id.
+   */
+  stop(id: number): boolean {
+    const entry = this.#blockers.get(id);
+    if (entry === undefined) {
+      return false;
+    }
+    this.#blockers.delete(id);
+    if (entry.nativeHandle !== null) {
+      try {
+        this.#backend.release(entry.nativeHandle);
+      } catch {
+        // Best-effort release; the id is already forgotten.
+      }
+    }
+    return true;
+  }
+
+  /** Whether `id` refers to a currently-started blocker. */
+  isStarted(id: number): boolean {
+    return this.#blockers.has(id);
+  }
+
+  /** Clear every blocker without releasing natively. Test-only. */
+  resetForTesting(): void {
+    this.#blockers.clear();
+    this.#nextId = 1;
+  }
+}
+
+/** The power-save-blocker singleton. Drop-in equivalent of Electron's `powerSaveBlocker`. */
+export const powerSaveBlocker = new PowerSaveBlockerImpl();
+export type PowerSaveBlocker = PowerSaveBlockerImpl;

src/main/index.ts

@@ -29,6 +29,7 @@ export {
 export { nativeTheme, type NativeTheme } from './api/native-theme';
 export { Notification, type NotificationOptions } from './api/notification';
 export { type PowerMonitor, powerMonitor } from './api/power-monitor';
+export { type PowerSaveBlocker, powerSaveBlocker } from './api/power-save-blocker';
 export {
   type ProtocolHandler,
   type ProtocolRequest,

src/main/module-list.ts

@@ -69,6 +69,7 @@ export const IMPLEMENTED_MODULES = [
   'nativeTheme',
   'Notification',
   'powerMonitor',
+  'powerSaveBlocker',
   'protocol',
   'safeStorage',
   'screen',

src/main/platform/linux/gdbus-ffi.ts

@@ -34,8 +34,13 @@ const LIBGIO_PATH = 'libgio-2.0.so.0';
 
 /** `GBusType` enum (gio/gioenums.h): STARTER=-1, NONE=0, SYSTEM=1, SESSION=2. */
 export const G_BUS_TYPE_SYSTEM = 1;
+export const G_BUS_TYPE_SESSION = 2;
 /** `GDBusSignalFlags` — no special matching. */
 export const G_DBUS_SIGNAL_FLAGS_NONE = 0;
+/** `GDBusCallFlags` — default. */
+export const G_DBUS_CALL_FLAGS_NONE = 0;
+/** Bounded reply timeout (ms). NEVER `G_MAXINT` — a finite backstop against a peer that never answers. */
+export const DBUS_CALL_TIMEOUT_MS = 5000;
 
 /**
  * ABI shape of `GDBusSignalCallback`:
@@ -77,6 +82,31 @@ export const GDBUS_FFI_SYMBOLS = {
     args: [FFIType.pointer, FFIType.u32],
     returns: FFIType.void,
   },
+  // Bounded REMOTE method call. SAFE on the pumped thread: the reply is read by the
+  // connection's PRIVATE GDBusWorker thread and call_sync awaits it on its OWN private
+  // GMainContext (gdbusconnection.c), so it blocks only THIS thread for a bounded round
+  // trip and never needs Sambar's pump to turn (unlike the clipboard local-pipe read). A
+  // FINITE timeout_msec (NEVER G_MAXINT) is mandatory. The floating `parameters` GVariant
+  // is consumed by the call; the reply tuple is transfer-full (caller g_variant_unref).
+  // (connection, bus_name, object_path, interface_name, method_name, parameters:GVariant*,
+  //  reply_type:GVariantType*|null, flags:GDBusCallFlags, timeout_msec:gint,
+  //  cancellable|null, error:GError**|null) -> GVariant*
+  g_dbus_connection_call_sync: {
+    args: [
+      FFIType.pointer,
+      FFIType.cstring,
+      FFIType.cstring,
+      FFIType.cstring,
+      FFIType.cstring,
+      FFIType.pointer,
+      FFIType.pointer,
+      FFIType.u32,
+      FFIType.i32,
+      FFIType.pointer,
+      FFIType.pointer,
+    ],
+    returns: FFIType.pointer,
+  },
 } as const;
 
 const cache: { ffi: ReturnType<typeof dlopen<typeof GDBUS_FFI_SYMBOLS>> | undefined } = {

src/main/platform/linux/glib-ffi.ts

@@ -107,6 +107,27 @@ export const GLIB_FFI_SYMBOLS = {
     args: [FFIType.pointer],
     returns: FFIType.void,
   },
+  // (value /*GVariant* 'u'*/) -> guint32. ABORTS on a non-u32 — guard with the type string.
+  g_variant_get_uint32: {
+    args: [FFIType.pointer],
+    returns: FFIType.u32,
+  },
+  // (string) -> GVariant* 's' (FLOATING). Builds a D-Bus method arg.
+  g_variant_new_string: {
+    args: [FFIType.cstring],
+    returns: FFIType.pointer,
+  },
+  // (value) -> GVariant* 'u' (FLOATING).
+  g_variant_new_uint32: {
+    args: [FFIType.u32],
+    returns: FFIType.pointer,
+  },
+  // (children /*GVariant**/, n_children /*gsize*/) -> GVariant* tuple (FLOATING; SINKS each
+  //  child's floating ref). Explicit builder avoids the fragile varargs g_variant_new.
+  g_variant_new_tuple: {
+    args: [FFIType.pointer, FFIType.u64],
+    returns: FFIType.pointer,
+  },
 } as const;
 
 const cache: { ffi: ReturnType<typeof dlopen<typeof GLIB_FFI_SYMBOLS>> | undefined } = {

src/main/platform/linux/linux-dbus.ts

@@ -1,8 +1,11 @@
 import { CString, JSCallback, type Pointer } from 'bun:ffi';
 import { cstr } from '../cstr';
 import {
+  DBUS_CALL_TIMEOUT_MS,
   DBUS_SIGNAL_CB_DEF,
+  G_BUS_TYPE_SESSION,
   G_BUS_TYPE_SYSTEM,
+  G_DBUS_CALL_FLAGS_NONE,
   G_DBUS_SIGNAL_FLAGS_NONE,
   loadGDBusFFI,
 } from './gdbus-ffi';
@@ -12,10 +15,14 @@ import {
  *
  * THE RULE (hard-won — a synchronous GIO read once hung CI for hours, see
  * gtk-clipboard.ts): never block Sambar's single pumped thread on a D-Bus reply that
- * only the GMainContext dispatch can deliver. So this module exposes ONLY subscription,
- * never a `*_call_sync`. A subscribed `GDBusSignalCallback` fires on the default
- * GMainContext during ordinary cooperative-pump iterations (gtk-run-loop.ts) — no thread
- * ever blocks for it.
+ * only the GMainContext dispatch can deliver. Signal SUBSCRIPTION never blocks (the
+ * `GDBusSignalCallback` fires on the default GMainContext during ordinary cooperative-pump
+ * iterations, gtk-run-loop.ts). The one method-call helper, {@link callMethodSync}, uses a
+ * BOUNDED `g_dbus_connection_call_sync` whose reply is read by the connection's PRIVATE
+ * GDBusWorker thread and awaited on `call_sync`'s OWN private GMainContext — it stalls the
+ * caller for at most {@link DBUS_CALL_TIMEOUT_MS} and NEVER needs our pump to turn, so it
+ * is categorically unlike the clipboard's local-pipe read (whose reply could only come
+ * from our pump). It is still gated off in CI.
  *
  * `getSystemBus()` is gated behind `SAMBAR_ENABLE_LINUX_POWER` (mirroring the libsecret
  * keyring gate): CI never sets it, so the bus is NEVER touched on the headless runner and
@@ -152,3 +159,76 @@ export const subscribeSignal = (
 export const resetSystemBusCacheForTesting = (): void => {
   cache.systemBus = undefined;
 };
+
+// --- Session bus + bounded method call (powerSaveBlocker) -------------------------------
+
+/**
+ * Whether the live SESSION-bus method-call path is enabled. A SEPARATE flag from the
+ * system-bus power flag, so a developer can enable read-only power-monitor signals without
+ * enabling outbound blocker method calls (different bus, different risk surface). CI never
+ * sets it → the session bus is never touched and blocker `acquire` is a no-op.
+ */
+const liveBlockerEnabled = (): boolean => process.env['SAMBAR_ENABLE_LINUX_POWER_BLOCKER'] === '1';
+
+const sessionCache: { sessionBus: Pointer | null | undefined } = { sessionBus: undefined };
+
+/** Call `g_bus_get_sync(SESSION)` directly, bypassing the gate. Never throws (see the system probe). */
+export const probeSessionBusUnchecked = (): Pointer | null => {
+  const gdbus = loadGDBusFFI();
+  try {
+    return gdbus.symbols.g_bus_get_sync(G_BUS_TYPE_SESSION, null, null);
+  } catch {
+    return null;
+  }
+};
+
+/** The session `GDBusConnection*`, or null when the gate is off OR there is no bus. Cached. */
+export const getSessionBus = (): Pointer | null => {
+  if (sessionCache.sessionBus !== undefined) {
+    return sessionCache.sessionBus;
+  }
+  const conn = liveBlockerEnabled() ? probeSessionBusUnchecked() : null;
+  sessionCache.sessionBus = conn;
+  return conn;
+};
+
+/**
+ * A BOUNDED, deadlock-safe synchronous D-Bus method call. The reply is read by the
+ * connection's private GDBusWorker thread and awaited on `call_sync`'s own private
+ * GMainContext, so this blocks only the calling thread for the round-trip (finite
+ * {@link DBUS_CALL_TIMEOUT_MS}), never the pump. Returns the transfer-FULL reply GVariant
+ * tuple (caller `g_variant_unref`) or null on any failure (NULL GError**). `parameters`
+ * (a floating GVariant, or null for no args) is CONSUMED by the call.
+ */
+export const callMethodSync = (
+  conn: Pointer,
+  busName: string,
+  objectPath: string,
+  iface: string,
+  method: string,
+  parameters: Pointer | null,
+): Pointer | null => {
+  const gdbus = loadGDBusFFI();
+  try {
+    return gdbus.symbols.g_dbus_connection_call_sync(
+      conn,
+      cstr(busName),
+      cstr(objectPath),
+      cstr(iface),
+      cstr(method),
+      parameters,
+      null, // reply_type
+      G_DBUS_CALL_FLAGS_NONE,
+      DBUS_CALL_TIMEOUT_MS,
+      null, // cancellable
+      null, // error (NULL return already means "failed")
+    );
+  } catch {
+    return null;
+  }
+};
+
+/** Reset the session-bus probe cache. Test-only. */
+export const resetSessionBusCacheForTesting = (): void => {
+  sessionCache.sessionBus = undefined;
+};