mikser-io 6.9.0 → 6.9.2

package/package.json

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

package/src/api.js

@@ -1,4 +1,4 @@
-// Public, transport-agnostic primitives that the REST plugin's HTTP
+// Public, transport-agnostic primitives that the API plugin's HTTP
 // endpoints are thin wrappers over. Library users embedding mikser
 // programmatically can import these directly.
 
@@ -12,7 +12,7 @@ import { updateEntity as defaultUpdateEntity } from './lifecycle.js'
  * concurrent calls into the minimum number of `runtime.process()` cycles.
  * The returned binding is stateful — each call to useRenderer() owns its
  * own pending queue and `completed`-hook lifecycle. Mount once per
- * consumer (the REST plugin mounts one; a library service mounts its own).
+ * consumer (the API plugin mounts one; a library service mounts its own).
  *
  * @example
  *   const { render } = useRenderer(runtime)

package/src/plugins/api.js

@@ -1,176 +1,175 @@
-import path from 'path'
-import { hash } from 'hasha'
-import _ from 'lodash'
+import path from 'node:path'
+import { access } from 'node:fs/promises'
+import { useRenderer, useCollection } from '../api.js'
+
+// MIME type lookup used when streaming a postprocessor's output back over
+// HTTP. The renderer's output extension lives on entity.destination
+// (assigned by the layouts plugin), so we use it as the source of truth.
+const MIME_BY_EXT = {
+    pdf: 'application/pdf',
+    html: 'text/html; charset=utf-8',
+    xml: 'application/xml; charset=utf-8',
+    xhtml: 'application/xhtml+xml; charset=utf-8',
+    rss: 'application/rss+xml; charset=utf-8',
+    atom: 'application/atom+xml; charset=utf-8',
+    json: 'application/json; charset=utf-8',
+    css: 'text/css; charset=utf-8',
+    js: 'application/javascript; charset=utf-8',
+    svg: 'image/svg+xml',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+    gif: 'image/gif',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    txt: 'text/plain; charset=utf-8',
+    md: 'text/markdown; charset=utf-8',
+}
+
+export function mimeForEntity(entity) {
+    if (!entity?.destination) return null
+    const ext = path.extname(entity.destination).toLowerCase().replace(/^\./, '')
+    return MIME_BY_EXT[ext] ?? null
+}
+
+// Decide how to send the render output over HTTP. Exported (and pure-ish)
+// so tests can exercise the branching without spinning up a real server.
+export async function sendRenderOutput(res, output, entity) {
+    if (output == null || output.result == null) {
+        return res.status(204).send()
+    }
+    const result = output.result
+    const mime = mimeForEntity(entity)
+
+    if (Buffer.isBuffer(result)) {
+        if (mime) res.type(mime)
+        return res.send(result)
+    }
+    if (typeof result === 'string') {
+        // A few postprocessors might return an absolute path to a generated
+        // file rather than its contents. Only attempt this when the string
+        // looks plausibly path-shaped — short, starts with a slash, and the
+        // file actually exists. Otherwise treat it as content.
+        if (result.length < 4096 && (result.startsWith('/') || /^[A-Za-z]:[\\/]/.test(result))) {
+            try {
+                await access(result)
+                return res.sendFile(result)
+            } catch { /* not a path, fall through */ }
+        }
+        if (mime) res.type(mime)
+        return res.send(result)
+    }
+    // Anything else (plain object, etc.) is sent as JSON.
+    return res.json(result)
+}
 
 export default ({
     runtime,
-    useLogger,
-    onImport,
     onLoaded,
-    onSync,
-    createEntity,
+    useLogger,
     updateEntity,
-    deleteEntity,
-    findEntity,
     findEntities,
-    schedule,
-    normalize,
-    trackProgress,
-    updateProgress,
 }) => {
-    const format = 'api'
-
-    async function syncEntities(apiName) {
+    onLoaded(async () => {
         const logger = useLogger()
-        const syncTime = Date.now()
-        const {
-            collection = apiName,
-            type = 'document',
-            readMany,
-            uri = ''
-        } = runtime.config.api[apiName]
-
-        let synced = 0
-        let removed = 0
-        try {
-            const recent = new Set()
-            const entities = await readMany(runtime)
-            trackProgress(`Api sync ${apiName}`, entities.length)
-            for (let meta of entities) {
-                if (collection && type && meta.id) {
-                    const name = path.join(collection, meta.name || meta.id.toString())
-                    const id = path.join('/api', collection, meta.id.toString())
-                    if (recent.has(id)) {
-                        logger.error(meta, 'Duplicate entity found: %s', id)
-                        continue
-                    }
-                    recent.add(id)
-                    const entity = normalize({
-                        id,
-                        uri: `${uri}/${meta.id}`,
-                        name,
-                        collection,
-                        type,
-                        format,
-                        meta
-                    })
-
-                    entity.checksum = await hash(JSON.stringify(entity.meta), { algorithm: 'md5' })
-                    const current = await findEntity({ id })
-                    if (current) {
-                        if (entity.checksum != current.checksum) {
-                            await updateEntity(entity)
-                            synced++
-                        }
-                    } else {
-                        await createEntity(entity)
-                        synced++
-                    }
-                }
-                updateProgress()
-            }
 
-            const entitiesToRemove = await findEntities(entity =>
-                entity.type == type &&
-                entity.format == format &&
-                entity.collection == collection &&
-                entity.time < syncTime &&
-                !recent.has(entity.id)
-            )
-            if (entitiesToRemove.length) trackProgress(`Api remove ${apiName}`, entitiesToRemove.length)
-            for (let entity of entitiesToRemove) {
-                deleteEntity(entity)
-                removed++
-                updateProgress()
-            }
-            if (synced || removed) {
-                logger.debug('Syncing api [%s] synced: %d, removed: %d', collection, synced, removed)
-            }
-        } catch (err) {
-            logger.error('Api sync [%s] error: %s', collection, err.message)
+        const { default: express } = await import('express').catch(() => {
+            throw new Error('express is required for the api plugin — run: npm install express')
+        })
+
+        const ownApp = !runtime.options.app
+        const app = runtime.options.app ?? express()
+
+        const router = express.Router()
+        router.use(express.json())
+
+        const token = runtime.config.api?.token
+        const auth = (req, res, next) => {
+            if (!token) return next()
+            if (req.headers.authorization === `Bearer ${token}`) return next()
+            res.status(401).json({ error: 'Unauthorized' })
         }
-        return synced > 0 || removed > 0
-    }
 
-    async function syncEntity(apiName, apiId) {
-        const logger = useLogger()
-        const {
-            collection = apiName,
-            type = 'document',
-            readOne,
-            uri = ''
-        } = runtime.config.api[apiName]
-
-        try {
-            const id = path.join('/api', collection, apiId.toString())
-            const current = await findEntity({ id })
-            const meta = await readOne(apiId, runtime)
-            if (meta?.id) {
-                const name = path.join(collection, meta.name || meta.id.toString())
-                const entity = normalize({
-                    id,
-                    uri: `${uri}/${meta.id}`,
-                    name,
-                    collection,
-                    type,
-                    format,
-                    meta
+        // Reuse the transport-agnostic primitives from src/api.js so the
+        // library entry point and the Api endpoints share the exact same
+        // batching/timeouts/error semantics.
+        const { render } = useRenderer(runtime, {
+            updateEntity,
+            defaultTimeout: runtime.config.api?.renderTimeout ?? 30_000,
+        })
+
+        router.get('/entities', async (req, res) => {
+            try {
+                const { page: rawPage, limit: rawLimit, ...filter } = req.query
+                const page = Math.max(1, parseInt(rawPage) || 1)
+                const limit = Math.min(100, Math.max(1, parseInt(rawLimit) || (runtime.config.api?.pageSize ?? 10)))
+                const query = Object.keys(filter).length ? filter : undefined
+
+                const all = await findEntities(query)
+                const total = all.length
+                const totalPages = Math.ceil(total / limit)
+                const items = all.slice((page - 1) * limit, page * limit)
+
+                res.json({
+                    items,
+                    page,
+                    limit,
+                    total,
+                    totalPages,
+                    hasNext: page < totalPages,
+                    hasPrev: page > 1,
                 })
-                entity.checksum = await hash(JSON.stringify(entity.meta), { algorithm: 'md5' })
-                if (current) {
-                    if (entity.checksum != current.checksum) {
-                        logger.info('Api update: %s', id)
-                        await updateEntity(entity)
-                    }
-                } else {
-                    logger.info('Api create: %s', id)
-                    await createEntity(entity)
-                }
-            } else {
-                if (current) {
-                    logger.info('Api delete: %s', id)
-                    await deleteEntity(entity)
-                }
+            } catch (err) {
+                logger.error('Api list error: %s', err.message)
+                res.status(500).json({ error: err.message })
             }
-        } catch (err) {
-            logger.error('Api sync entity [%s] error: %s', collection, err.message)
-        }
-    }
+        })
 
-    onLoaded(async () => {
-        const logger = useLogger()
-        for (let apiName in runtime.config.api || {}) {
-            const { cron } = runtime.config.api[apiName]
-            if (cron) {
-                logger.info('Schedule api: [%s] %s', apiName, cron)
-                schedule(apiName, cron)
+        router.put('/entities', auth, async (req, res) => {
+            try {
+                const { collection, relativePath, content = '' } = req.body
+                await useCollection(runtime, collection).write(relativePath, content)
+                res.status(202).json({ ok: true })
+            } catch (err) {
+                logger.error('Api update error: %s', err.message)
+                res.status(/Unknown collection/.test(err.message) ? 400 : 500).json({ error: err.message })
             }
+        })
 
-            onSync(apiName, async ({ context }) => {
-                if (context?.id) {
-                    return syncEntity(apiName, context.id)
-                } else {
-                    return syncEntities(apiName)
-                }
-            })
+        router.delete('/entities', auth, async (req, res) => {
+            try {
+                const { collection, relativePath } = req.body
+                await useCollection(runtime, collection).remove(relativePath)
+                res.status(202).json({ ok: true })
+            } catch (err) {
+                logger.error('Api delete error: %s', err.message)
+                res.status(/Unknown collection/.test(err.message) ? 400 : 500).json({ error: err.message })
+            }
+        })
 
-            const { origin } = new URL(runtime.config.api[apiName].uri)
-            onSync(origin, async ({ context }) => {
-                if (context.uri) {
-                    logger.info('Syncing api: [%s] %s', apiName, context.uri)
-                    return syncEntities(apiName)
+        router.post('/render', auth, async (req, res) => {
+            try {
+                const { output, entity } = await render(req.body)
+                await sendRenderOutput(res, output, entity)
+            } catch (err) {
+                logger.error('Api render error: %s', err.message)
+                if (!res.headersSent) {
+                    res.status(500).json({ error: err.message })
                 }
-            })
-        }
-    })
+            }
+        })
+
+        const base = runtime.config.api?.base ?? '/api'
+        app.use(base, router)
 
-    onImport(async () => {
-        for (let apiName in runtime.config.api || {}) {
-            await syncEntities(apiName)
+        if (ownApp) {
+            const port = runtime.config.api?.port ?? 3001
+            app.listen(port, () => {
+                logger.info('Api listening on port %d %s', port, base)
+            })
+        } else {
+            logger.info('Api mounted on %s', base)
         }
     })
-
-    return {
-        format
-    }
-}
+}

package/src/plugins/observer.js

@@ -0,0 +1,176 @@
+import path from 'path'
+import { hash } from 'hasha'
+import _ from 'lodash'
+
+export default ({
+    runtime,
+    useLogger,
+    onImport,
+    onLoaded,
+    onSync,
+    createEntity,
+    updateEntity,
+    deleteEntity,
+    findEntity,
+    findEntities,
+    schedule,
+    normalize,
+    trackProgress,
+    updateProgress,
+}) => {
+    const format = 'observer'
+
+    async function syncEntities(observerName) {
+        const logger = useLogger()
+        const syncTime = Date.now()
+        const {
+            collection = observerName,
+            type = 'document',
+            readMany,
+            uri = ''
+        } = runtime.config.observer[observerName]
+
+        let synced = 0
+        let removed = 0
+        try {
+            const recent = new Set()
+            const entities = await readMany(runtime)
+            trackProgress(`Observer sync ${observerName}`, entities.length)
+            for (let meta of entities) {
+                if (collection && type && meta.id) {
+                    const name = path.join(collection, meta.name || meta.id.toString())
+                    const id = path.join('/observer', collection, meta.id.toString())
+                    if (recent.has(id)) {
+                        logger.error(meta, 'Duplicate entity found: %s', id)
+                        continue
+                    }
+                    recent.add(id)
+                    const entity = normalize({
+                        id,
+                        uri: `${uri}/${meta.id}`,
+                        name,
+                        collection,
+                        type,
+                        format,
+                        meta
+                    })
+
+                    entity.checksum = await hash(JSON.stringify(entity.meta), { algorithm: 'md5' })
+                    const current = await findEntity({ id })
+                    if (current) {
+                        if (entity.checksum != current.checksum) {
+                            await updateEntity(entity)
+                            synced++
+                        }
+                    } else {
+                        await createEntity(entity)
+                        synced++
+                    }
+                }
+                updateProgress()
+            }
+
+            const entitiesToRemove = await findEntities(entity =>
+                entity.type == type &&
+                entity.format == format &&
+                entity.collection == collection &&
+                entity.time < syncTime &&
+                !recent.has(entity.id)
+            )
+            if (entitiesToRemove.length) trackProgress(`Observer remove ${observerName}`, entitiesToRemove.length)
+            for (let entity of entitiesToRemove) {
+                deleteEntity(entity)
+                removed++
+                updateProgress()
+            }
+            if (synced || removed) {
+                logger.debug('Syncing api [%s] synced: %d, removed: %d', collection, synced, removed)
+            }
+        } catch (err) {
+            logger.error('Observer sync [%s] error: %s', collection, err.message)
+        }
+        return synced > 0 || removed > 0
+    }
+
+    async function syncEntity(observerName, apiId) {
+        const logger = useLogger()
+        const {
+            collection = observerName,
+            type = 'document',
+            readOne,
+            uri = ''
+        } = runtime.config.observer[observerName]
+
+        try {
+            const id = path.join('/observer', collection, apiId.toString())
+            const current = await findEntity({ id })
+            const meta = await readOne(apiId, runtime)
+            if (meta?.id) {
+                const name = path.join(collection, meta.name || meta.id.toString())
+                const entity = normalize({
+                    id,
+                    uri: `${uri}/${meta.id}`,
+                    name,
+                    collection,
+                    type,
+                    format,
+                    meta
+                })
+                entity.checksum = await hash(JSON.stringify(entity.meta), { algorithm: 'md5' })
+                if (current) {
+                    if (entity.checksum != current.checksum) {
+                        logger.info('Observer update: %s', id)
+                        await updateEntity(entity)
+                    }
+                } else {
+                    logger.info('Observer create: %s', id)
+                    await createEntity(entity)
+                }
+            } else {
+                if (current) {
+                    logger.info('Observer delete: %s', id)
+                    await deleteEntity(entity)
+                }
+            }
+        } catch (err) {
+            logger.error('Observer sync entity [%s] error: %s', collection, err.message)
+        }
+    }
+
+    onLoaded(async () => {
+        const logger = useLogger()
+        for (let observerName in runtime.config.observer || {}) {
+            const { cron } = runtime.config.observer[observerName]
+            if (cron) {
+                logger.info('Schedule observer: [%s] %s', observerName, cron)
+                schedule(observerName, cron)
+            }
+
+            onSync(observerName, async ({ context }) => {
+                if (context?.id) {
+                    return syncEntity(observerName, context.id)
+                } else {
+                    return syncEntities(observerName)
+                }
+            })
+
+            const { origin } = new URL(runtime.config.observer[observerName].uri)
+            onSync(origin, async ({ context }) => {
+                if (context.uri) {
+                    logger.info('Syncing observer: [%s] %s', observerName, context.uri)
+                    return syncEntities(observerName)
+                }
+            })
+        }
+    })
+
+    onImport(async () => {
+        for (let observerName in runtime.config.observer || {}) {
+            await syncEntities(observerName)
+        }
+    })
+
+    return {
+        format
+    }
+}

package/src/plugins/rest.js

@@ -1,175 +0,0 @@
-import path from 'node:path'
-import { access } from 'node:fs/promises'
-import { useRenderer, useCollection } from '../api.js'
-
-// MIME type lookup used when streaming a postprocessor's output back over
-// HTTP. The renderer's output extension lives on entity.destination
-// (assigned by the layouts plugin), so we use it as the source of truth.
-const MIME_BY_EXT = {
-    pdf: 'application/pdf',
-    html: 'text/html; charset=utf-8',
-    xml: 'application/xml; charset=utf-8',
-    xhtml: 'application/xhtml+xml; charset=utf-8',
-    rss: 'application/rss+xml; charset=utf-8',
-    atom: 'application/atom+xml; charset=utf-8',
-    json: 'application/json; charset=utf-8',
-    css: 'text/css; charset=utf-8',
-    js: 'application/javascript; charset=utf-8',
-    svg: 'image/svg+xml',
-    png: 'image/png',
-    jpg: 'image/jpeg',
-    jpeg: 'image/jpeg',
-    webp: 'image/webp',
-    gif: 'image/gif',
-    mp4: 'video/mp4',
-    webm: 'video/webm',
-    txt: 'text/plain; charset=utf-8',
-    md: 'text/markdown; charset=utf-8',
-}
-
-export function mimeForEntity(entity) {
-    if (!entity?.destination) return null
-    const ext = path.extname(entity.destination).toLowerCase().replace(/^\./, '')
-    return MIME_BY_EXT[ext] ?? null
-}
-
-// Decide how to send the render output over HTTP. Exported (and pure-ish)
-// so tests can exercise the branching without spinning up a real server.
-export async function sendRenderOutput(res, output, entity) {
-    if (output == null || output.result == null) {
-        return res.status(204).send()
-    }
-    const result = output.result
-    const mime = mimeForEntity(entity)
-
-    if (Buffer.isBuffer(result)) {
-        if (mime) res.type(mime)
-        return res.send(result)
-    }
-    if (typeof result === 'string') {
-        // A few postprocessors might return an absolute path to a generated
-        // file rather than its contents. Only attempt this when the string
-        // looks plausibly path-shaped — short, starts with a slash, and the
-        // file actually exists. Otherwise treat it as content.
-        if (result.length < 4096 && (result.startsWith('/') || /^[A-Za-z]:[\\/]/.test(result))) {
-            try {
-                await access(result)
-                return res.sendFile(result)
-            } catch { /* not a path, fall through */ }
-        }
-        if (mime) res.type(mime)
-        return res.send(result)
-    }
-    // Anything else (plain object, etc.) is sent as JSON.
-    return res.json(result)
-}
-
-export default ({
-    runtime,
-    onLoaded,
-    useLogger,
-    updateEntity,
-    findEntities,
-}) => {
-    onLoaded(async () => {
-        const logger = useLogger()
-
-        const { default: express } = await import('express').catch(() => {
-            throw new Error('express is required for the rest plugin — run: npm install express')
-        })
-
-        const ownApp = !runtime.options.app
-        const app = runtime.options.app ?? express()
-
-        const router = express.Router()
-        router.use(express.json())
-
-        const token = runtime.config.rest?.token
-        const auth = (req, res, next) => {
-            if (!token) return next()
-            if (req.headers.authorization === `Bearer ${token}`) return next()
-            res.status(401).json({ error: 'Unauthorized' })
-        }
-
-        // Reuse the transport-agnostic primitives from src/api.js so the
-        // library entry point and the REST endpoints share the exact same
-        // batching/timeouts/error semantics.
-        const { render } = useRenderer(runtime, {
-            updateEntity,
-            defaultTimeout: runtime.config.rest?.renderTimeout ?? 30_000,
-        })
-
-        router.get('/entities', async (req, res) => {
-            try {
-                const { page: rawPage, limit: rawLimit, ...filter } = req.query
-                const page = Math.max(1, parseInt(rawPage) || 1)
-                const limit = Math.min(100, Math.max(1, parseInt(rawLimit) || (runtime.config.rest?.pageSize ?? 10)))
-                const query = Object.keys(filter).length ? filter : undefined
-
-                const all = await findEntities(query)
-                const total = all.length
-                const totalPages = Math.ceil(total / limit)
-                const items = all.slice((page - 1) * limit, page * limit)
-
-                res.json({
-                    items,
-                    page,
-                    limit,
-                    total,
-                    totalPages,
-                    hasNext: page < totalPages,
-                    hasPrev: page > 1,
-                })
-            } catch (err) {
-                logger.error('REST list error: %s', err.message)
-                res.status(500).json({ error: err.message })
-            }
-        })
-
-        router.put('/entities', auth, async (req, res) => {
-            try {
-                const { collection, relativePath, content = '' } = req.body
-                await useCollection(runtime, collection).write(relativePath, content)
-                res.status(202).json({ ok: true })
-            } catch (err) {
-                logger.error('REST update error: %s', err.message)
-                res.status(/Unknown collection/.test(err.message) ? 400 : 500).json({ error: err.message })
-            }
-        })
-
-        router.delete('/entities', auth, async (req, res) => {
-            try {
-                const { collection, relativePath } = req.body
-                await useCollection(runtime, collection).remove(relativePath)
-                res.status(202).json({ ok: true })
-            } catch (err) {
-                logger.error('REST delete error: %s', err.message)
-                res.status(/Unknown collection/.test(err.message) ? 400 : 500).json({ error: err.message })
-            }
-        })
-
-        router.post('/render', auth, async (req, res) => {
-            try {
-                const { output, entity } = await render(req.body)
-                await sendRenderOutput(res, output, entity)
-            } catch (err) {
-                logger.error('REST render error: %s', err.message)
-                if (!res.headersSent) {
-                    res.status(500).json({ error: err.message })
-                }
-            }
-        })
-
-        const base = runtime.config.rest?.base ?? '/mikser'
-        app.use(base, router)
-
-        if (ownApp) {
-            const port = runtime.config.rest?.port ?? 3001
-            app.listen(port, () => {
-                logger.info('REST plugin listening on port %d', port)
-            })
-        } else {
-            logger.info('REST plugin mounted on %s', base)
-        }
-    })
-}