mikser-io 9.2.0 → 9.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.2.0",
+  "version": "9.3.0",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {

package/src/plugins/api.js

@@ -394,6 +394,37 @@ export function api(options = {}) {
         //   api.endpoints.admin   { token: '...', operations: ['list','update','delete','render'] }
         for (const [name, ep] of Object.entries(endpoints)) {
             const router = express.Router()
+
+            // Nothing is served until the first build cycle has finished.
+            //
+            // The server binds at the end of the loaded phase — before
+            // process() has emitted an entity — so without this the endpoint
+            // spends the whole first build answering against an empty catalog.
+            // Renders fail outright (the layouts registry fills during
+            // process()), and reads are worse than that: a list returns
+            // whichever subset exists at that instant, which is a wrong answer
+            // wearing a 200. A consumer seeding its routes from that gets zero
+            // routes and renders blank pages.
+            //
+            // 503, not 4xx, and Retry-After: this is the one honest status
+            // here. It says the request was fine and the server was not, which
+            // is exactly the case, and it is the status every HTTP client
+            // already knows to retry. A 422 or a 500 invites the caller to
+            // treat a transient build as a permanent defect and give up.
+            //
+            // The window is normally sub-second and easy to miss. It stretches
+            // whenever the cache has to be rebuilt from scratch — most notably
+            // after an engine upgrade, where the schema stamp no longer matches
+            // and the catalog is wiped before the rebuild.
+            router.use((req, res, next) => {
+                if (runtime.ready) return next()
+                res.set('Retry-After', '1')
+                res.status(503).json({
+                    error: 'Mikser is still building — the catalog is not ready yet',
+                    ready: false,
+                })
+            })
+
             router.use(express.json({ limit: ep.bodyLimit ?? globalBodyLimit }))
 
             // Operations default to the safer shape when no token is set
@@ -415,6 +446,20 @@ export function api(options = {}) {
             const query = (typeof ep.query === 'function' || (ep.query && typeof ep.query === 'object'))
                 ? ep.query
                 : null
+
+            // The same scope as a PREDICATE. Two paths hold one entity in
+            // hand and have no query to push a filter into — admitting a
+            // POST /render body, and the graph-subscription filter — so
+            // they have to test it directly. Calling `query` there works
+            // only while the scope is a function; the sift-object form
+            // this endpoint now accepts is not callable, and the failure
+            // is a bare `query is not a function` surfacing from whichever
+            // route touched it first.
+            const matchesScope = typeof ep.query === 'function'
+                ? ep.query
+                : query
+                    ? sift(query)
+                    : null
             const pageSize = ep.pageSize ?? globalPageSize
             const renderTimeout = ep.renderTimeout ?? globalRenderTimeout
 
@@ -614,7 +659,7 @@ export function api(options = {}) {
                                 : null
                             const handle = runtime.refs.subscribeGraph({
                                 filter: (entity) => {
-                                    if (query && !query(entity)) return false
+                                    if (matchesScope && !matchesScope(entity)) return false
                                     if (requestFilter && !requestFilter(entity)) return false
                                     return true
                                 },
@@ -645,7 +690,10 @@ export function api(options = {}) {
                     // is a 500. Same shape used by the POST handler below.
                     const status = err instanceof ExpandError ? err.status : 500
                     if (status >= 500) {
-                        logger.error('Api[%s] list error (%dms): %s', name, Date.now() - t0, err.message)
+                        logger.error(
+                            'Api[%s] list error (%dms): %s\n%s',
+                            name, Date.now() - t0, err.message, err.stack || '(no stack)',
+                        )
                     } else {
                         logger.debug('Api[%s] list rejected (%dms): %s', name, Date.now() - t0, err.message)
                     }
@@ -803,6 +851,10 @@ export function api(options = {}) {
             })
 
             router.post('/render', allow('render'), auth, async (req, res) => {
+                // Hoisted so the catch can name WHICH entity failed. A
+                // render that throws before this is assigned is itself the
+                // finding — it means the body never parsed.
+                let renderId
                 try {
                     // Body shape mirrors the JS API: entity fields at top
                     // level, control flags grouped under `options`. Forwarded
@@ -813,19 +865,42 @@ export function api(options = {}) {
                     //   options.save:    false → skip the final disk write
                     //                            (bytes still in the response)
                     const { options = {}, ...entityShape } = req.body
+                    renderId = entityShape.id
                     // When the endpoint declares a scope, reject anything
                     // outside it BEFORE pushing through the renderer.
-                    if (query && !query(entityShape)) {
+                    if (matchesScope && !matchesScope(entityShape)) {
                         return res.status(403).json({ error: 'Entity is outside this endpoint\'s scope' })
                     }
                     const { output, entity } = await render(entityShape, options)
                     await sendRenderOutput(res, output, entity)
                 } catch (err) {
-                    logger.error('Api[%s] render error: %s', name, err.message)
+                    // useRenderer tags an unrenderable entity (no layout)
+                    // with err.status = 422; everything else is a 500.
+                    const status = err.status ?? 500
+                    if (status >= 500) {
+                        // The stack, not just the message — and this is the
+                        // one route where that is not optional. A render
+                        // reaches here through a renderer, a postprocessor
+                        // chain and any template helper they call, so the
+                        // message is routinely a bare TypeError from a frame
+                        // the operator cannot name. Logging `{error: message}`
+                        // alone leaves bisecting deployed versions as the only
+                        // way to find out where it came from, which is exactly
+                        // as expensive as it sounds. The id says which entity;
+                        // `undefined` there means the body never parsed.
+                        logger.error(
+                            'Api[%s] render error for %s: %s\n%s',
+                            name, renderId ?? '(no id in body)', err.message,
+                            err.stack || '(no stack)',
+                        )
+                    } else {
+                        logger.debug(
+                            'Api[%s] render rejected for %s (%d): %s',
+                            name, renderId ?? '(no id in body)', status, err.message,
+                        )
+                    }
                     if (!res.headersSent) {
-                        // useRenderer tags an unrenderable entity (no layout)
-                        // with err.status = 422; everything else is a 500.
-                        res.status(err.status ?? 500).json({ error: err.message })
+                        res.status(status).json({ error: err.message })
                     }
                 }
             })

package/src/runtime.js

@@ -12,6 +12,22 @@ const runtime = {
     journal: [],
     validators: [],
     started: false,
+    // Whether the FIRST build cycle has finished — i.e. whether the catalog
+    // reflects the sources yet. Not the same question as `started`, which is
+    // true from the moment the loaded phase ends, before process() has emitted
+    // a single entity.
+    //
+    // Transports need this. The server binds at the end of the loaded phase, by
+    // design, so that every plugin has registered its routes first — which also
+    // means requests are accepted while the catalog is still empty. A render
+    // arriving then cannot resolve its layout (the layouts registry is filled
+    // during process()), and a list returns whatever subset happens to exist,
+    // which is worse: it is wrong without being an error.
+    //
+    // Set once and never cleared. Later cycles rebuild against a catalog that
+    // is already populated, so they are serveable; flapping this on every watch
+    // rebuild would take the endpoint down for every keystroke.
+    ready: false,
     // Name of the lifecycle phase currently executing — null between
     // phases. Set inside start() / process() / render() etc. before
     // each callHooks(), cleared on completion. Read by mikser-io-mcp's
@@ -85,6 +101,7 @@ const runtime = {
 
         this.started = true
         await this.process()
+        this.ready = true
     },
 
     async process() {