@stonyx/orm 0.3.2-alpha.59 → 0.3.2-alpha.60

package/dist/setup-rest-server.js

@@ -45,17 +45,41 @@ export default async function (route, accessPath, metaRoute) {
     // predicate -- which is what abofs/stonyx-orm#196 and #207 need in order to
     // ask model X's predicate about a request routed to model Y.
     //
-    // Published BEFORE `waitForModule('rest-server')` and before the mount loop,
-    // deliberately. That module may already be listening by the time it reports
-    // ready, so assigning after the mounts would leave a window in which a route
-    // exists and the registry does not.
+    // Published BEFORE `await waitForModule('rest-server')`, deliberately: that
+    // await is the ONLY yield point in this function, and the rest-server module
+    // may already be listening by the time it reports ready, so an assignment
+    // after it would leave a window in which a route is live and the registry is
+    // not.
+    //
+    // It is NOT before the mount loop for that reason, and the comment here used
+    // to say it was. `RestServer.mountRoute` is fully synchronous -- construct,
+    // registerCalls(), api.use() -- and nothing between the loop and this
+    // function's closing brace yields, so the event loop cannot deliver a request
+    // in there and the window that clause described cannot open. Measured:
+    // moving this assignment to the last statement of the function leaves the
+    // suite at 951 pass / 0 fail. Being ahead of the mount loop is free and
+    // harmless; it is not what makes the ordering correct.
     //
     // Assigned unconditionally, including when the try above failed and the map
     // is empty or partial: the mount loop below is driven by this exact object,
-    // so whatever is reachable through `Orm.instance` is by construction the same
-    // set of predicates that is actually enforcing. A guard here that skipped the
-    // assignment would let the registry go silently missing, which is precisely
-    // the failure #202's AC8 exists to catch.
+    // so at the moment of assignment whatever is reachable through
+    // `Orm.instance` is the same set of predicates that is about to enforce.
+    // A guard such as `if (Object.keys(accessFunctions).length)` would let the
+    // registry go silently missing on a total load failure, and a later consumer
+    // would read `undefined` from `getAccess` and have to distinguish "no access
+    // class" from "the registry was never published" -- which it cannot. That is
+    // the reasoning, and it is REASONING, not something this suite tests: the
+    // guarded variant is also 951 pass / 0 fail, AC8 included, because every boot
+    // in this suite loads a non-empty access map so the guard never fires. AC8
+    // demonstrably cannot catch it. Catching it needs a boot with
+    // `orm.paths.access` pointed at an empty directory, which this suite has no
+    // harness for.
+    //
+    // One further limit on "by construction": the mount loop passes `access` BY
+    // VALUE into each OrmRequest, so the enforcing set is a snapshot taken here,
+    // while `getAccess` reads the map live. The two are the same set at boot and
+    // stay the same set only for as long as nobody writes to the public field.
+    // The equality is a boot-time fact, not an invariant.
     Orm.instance.accessFunctions = accessFunctions;
     await waitForModule('rest-server');
     // Remove "/" prefix and name mount point accordingly

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.59",
+  "version": "0.3.2-alpha.60",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/setup-rest-server.ts

@@ -57,17 +57,41 @@ export default async function(route: string, accessPath: string, metaRoute: bool
   // predicate -- which is what abofs/stonyx-orm#196 and #207 need in order to
   // ask model X's predicate about a request routed to model Y.
   //
-  // Published BEFORE `waitForModule('rest-server')` and before the mount loop,
-  // deliberately. That module may already be listening by the time it reports
-  // ready, so assigning after the mounts would leave a window in which a route
-  // exists and the registry does not.
+  // Published BEFORE `await waitForModule('rest-server')`, deliberately: that
+  // await is the ONLY yield point in this function, and the rest-server module
+  // may already be listening by the time it reports ready, so an assignment
+  // after it would leave a window in which a route is live and the registry is
+  // not.
+  //
+  // It is NOT before the mount loop for that reason, and the comment here used
+  // to say it was. `RestServer.mountRoute` is fully synchronous -- construct,
+  // registerCalls(), api.use() -- and nothing between the loop and this
+  // function's closing brace yields, so the event loop cannot deliver a request
+  // in there and the window that clause described cannot open. Measured:
+  // moving this assignment to the last statement of the function leaves the
+  // suite at 951 pass / 0 fail. Being ahead of the mount loop is free and
+  // harmless; it is not what makes the ordering correct.
   //
   // Assigned unconditionally, including when the try above failed and the map
   // is empty or partial: the mount loop below is driven by this exact object,
-  // so whatever is reachable through `Orm.instance` is by construction the same
-  // set of predicates that is actually enforcing. A guard here that skipped the
-  // assignment would let the registry go silently missing, which is precisely
-  // the failure #202's AC8 exists to catch.
+  // so at the moment of assignment whatever is reachable through
+  // `Orm.instance` is the same set of predicates that is about to enforce.
+  // A guard such as `if (Object.keys(accessFunctions).length)` would let the
+  // registry go silently missing on a total load failure, and a later consumer
+  // would read `undefined` from `getAccess` and have to distinguish "no access
+  // class" from "the registry was never published" -- which it cannot. That is
+  // the reasoning, and it is REASONING, not something this suite tests: the
+  // guarded variant is also 951 pass / 0 fail, AC8 included, because every boot
+  // in this suite loads a non-empty access map so the guard never fires. AC8
+  // demonstrably cannot catch it. Catching it needs a boot with
+  // `orm.paths.access` pointed at an empty directory, which this suite has no
+  // harness for.
+  //
+  // One further limit on "by construction": the mount loop passes `access` BY
+  // VALUE into each OrmRequest, so the enforcing set is a snapshot taken here,
+  // while `getAccess` reads the map live. The two are the same set at boot and
+  // stay the same set only for as long as nobody writes to the public field.
+  // The equality is a boot-time fact, not an invariant.
   Orm.instance.accessFunctions = accessFunctions;
 
   await waitForModule('rest-server');