@deepblend/dsh-blender-provider-local 0.2.6 → 0.2.8

package/lib/index.js

@@ -167,6 +167,20 @@ export const ProviderConfig = z.object({
   sessionActions: z.array(z.string()).default([]),
   /** How long a kept session may sit idle before it is closed. */
   sessionIdleMs: z.number().default(60_000),
+  /**
+   * The socket a Blender bridge is listening on, when the operator wants the session actions served by
+   * THE USER'S OWN BLENDER rather than one this provider spawns (SPEC §20 M6 "Live Bridge").
+   *
+   * Empty means "spawn one", which is what every deployment did before this key existed. Setting it is
+   * how a user says *use the Blender I already have open* — and the difference is not speed, it is that
+   * they can watch the operations happen in the window they are looking at.
+   *
+   * A CONFIGURED SOCKET THAT DOES NOT ANSWER IS AN ERROR, not a fallback to spawning. Silently doing
+   * something else than what was asked is the failure mode this repository keeps paying for: the user
+   * would see operations succeed and never learn that their Blender was not the one doing them. The
+   * refusal names the add-on, because that is what has to be enabled.
+   */
+  sessionSocket: z.string().default(''),
 })
 
 /**
@@ -211,6 +225,28 @@ async function connect(socketPath, timeoutMs) {
   }
 }
 
+/**
+ * The actions this provider can serve from a kept session, and the ONLY ones it can.
+ *
+ * DERIVED, NOT CHOSEN: these are exactly the actions whose calls go through `runBootstrap`, which is
+ * the one place the session path is decided. Everything else spawns its own process on purpose —
+ * `render_frames` most of all, because cancelling a render has to kill exactly that render, and a
+ * request inside a kept session cannot be killed without ending the session (and, attached, the
+ * user's own Blender).
+ *
+ * WHY THE LIST IS CHECKED RATHER THAN TRUSTED. MEASURED: naming `render_frames` in `sessionActions`
+ * used to do NOTHING AT ALL — the configuration was inert, the render ran in its own process as
+ * before, and nothing anywhere said so. A key that silently does nothing is worse than a key that
+ * fails: the operator believes they changed something. `contract/session-routing.test.mjs` derives
+ * this set from the source, so adding a `runBootstrap` call site without adding it here goes red.
+ */
+export const SESSION_ROUTABLE_ACTIONS = Object.freeze([
+  'get_capabilities',
+  'compile_scene',
+  'render_preview',
+  'render_views',
+])
+
 /**
  * A live Blender, presented as one shape whatever carries the bytes.
  *
@@ -560,6 +596,20 @@ export default class LocalBlenderRuntime extends Service {
     // See the host's constructor: a key this row does not read is a startup error, because the schema
     // accepts it silently (SPEC §17's nested groups versus this package's flat keys).
     assertKnownConfigKeys(ProviderConfig, config, 'deepblend-blender-runtime')
+    // A CONFIGURED ACTION THAT CANNOT BE ROUTED IS REFUSED AT STARTUP, not ignored. Naming a render
+    // here would leave the operator believing their renders now run in their own Blender, while the
+    // render quietly kept its own process — the same shape as a key this row does not read, which the
+    // line above already refuses.
+    const unroutable = (config.sessionActions ?? []).filter(action => !SESSION_ROUTABLE_ACTIONS.includes(action))
+    if (unroutable.length > 0) {
+      throw new Error(
+        `sessionActions names ${unroutable.map(action => `"${action}"`).join(', ')}, and this provider can only ` +
+        `serve ${SESSION_ROUTABLE_ACTIONS.join(', ')} from a kept session. The renders that must be cancellable ` +
+        '(`render_frames`) spawn their own process on purpose: cancelling one kills exactly that render, and a ' +
+        'request inside a kept session cannot be killed without ending the session — which, attached, is the ' +
+        'user\'s own Blender.',
+      )
+    }
     this.config = config
     this.bootstrapPath = this._resolveBootstrapPath(config.bootstrapPath)
     /** Resolved once: the host must be configured with the same value. */
@@ -948,7 +998,12 @@ export default class LocalBlenderRuntime extends Service {
    */
   async _keptSession() {
     if (this._session !== null && !this._session.closed) return this._session
-    this._session = await this.openSession()
+    const socket = this.config.sessionSocket
+    // THE USER'S BLENDER, when they have named one. `attachSession` owns the refusal and its message;
+    // this only decides which of the two transports the configured actions travel over.
+    this._session = typeof socket === 'string' && socket.length > 0
+      ? await this.attachSession(socket)
+      : await this.openSession()
     return this._session
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "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.6"
+    "@deepblend/dsh-blender-contracts": "0.2.8"
   },
   "license": "MIT",
   "repository": {