@deepblend/dsh-blender-provider-local 0.2.4 → 0.2.5

package/lib/index.js

@@ -21,6 +21,7 @@
 
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import net from 'node:net'
 import { readFile } from 'node:fs/promises'
 import { delimiter, isAbsolute, join, resolve, sep } from 'node:path'
 import { randomUUID } from 'node:crypto'
@@ -154,6 +155,124 @@ export const ProviderConfig = z.object({
  * @property {string} workingDirectory
  */
 
+/** How long an attached Blender gets to say hello before the attach is called a failure. */
+const ATTACH_READY_MS = 10_000
+
+/**
+ * Connect to a Unix socket, with a deadline.
+ *
+ * The add-on may be starting when the product asks — a user enables it and the product is already
+ * polling — so this retries inside one deadline rather than failing on the first refusal.
+ *
+ * @param {string} socketPath
+ * @param {number} timeoutMs
+ * @returns {Promise<import('node:net').Socket>}
+ */
+async function connect(socketPath, timeoutMs) {
+  const deadline = Date.now() + Math.min(timeoutMs, 10_000)
+  let lastError = null
+  for (;;) {
+    const socket = await new Promise(resolve => {
+      const candidate = net.connect(socketPath)
+      candidate.once('connect', () => resolve(candidate))
+      candidate.once('error', error => {
+        lastError = error
+        candidate.destroy()
+        resolve(null)
+      })
+    })
+    if (socket !== null) return socket
+    if (Date.now() >= deadline) throw lastError ?? new Error('no answer')
+    await new Promise(settle => setTimeout(settle, 250))
+  }
+}
+
+/**
+ * A live Blender, presented as one shape whatever carries the bytes.
+ *
+ * WHY THE SEAM EXISTS. A session can be carried two ways, and both are real: the process this
+ * provider SPAWNS (`--background`, pipes on stdin/stdout) and the Blender a USER is looking at (the
+ * add-on's socket). The conversation — the handshake, the per-request deadline, matching an answer to
+ * its request — is identical, and the only thing that differs is who owns the other end. Writing it
+ * twice would mean two places to fix the next bug in the deadline, and the second one would be the
+ * one nobody runs.
+ *
+ * The subprocess adapter and the socket adapter below are the whole of the difference.
+ */
+class SubprocessTransport {
+  /** @param {object} handle from `ctx.subprocess.spawn` */
+  constructor(handle) {
+    this.handle = handle
+    this.read = handle.stdout
+    this.onExit = callback => handle.done?.then?.(() => callback({}), () => callback({}))
+    this.pid = null
+  }
+
+  write(text) {
+    this.handle.stdin.write(text)
+  }
+
+  end() {
+    try {
+      this.handle.stdin.end()
+    } catch {
+      // Already gone; the exit callback is what decides.
+    }
+  }
+
+  /** Wait for the process to be gone, bounded. */
+  async settle(graceMs) {
+    try {
+      await this.handle.waitForExit?.(graceMs)
+    } catch {
+      // A process that had to be terminated is still a settled one.
+    }
+  }
+}
+
+class SocketTransport {
+  /**
+   * @param {import('node:net').Socket} socket
+   * @param {{ pid?: number|null }} [info]
+   */
+  constructor(socket, info = {}) {
+    this.socket = socket
+    this.read = socket
+    // The pid is the ATTACHED Blender's own, from its handshake — never this process's. A product that
+    // reported its own pid here would make "which Blender answered" unanswerable, which is the one
+    // question an attach exists to answer.
+    this.pid = info.pid ?? null
+    this.exitCallbacks = []
+    socket.on('close', () => {
+      for (const callback of this.exitCallbacks) callback({})
+    })
+    socket.on('error', () => {
+      // An error closes the socket, and the close handler reports it. Swallowing it here keeps a
+      // broken pipe from becoming an unhandled 'error' event, which would take the host down.
+    })
+  }
+
+  onExit(callback) {
+    this.exitCallbacks.push(callback)
+  }
+
+  write(text) {
+    this.socket.write(text)
+  }
+
+  end() {
+    try {
+      this.socket.end()
+    } catch {
+      // Already closed.
+    }
+  }
+
+  async settle() {
+    this.socket.destroy()
+  }
+}
+
 /**
  * One live Blender process, serving requests until it is closed (SPEC §20 M6).
  *
@@ -170,10 +289,11 @@ export const ProviderConfig = z.object({
  */
 class BlenderSession {
   /**
-   * @param {{ handle: object, directory: string, jobId: string, timeoutMs: number, onClose: () => void }} input
+   * @param {{ transport: SubprocessTransport|SocketTransport, directory: string|null, jobId: string, timeoutMs: number, onClose: () => void }} input
    */
   constructor(input) {
-    this.handle = input.handle
+    this.transport = input.transport
+    this.handle = input.transport.handle ?? null
     this.directory = input.directory
     this.jobId = input.jobId
     this.timeoutMs = input.timeoutMs
@@ -182,7 +302,7 @@ class BlenderSession {
     // `done`, `terminate`, `terminateForHostExit`, `waitForExit`. So the pid comes from the process
     // itself, in the `ready` line bootstrap.py opens with — which is better evidence anyway, because
     // it is the pid the script believes it is rather than the one the spawn returned.
-    this.pid = null
+    this.pid = input.transport.pid ?? null
     /** @type {Map<string, {resolve: Function, reject: Function, timer: object}>} */
     this.waiting = new Map()
     this.progress = []
@@ -193,15 +313,42 @@ class BlenderSession {
     this.readyPromise = null
     this.readyResolve = null
     this.readyReject = null
+    this.readySettled = false
     this._read()
   }
 
-  /** Resolve when bootstrap.py has announced itself, reject if the process dies first. */
-  ready() {
+  /**
+   * Resolve when the other end has announced itself — reject if it dies first, or says nothing.
+   *
+   * THE DEADLINE IS THE POINT, and a mutation found it missing: with the handshake removed from the
+   * bridge, `attachSession` connected successfully and then waited FOREVER, because the socket stayed
+   * open and simply never spoke. A hang is worse than either a success or a coded failure — it has no
+   * message, no code, and no end — and this repository's rule is that a failure has to be a branchable
+   * result. The same deadline that bounds a request bounds the opening of the conversation.
+   */
+  ready(timeoutMs = this.timeoutMs) {
     if (this.readyPromise === null) {
       this.readyPromise = new Promise((resolve, reject) => {
-        this.readyResolve = resolve
-        this.readyReject = reject
+        const timer = setTimeout(() => {
+          if (this.readySettled) return
+          this.readySettled = true
+          reject(new BlenderError(
+            BlenderErrorCode.TIMEOUT,
+            `The Blender session (pid ${this.pid ?? 'unknown'}) connected but never announced itself within ${timeoutMs} ms.`,
+            { detail: { pid: this.pid, timeoutMs } },
+          ))
+        }, timeoutMs)
+        if (typeof timer.unref === 'function') timer.unref()
+        this.readyResolve = value => {
+          clearTimeout(timer)
+          this.readySettled = true
+          resolve(value)
+        }
+        this.readyReject = error => {
+          clearTimeout(timer)
+          this.readySettled = true
+          reject(error)
+        }
       })
     }
     return this.readyPromise
@@ -209,7 +356,7 @@ class BlenderSession {
 
   /** Read stdout line by line for the life of the process. */
   _read() {
-    const stream = this.handle?.stdout
+    const stream = this.transport.read
     if (stream === undefined || stream === null) {
       this._fail(new BlenderError(BlenderErrorCode.SPAWN_FAILED, 'the session has no stdout stream to read'))
       return
@@ -229,10 +376,10 @@ class BlenderSession {
       // Bounded: stderr is evidence for a failure, not a log to keep.
       this.stderr = (this.stderr + chunk.toString('utf8')).slice(-8192)
     })
-    // THE HANDLE'S EXIT SIGNAL IS A PROMISE, NOT AN EVENT (`done`), and it carries nothing — so the
-    // exit code is read from `waitForExit()` where one is needed, and the failure below says what is
-    // knowable: the session ended without answering.
-    this.handle?.done?.then?.(() => this._exited({}), () => this._exited({}))
+    // THE TRANSPORT REPORTS THE END, whatever the end means: for a spawned process the handle's
+    // `done` promise, for a socket its 'close'. Neither carries a code — the failure below says what
+    // is knowable, which is that the session ended without answering.
+    this.transport.onExit(info => this._exited(info))
   }
 
   _line(line) {
@@ -331,7 +478,7 @@ class BlenderSession {
       }
     })
 
-    this.handle.stdin.write(`${JSON.stringify(document)}\n`)
+    this.transport.write(`${JSON.stringify(document)}\n`)
     return answered
   }
 
@@ -339,17 +486,12 @@ class BlenderSession {
   async close() {
     if (this.closed) return
     try {
-      this.handle.stdin.write(`${JSON.stringify({ action: 'shutdown' })}\n`)
-      this.handle.stdin.end()
+      this.transport.write(`${JSON.stringify({ action: 'shutdown' })}\n`)
+      this.transport.end()
     } catch {
-      // The process may already be gone; the wait below is what decides.
-    }
-    try {
-      // `waitForExit` is the handle's own way to wait, and it takes a deadline in milliseconds.
-      await this.handle.waitForExit?.(TERMINATE_GRACE_MS)
-    } catch {
-      // A process that had to be terminated is still a closed session.
+      // The other end may already be gone; the settle below is what decides.
     }
+    await this.transport.settle(TERMINATE_GRACE_MS)
     this.closed = true
     this._fail(new BlenderError(
       BlenderErrorCode.ABORTED,
@@ -692,7 +834,7 @@ export default class LocalBlenderRuntime extends Service {
     })
 
     const session = new BlenderSession({
-      handle,
+      transport: new SubprocessTransport(handle),
       directory,
       jobId,
       timeoutMs: this.config.timeoutMs,
@@ -702,6 +844,63 @@ export default class LocalBlenderRuntime extends Service {
     return session
   }
 
+  /**
+   * Attach to a Blender that is ALREADY RUNNING — the user's own, with the add-on (SPEC §20 M6).
+   *
+   * THE OTHER HALF OF THE LIVE BRIDGE. `openSession()` spawns a Blender nobody can see; this one talks
+   * to the Blender on the user's screen, so the operations happen in the window they are looking at.
+   * The conversation is identical — same protocol, same envelopes, same per-request deadline — because
+   * both go through `BlenderSession`; the only difference is who owns the other end of the bytes.
+   *
+   * The pid in the handshake is the ATTACHED Blender's own, and it is what makes "which Blender
+   * answered this" answerable. A product that reported its own pid here would make that question
+   * unanswerable, which is the one question an attach exists to answer.
+   *
+   * @param {string} socketPath
+   * @param {{ timeoutMs?: number }} [options]
+   * @returns {Promise<{ pid: number|null, run: Function, close: Function }>}
+   */
+  async attachSession(socketPath, options = {}) {
+    if (typeof socketPath !== 'string' || socketPath.length === 0) {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        'Attaching needs the socket path the Blender add-on is listening on.',
+      )
+    }
+    if (!existsSync(socketPath)) {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        `Nothing is listening at ${socketPath}. Enable the DeepBlend bridge add-on in Blender ` +
+          '(View3D > Sidebar > DeepBlend), or start one headless with ' +
+          '`blender --background --python deepblend_bridge.py -- --socket <path>`.',
+        { detail: { socketPath } },
+      )
+    }
+
+    const socket = await connect(socketPath, options.timeoutMs ?? this.config.timeoutMs).catch(cause => {
+      throw new BlenderError(
+        BlenderErrorCode.RUNTIME_UNAVAILABLE,
+        `The Blender bridge at ${socketPath} could not be reached: ${cause?.message ?? 'unknown failure'}.`,
+        { detail: { socketPath } },
+      )
+    })
+
+    const session = new BlenderSession({
+      transport: new SocketTransport(socket),
+      directory: null,
+      jobId: `attach-${randomUUID()}`,
+      timeoutMs: this.config.timeoutMs,
+      onClose: () => {},
+    })
+    // A SHORTER DEADLINE THAN A SPAWN, and the difference is real rather than a preference: a spawned
+    // Blender legitimately takes a second or two to boot, while an add-on that is already serving
+    // answers the handshake immediately. MEASURED: with the provider's own 180 s timeout, a peer that
+    // connected and said nothing took 180 s to report — long enough that a user would conclude the
+    // product had hung.
+    await session.ready(ATTACH_READY_MS)
+    return session
+  }
+
   async runBootstrap(request, options = {}) {
     const action = request?.action
     if (typeof action !== 'string' || action.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "description": "Local Blender Provider: the BlenderRuntime Service over ctx.subprocess (batch execution).",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.2.4"
+    "@deepblend/dsh-blender-contracts": "0.2.5"
   },
   "license": "MIT",
   "repository": {

package/python/deepblend_bridge.py

@@ -0,0 +1,306 @@
+"""DeepBlend Studio — the Blender-side bridge (SPEC §20 M6 "Blender Add-on" / "Live Bridge").
+
+WHAT THIS IS
+------------
+One file with two entry points, and that is deliberate:
+
+* **As a Blender add-on** (the GUI case): the user installs it, enables it, and their own Blender
+  opens a local socket and shows a panel saying whether DeepBlend is attached. Every operation then
+  runs in the Blender they are LOOKING AT, which is the whole point of the M6 item — the batch round
+  trip stops being the only shape.
+* **As a headless server** (the case a test can drive): `blender --background --python
+  deepblend_bridge.py -- --socket <path>` serves exactly the same protocol with no GUI at all.
+
+Two entry points rather than two files, because the protocol and the dispatch are one thing: a second
+copy for the headless case would be a second answer to "what does compile_scene do", and it would rot
+first because nothing runs it.
+
+WHAT IT REUSES
+--------------
+`bootstrap.py`'s dispatch, unchanged: the same `ACTIONS` table, the same protocol-version check, the
+same envelope builder, the same per-request process identity. This file adds a TRANSPORT (a socket)
+and a GUI (a panel), not a second implementation.
+
+THE PROTOCOL is the session protocol, one JSON document per line: the product sends
+`{protocolVersion, jobId, action, payload?}`, this answers with the envelope bootstrap.py builds.
+`{"action": "shutdown"}` closes the connection.
+
+Owner: DeepBlend Studio — SPEC §20 M6
+"""
+
+import json
+import os
+import socket
+import sys
+import threading
+
+import bpy  # noqa: F401  — present in Blender; the import is what makes this an add-on module
+
+def _find_bootstrap():
+    """Import `bootstrap` from wherever it actually is, or say what to set.
+
+    MEASURED PROBLEM, and it is the user's case rather than the test's: Blender COPIES an add-on into
+    its own add-ons directory, so the file that lands there is this one ALONE — `bootstrap.py` is not
+    beside it, and `import bootstrap` fails. The headless entry point never sees this, because there
+    the file still sits in the package.
+
+    So the search is: beside me (headless), then the directory an operator points at, then the one a
+    user can paste into the add-on's preferences. When all three miss, the failure names the setting
+    instead of raising an ImportError into a panel that shows nothing.
+    """
+    candidates = [os.path.dirname(os.path.abspath(__file__))]
+    configured = os.environ.get("DEEPBLEND_BOOTSTRAP_DIR", "")
+    if configured:
+        candidates.append(configured)
+    try:
+        preferences = bpy.context.preferences.addons[__name__].preferences
+        if getattr(preferences, "bootstrap_dir", ""):
+            candidates.insert(0, preferences.bootstrap_dir)
+    except Exception:
+        # No preferences yet (headless, or before registration): the other two are enough.
+        pass
+
+    for candidate in candidates:
+        if candidate and os.path.exists(os.path.join(candidate, "bootstrap.py")):
+            if candidate not in sys.path:
+                sys.path.insert(0, candidate)
+            import bootstrap  # noqa: F401
+            return sys.modules["bootstrap"]
+    return None
+
+
+bootstrap = _find_bootstrap()
+BOOTSTRAP_PROBLEM = None if bootstrap is not None else (
+    "bootstrap.py was not found. Set DEEPBLEND_BOOTSTRAP_DIR to the provider package's python "
+    "directory (…/provider-local/python), or paste it into this add-on's preferences."
+)
+
+bl_info = {
+    "name": "DeepBlend Studio Bridge",
+    "author": "DeepBlend Studio",
+    "version": (0, 2, 4),
+    "blender": (4, 0, 0),
+    "location": "View3D > Sidebar > DeepBlend",
+    "description": "Serve DeepBlend operations inside this Blender, so the product drives the window you are looking at",
+    "category": "Scene",
+}
+
+# The default socket path. One per workspace, so two stores on one machine do not collide — and the
+# product passes its own path when it starts the headless server, so this default is only what the
+# add-on uses when a user enables it with no configuration.
+DEFAULT_SOCKET = os.path.join(os.path.expanduser("~"), ".deepblend-bridge.sock")
+
+
+class _Bridge:
+    """The serving state: one socket, one thread, and the last thing that happened."""
+
+    def __init__(self, socket_path, options=None):
+        self.socket_path = socket_path
+        self.options = options or {}
+        self.server = None
+        self.thread = None
+        self.requests = 0
+        self.last_action = None
+        self.last_error = None
+        self.connected = False
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def start(self):
+        if os.path.exists(self.socket_path):
+            # A socket file left by a process that died. Refusing to start would leave the user with
+            # no way forward except deleting a file they cannot see, so it is replaced — the same
+            # decision the render job's recovery path makes about a stale pid file.
+            os.unlink(self.socket_path)
+        self.server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.server.bind(self.socket_path)
+        self.server.listen(4)
+        self.thread = threading.Thread(target=self._serve, name="deepblend-bridge", daemon=True)
+        self.thread.start()
+
+    def stop(self):
+        try:
+            if self.server is not None:
+                self.server.close()
+        except Exception:
+            pass
+        self.server = None
+        try:
+            if os.path.exists(self.socket_path):
+                os.unlink(self.socket_path)
+        except Exception:
+            pass
+
+    # -- serving -----------------------------------------------------------
+
+    def _serve(self):
+        while self.server is not None:
+            try:
+                connection, _ = self.server.accept()
+            except Exception:
+                return
+            self.connected = True
+            try:
+                self._converse(connection)
+            except Exception as exc:
+                self.last_error = bootstrap.error_text(exc)
+            finally:
+                self.connected = False
+                try:
+                    connection.close()
+                except Exception:
+                    pass
+
+    def _converse(self, connection):
+        """One connection: a handshake, then a line in and an envelope out, until the peer stops.
+
+        THE HANDSHAKE IS THE SESSION PROTOCOL'S OWN, and it took a hang to notice it was missing: the
+        headless entry point printed `{"kind": "ready"}` to stdout at startup, and a CONNECTION got
+        nothing — so the product's `BlenderSession.ready()` waited forever on a peer that was already
+        serving. A transport that answers the same conversation has to open it the same way.
+        """
+        connection.sendall((json.dumps({"kind": "ready", "pid": os.getpid(), "socket": self.socket_path}) + "\n").encode("utf-8"))
+        buffer = b""
+        while True:
+            chunk = connection.recv(65536)
+            if not chunk:
+                return
+            buffer += chunk
+            while b"\n" in buffer:
+                line, buffer = buffer.split(b"\n", 1)
+                text = line.decode("utf-8", "replace").strip()
+                if text == "":
+                    continue
+                try:
+                    request = json.loads(text)
+                except Exception as exc:
+                    answer = bootstrap.build_envelope(None, None, None, {
+                        "code": "BLENDER_SCRIPT_ERROR",
+                        "message": "the request line is not valid JSON: %s" % (bootstrap.error_text(exc),),
+                    }, [], [])
+                else:
+                    if isinstance(request, dict) and request.get("action") == "shutdown":
+                        connection.sendall((json.dumps({"kind": "bye", "pid": os.getpid()}) + "\n").encode("utf-8"))
+                        return
+                    self.requests += 1
+                    self.last_action = request.get("action") if isinstance(request, dict) else None
+                    answer = bootstrap._session_dispatch(request, self.options)
+                answer["kind"] = "result"
+                connection.sendall((json.dumps(answer, ensure_ascii=False) + "\n").encode("utf-8"))
+
+    # -- what the panel shows ----------------------------------------------
+
+    def status(self):
+        if self.server is None:
+            return "off"
+        return "attached" if self.connected else "listening on %s" % (self.socket_path,)
+
+
+_BRIDGE = None
+
+
+class DeepBlendBridgePreferences(bpy.types.AddonPreferences):
+    """Where the user points the add-on at the package, because Blender copies add-ons alone."""
+
+    bl_idname = __name__
+
+    bootstrap_dir: bpy.props.StringProperty(  # type: ignore[valid-type]
+        name="bootstrap.py directory",
+        description="The provider package's python directory (…/provider-local/python)",
+        default="",
+        subtype="DIR_PATH",
+    )
+
+    def draw(self, context):
+        layout = self.layout
+        layout.prop(self, "bootstrap_dir")
+        if BOOTSTRAP_PROBLEM is not None:
+            layout.label(text=BOOTSTRAP_PROBLEM, icon="ERROR")
+
+
+class DEEPBLEND_PT_bridge(bpy.types.Panel):
+    """The panel, because an add-on a user cannot see is an add-on they will not trust."""
+
+    bl_label = "DeepBlend Studio"
+    bl_idname = "DEEPBLEND_PT_bridge"
+    bl_space_type = "VIEW_3D"
+    bl_region_type = "UI"
+    bl_category = "DeepBlend"
+
+    def draw(self, context):
+        layout = self.layout
+        if BOOTSTRAP_PROBLEM is not None:
+            layout.label(text="bootstrap.py not found", icon="ERROR")
+            layout.label(text="Set it in this add-on's preferences")
+            return
+        if _BRIDGE is None:
+            layout.label(text="Bridge is not running", icon="ERROR")
+            return
+        layout.label(text="Status: %s" % (_BRIDGE.status(),))
+        layout.label(text="Socket: %s" % (os.path.basename(_BRIDGE.socket_path),))
+        layout.label(text="Operations served: %d" % (_BRIDGE.requests,))
+        if _BRIDGE.last_action is not None:
+            layout.label(text="Last: %s" % (_BRIDGE.last_action,))
+        if _BRIDGE.last_error is not None:
+            layout.label(text="Last error: %s" % (_BRIDGE.last_error[:60],), icon="ERROR")
+
+
+def register():
+    global _BRIDGE
+    socket_path = os.environ.get("DEEPBLEND_BRIDGE_SOCKET", DEFAULT_SOCKET)
+    _BRIDGE = _Bridge(socket_path)
+    try:
+        _BRIDGE.start()
+    except Exception as exc:
+        # A bridge that cannot listen must not stop Blender from starting: the user's session is more
+        # important than this panel, and the panel says what went wrong.
+        _BRIDGE.last_error = bootstrap.error_text(exc)
+    bpy.utils.register_class(DeepBlendBridgePreferences)
+    bpy.utils.register_class(DEEPBLEND_PT_bridge)
+
+
+def unregister():
+    global _BRIDGE
+    bpy.utils.unregister_class(DEEPBLEND_PT_bridge)
+    bpy.utils.unregister_class(DeepBlendBridgePreferences)
+    if _BRIDGE is not None:
+        _BRIDGE.stop()
+    _BRIDGE = None
+
+
+def main():
+    """Headless entry point: serve until the process is asked to stop."""
+    argv = sys.argv
+    options = {}
+    if "--" in argv:
+        tokens = argv[argv.index("--") + 1:]
+        index = 0
+        while index < len(tokens):
+            if tokens[index] == "--socket" and index + 1 < len(tokens):
+                options["socket"] = tokens[index + 1]
+                index += 2
+                continue
+            index += 1
+    socket_path = options.get("socket", DEFAULT_SOCKET)
+
+    if bootstrap is None:
+        print(json.dumps({"kind": "error", "message": BOOTSTRAP_PROBLEM}), flush=True)
+        return 2
+
+    global _BRIDGE
+    _BRIDGE = _Bridge(socket_path, {"proc": None})
+    _BRIDGE.start()
+    print(json.dumps({"kind": "ready", "pid": os.getpid(), "socket": socket_path}), flush=True)
+    try:
+        # The serve thread is a daemon, so this loop is what keeps the process alive. A SIGTERM (or
+        # the product closing the socket and asking for shutdown) ends it.
+        _BRIDGE.thread.join()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        _BRIDGE.stop()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())