@pikku/deploy-standalone 0.12.11 → 0.12.13

package/src/runtime/parent-watch.test.ts

@@ -0,0 +1,148 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import { PARENT_PID_ENV, watchParentProcess } from './parent-watch.js'
+
+const tick = () => delay(12)
+
+describe('a sidecar that outlives the shell that spawned it', () => {
+  it('does not watch when no parent pid was handed down', async () => {
+    let orphaned = 0
+    const watch = watchParentProcess({
+      env: {},
+      onOrphaned: () => orphaned++,
+      intervalMs: 1,
+    })
+    try {
+      assert.equal(watch.watching, false)
+      await tick()
+      assert.equal(orphaned, 0)
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('ignores a pid that is not a positive integer', async () => {
+    for (const value of ['', 'abc', '0', '-1', '1.5']) {
+      const watch = watchParentProcess({
+        env: { [PARENT_PID_ENV]: value },
+        onOrphaned: () => assert.fail(`pid ${value} should not be watched`),
+        intervalMs: 1,
+      })
+      assert.equal(watch.watching, false, `pid ${JSON.stringify(value)}`)
+      await tick()
+      watch.stop()
+    }
+  })
+
+  it('stays quiet while the parent is alive', async () => {
+    let orphaned = 0
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '4242' },
+      isAlive: () => true,
+      onOrphaned: () => orphaned++,
+      intervalMs: 1,
+    })
+    try {
+      assert.equal(watch.watching, true)
+      await tick()
+      assert.equal(orphaned, 0)
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('fires once when the parent goes away, and stops polling', async () => {
+    let alive = true
+    let orphaned = 0
+    let probes = 0
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '4242' },
+      isAlive: () => {
+        probes++
+        return alive
+      },
+      onOrphaned: () => orphaned++,
+      intervalMs: 1,
+    })
+    try {
+      await tick()
+      assert.equal(orphaned, 0)
+      alive = false
+      await tick()
+      assert.equal(orphaned, 1, 'the orphan handler must run')
+      const probesAtDeath = probes
+      await tick()
+      assert.equal(orphaned, 1, 'it must not fire again')
+      assert.equal(probes, probesAtDeath, 'polling must stop after it fires')
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('reads the pid the shell passes through the environment', () => {
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: String(process.pid) },
+      onOrphaned: () => {},
+      intervalMs: 60_000,
+    })
+    try {
+      assert.equal(watch.watching, true)
+      assert.equal(watch.parentPid, process.pid)
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('treats this very process as alive by default, and a reaped pid as gone', () => {
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: String(process.pid) },
+      onOrphaned: () => assert.fail('our own pid is alive'),
+      intervalMs: 60_000,
+    })
+    watch.stop()
+
+    // A pid that cannot exist: the default probe must report it gone rather
+    // than throwing, or an orphaned sidecar would never notice.
+    let orphaned = 0
+    const dead = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '2147483646' },
+      onOrphaned: () => orphaned++,
+      intervalMs: 60_000,
+    })
+    dead.checkNow()
+    dead.stop()
+    assert.equal(orphaned, 1)
+  })
+
+  it('never keeps the process alive on its own', () => {
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '4242' },
+      isAlive: () => true,
+      onOrphaned: () => {},
+      intervalMs: 60_000,
+    })
+    try {
+      assert.equal(
+        watch.holdsProcessOpen,
+        false,
+        'the poll timer must be unref-ed'
+      )
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('is safe to stop twice', () => {
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '4242' },
+      isAlive: () => true,
+      onOrphaned: () => {},
+      intervalMs: 60_000,
+    })
+    watch.stop()
+    watch.stop()
+    assert.equal(watch.watching, false)
+  })
+})

package/src/runtime/parent-watch.ts

@@ -0,0 +1,115 @@
+/**
+ * Environment variable a desktop shell uses to tell its sidecar which process
+ * it must not outlive.
+ */
+export const PARENT_PID_ENV = 'PIKKU_PARENT_PID'
+
+/**
+ * Environment variable a desktop shell uses to tell its sidecar where the
+ * SQLite file, uploaded content and runtime state belong. The shell resolves
+ * it from the platform's own app-data location, because a binary launched by
+ * double-click has no meaningful working directory.
+ */
+export const DATA_DIR_ENV = 'PIKKU_DATA_DIR'
+
+export type ParentWatchOptions = {
+  /** Where the parent pid is read from. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>
+  /** Probe for whether a pid is still running. Defaults to signal 0. */
+  isAlive?: (pid: number) => boolean
+  /** Run when the parent is found to be gone. Defaults to exiting cleanly. */
+  onOrphaned?: () => void
+  intervalMs?: number
+}
+
+export type ParentWatch = {
+  /** False when no usable parent pid was supplied — the watch is inert. */
+  readonly watching: boolean
+  readonly parentPid: number | undefined
+  /** True only if the poll timer would hold the event loop open. */
+  readonly holdsProcessOpen: boolean
+  /** Probe immediately rather than waiting for the next interval. */
+  checkNow(): void
+  stop(): void
+}
+
+/**
+ * A pid is alive if signalling it succeeds. `EPERM` also means alive — the
+ * process exists but belongs to another user — and only `ESRCH` means gone.
+ */
+const defaultIsAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+const parsePid = (raw: string | undefined): number | undefined => {
+  if (!raw) return undefined
+  if (!/^\d+$/.test(raw)) return undefined
+  const pid = Number(raw)
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined
+}
+
+/**
+ * Exit when the process that spawned us does.
+ *
+ * Tauri kills its sidecar on a clean exit, but a hard crash of the shell never
+ * runs that path. An orphaned pikku server keeps the SQLite file open, and the
+ * next launch — which single-instance only guards against a second *shell* —
+ * would be a second writer against the same database. Polling the parent is the only portable answer: neither
+ * `process.on('disconnect')` (no IPC channel here) nor a closed stdin is
+ * reliable across the platforms a desktop build targets.
+ *
+ * With no parent pid in the environment the watch is inert, so a server run
+ * from a terminal or a container behaves exactly as it did before.
+ */
+export const watchParentProcess = (
+  options: ParentWatchOptions = {}
+): ParentWatch => {
+  const env = options.env ?? process.env
+  const isAlive = options.isAlive ?? defaultIsAlive
+  const onOrphaned = options.onOrphaned ?? (() => process.exit(0))
+  const intervalMs = options.intervalMs ?? 1_000
+
+  const parentPid = parsePid(env[PARENT_PID_ENV])
+
+  let timer: ReturnType<typeof setInterval> | undefined
+  let fired = false
+
+  const stop = () => {
+    if (timer) {
+      clearInterval(timer)
+      timer = undefined
+    }
+  }
+
+  const checkNow = () => {
+    if (parentPid === undefined || fired) return
+    if (isAlive(parentPid)) return
+    fired = true
+    stop()
+    onOrphaned()
+  }
+
+  if (parentPid !== undefined) {
+    timer = setInterval(checkNow, intervalMs)
+    // The watch is a guard, not a reason to stay running: a server that has
+    // finished its work must still be allowed to exit.
+    timer.unref?.()
+  }
+
+  return {
+    get watching() {
+      return timer !== undefined
+    },
+    parentPid,
+    get holdsProcessOpen() {
+      return timer?.hasRef?.() ?? false
+    },
+    checkNow,
+    stop,
+  }
+}

package/src/sidecar-entry.test.ts

@@ -0,0 +1,89 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { SERVER_READY_MARKER } from '@pikku/deploy'
+
+import { StandaloneProviderAdapter } from './adapter.js'
+import { DATA_DIR_ENV, PARENT_PID_ENV } from './runtime/parent-watch.js'
+
+const baseContext = {
+  unit: { name: 'app', role: 'function' },
+  unitDir: '/build/app',
+  bootstrapPath: './.pikku/pikku-bootstrap.gen.js',
+  configImport: `import { createConfig } from './config.js'`,
+  configVar: 'createConfig',
+  servicesImport: `import { createSingletonServices } from './services.js'`,
+  servicesVar: 'createSingletonServices',
+  singletonServicesImport: '',
+  servicesType: 'Record<string, unknown>',
+  mcpImport: '',
+  mcpServerOption: '',
+} as never
+
+const entries = (['node', 'bun'] as const).map((runtime) => ({
+  runtime,
+  source: new StandaloneProviderAdapter({ runtime }).generateEntrySource(
+    baseContext
+  ),
+}))
+
+describe('the handshake a desktop shell reads off its sidecar', () => {
+  for (const { runtime, source } of entries) {
+    test(`the ${runtime} entry announces readiness with the shared marker`, () => {
+      assert.ok(
+        source.includes(SERVER_READY_MARKER),
+        'a shell waiting on `pikku: ready` would hang forever without it'
+      )
+      assert.match(
+        source,
+        /serverReadyLine|pikku: ready on http:\/\//,
+        'the line must carry a URL, not just the marker'
+      )
+    })
+
+    test(`the ${runtime} entry reports the port the server bound, not the one requested`, () => {
+      assert.match(
+        source,
+        /server\.port/,
+        'PORT=0 is how the shell avoids a bind race, so the requested port is useless'
+      )
+      assert.doesNotMatch(
+        source,
+        /ready on http:\/\/\$\{hostname\}:\$\{port\}/,
+        'announcing the requested port re-introduces the race'
+      )
+    })
+
+    test(`the ${runtime} entry announces readiness only after the server starts`, () => {
+      const readyAt = source.indexOf(SERVER_READY_MARKER)
+      const startAt = source.indexOf('await server.start()')
+      assert.ok(startAt > -1, 'the entry must start the server')
+      assert.ok(
+        readyAt > startAt,
+        'readiness printed before start() is a lie a parent will act on'
+      )
+    })
+
+    test(`the ${runtime} entry installs the orphan guard`, () => {
+      assert.match(
+        source,
+        /watchParentProcess\(\)/,
+        'a hard crash of the shell would otherwise orphan this process'
+      )
+      assert.match(source, /@pikku\/deploy-standalone\/runtime/)
+    })
+
+    test(`the ${runtime} entry still defaults to a fixed port outside a shell`, () => {
+      assert.match(
+        source,
+        /process\.env\.PORT \|\| '3000'/,
+        'an ordinary server deploy must keep its predictable port'
+      )
+    })
+  }
+
+  test('the environment contract is named in one place', () => {
+    assert.equal(PARENT_PID_ENV, 'PIKKU_PARENT_PID')
+    assert.equal(DATA_DIR_ENV, 'PIKKU_DATA_DIR')
+  })
+})