@knowark/loggarkjs 0.4.0 → 0.5.0

package/README.md

@@ -50,3 +50,16 @@ const logger = new Logger({
   flat: false
 })
 ```
+
+## Journald integration
+
+Set the boolean `globalThis.JOURNALD` flag to `true` and `Logger` will open `/run/systemd/journal/socket` for you. Every JSON record is translated into Journald fields (`PRIORITY`, `MESSAGE`, `LEVEL`, optional `SYSLOG_IDENTIFIER`, and uppercased context payloads), so you can pipe `logger.info()` calls directly into `journalctl` for centralized viewing.
+
+```js
+globalThis.JOURNALD = true
+const logger = new Logger({ namespace: 'api' })
+
+logger.info('User login', { userId: 'u-123', extra: undefined })
+```
+
+Undefined values are dropped, `null` turns into the string `'null'`, and functions/symbols are rendered so Journald receives a predictable payload. The socket connection is cached per process, so later `Logger` instances reuse the same transport without extra setup.

package/lib/logger.js

@@ -1,3 +1,5 @@
+import { journaldSocket } from './utilities/journald-socket.js'
+
 export class Logger {
   static context () {
     return null
@@ -14,6 +16,7 @@ export class Logger {
       Boolean).join('_').toUpperCase().replaceAll(' ', '_')
     this.global = global
     this.#context = context
+    this.journald = getJournaldTransport(this.global)
   }
 
   get context () {
@@ -27,23 +30,23 @@ export class Logger {
   }
 
   log (...args) {
-    if (this.logindex >= 0) log(this.global, 'log', this.context, args, this.namespace, this.format, this.flat)
+    if (this.logindex >= 0) log(this.global, 'log', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 
   error (...args) {
-    if (this.logindex >= 0) log(this.global, 'error', this.context, args, this.namespace, this.format, this.flat)
+    if (this.logindex >= 0) log(this.global, 'error', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 
   warn (...args) {
-    if (this.logindex >= 1) log(this.global, 'warn', this.context, args, this.namespace, this.format, this.flat)
+    if (this.logindex >= 1) log(this.global, 'warn', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 
   info (...args) {
-    if (this.logindex >= 2) log(this.global, 'info', this.context, args, this.namespace, this.format, this.flat)
+    if (this.logindex >= 2) log(this.global, 'info', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 
   debug (...args) {
-    if (this.logindex >= 3) log(this.global, 'debug', this.context, args, this.namespace, this.format, this.flat)
+    if (this.logindex >= 3) log(this.global, 'debug', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 }
 
@@ -94,16 +97,73 @@ function stringifyJson (payload) {
   })
 }
 
-function log (global, level, context, args, namespace, format, flat) {
-  const timestamp = new global.Date().toISOString()
+export const JOURNAL_PRIORITY = {
+  log: 6,
+  error: 3,
+  warn: 4,
+  info: 6,
+  debug: 7
+}
 
-  if (format === 'plain') {
-    const message = [`${timestamp} [${level.toUpperCase()}]`]
-    if (context) message.push(stringifyJson(context))
-    message.push(...args)
-    return global.console[level](...message)
+function toJournaldFields (record) {
+  const entry = {
+    PRIORITY: JOURNAL_PRIORITY[record.level] ?? 6,
+    MESSAGE: serializeJournaldValue(record.message) ?? '',
+    TIMESTAMP: record.timestamp,
+    LEVEL: record.level
+  }
+
+  if (record.namespace) {
+    entry.SYSLOG_IDENTIFIER = record.namespace
+  }
+
+  for (const [key, value] of Object.entries(record)) {
+    if (['timestamp', 'level', 'namespace', 'message'].includes(key)) continue
+    const normalized = serializeJournaldValue(value)
+    if (normalized !== undefined) {
+      entry[key.toUpperCase()] = normalized
+    }
+  }
+
+  return entry
+}
+
+function serializeJournaldValue (value) {
+  if (value === undefined) return undefined
+  if (value === null) return 'null'
+  if (typeof value === 'function') return `[Function ${value.name || 'anonymous'}]`
+  if (typeof value === 'symbol') return value.toString()
+  if (typeof value === 'object') return stringifyJson(value)
+  return String(value)
+}
+
+let defaultJournaldTransport = null
+
+function getJournaldTransport (global) {
+  if (!global?.JOURNALD) return null
+  if (defaultJournaldTransport) return defaultJournaldTransport
+  defaultJournaldTransport = journaldSocket.createTransport()
+  return defaultJournaldTransport
+}
+
+function sendToJournald (journald, fields) {
+  if (typeof journald === 'function') {
+    journald(fields)
+    return
+  }
+
+  if (journald && typeof journald.send === 'function') {
+    journald.send(fields)
+    return
   }
 
+  if (journald && typeof journald.log === 'function') {
+    journald.log(fields)
+  }
+}
+
+function log (global, level, context, args, namespace, format, flat, journald) {
+  const timestamp = new global.Date().toISOString()
   const record = {
     ...(flat && context ? context : {}),
     timestamp,
@@ -113,5 +173,20 @@ function log (global, level, context, args, namespace, format, flat) {
     ...parseArgs(args)
   }
 
-  return global.console[level](stringifyJson(record))
+  let consoleResult
+
+  if (format === 'plain') {
+    const message = [`${timestamp} [${level.toUpperCase()}]`]
+    if (context) message.push(stringifyJson(context))
+    message.push(...args)
+    consoleResult = global.console[level](...message)
+  } else {
+    consoleResult = global.console[level](stringifyJson(record))
+  }
+
+  if (journald) {
+    sendToJournald(journald, toJournaldFields(record))
+  }
+
+  return consoleResult
 }

package/lib/logger.test.js

@@ -1,6 +1,20 @@
 import assert from 'node:assert/strict'
-import { it } from 'node:test'
-import { Logger } from './logger.js'
+import test, { it } from 'node:test'
+
+const journaldTransportState = { lastFields: null }
+
+const journaldSocketModule = await import('./utilities/journald-socket.js')
+const { journaldSocket } = journaldSocketModule
+test.mock.method(journaldSocket, 'createTransport', () => {
+  return {
+    send (fields) {
+      journaldTransportState.lastFields = fields
+    }
+  }
+})
+
+const loggerModule = await import('./logger.js')
+const { Logger, JOURNAL_PRIORITY } = loggerModule
 
 function setup () {
   const mockGlobal = {
@@ -392,3 +406,187 @@ it('supports plain formatting without context labels', () => {
     '2025-02-15T00:00:00.000Z [INFO]'
   ])
 })
+
+it('reports JSON records to Journald when the global flag is enabled', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  journaldTransportState.lastFields = null
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal })
+
+  logger.info('Journald event', { action: 'create' })
+
+  const fields = journaldTransportState.lastFields
+  assert.ok(fields)
+  assert.deepStrictEqual(fields, {
+    PRIORITY: 6,
+    MESSAGE: 'Journald event',
+    TIMESTAMP: '2025-02-15T00:00:00.000Z',
+    LEVEL: 'info',
+    ACTION: 'create'
+  })
+
+  delete mockGlobal.JOURNALD
+})
+
+it('serializes nested context for Journald when flattening is disabled', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const context = { correlationId: 'ABCD1234', nested: { role: 'admin' } }
+  journaldTransportState.lastFields = null
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal, context, flat: false })
+
+  logger.info('Nested context')
+
+  const fields = journaldTransportState.lastFields
+  assert.ok(fields)
+  assert.strictEqual(fields.CONTEXT, JSON.stringify(context))
+  assert.strictEqual(fields.MESSAGE, 'Nested context')
+  assert.strictEqual(fields.PRIORITY, 6)
+
+  delete mockGlobal.JOURNALD
+})
+
+it('defaults Journald MESSAGE to an empty string when no message is provided', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal })
+  let recorded
+  logger.journald = (fields) => { recorded = fields }
+
+  const payload = { action: 'create', detail: undefined }
+  logger.info(payload)
+
+  assert.ok(recorded)
+  assert.strictEqual(recorded.MESSAGE, '')
+  assert.strictEqual(recorded.ACTION, 'create')
+  assert.ok(!('DETAIL' in recorded))
+
+  delete mockGlobal.JOURNALD
+})
+
+it('falls back to the default Journald priority when the level is missing', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal })
+  let recorded
+  logger.journald = (fields) => { recorded = fields }
+
+  const original = JOURNAL_PRIORITY.info
+  delete JOURNAL_PRIORITY.info
+
+  try {
+    logger.info('Fallback priority')
+    assert.ok(recorded)
+    assert.strictEqual(recorded.PRIORITY, 6)
+  } finally {
+    JOURNAL_PRIORITY.info = original
+    delete mockGlobal.JOURNALD
+  }
+})
+
+it('serializes null, function, and symbol values for Journald payloads', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal })
+  let recorded
+  logger.journald = (fields) => { recorded = fields }
+
+  const symbol = Symbol('token')
+  function namedFn () {}
+  const anonymousFn = Object.defineProperty(function () {}, 'name', { value: '' })
+  const payload = {
+    value: null,
+    handler: namedFn,
+    key: symbol,
+    unused: undefined,
+    data: { detail: 'rich' },
+    shadowed: anonymousFn
+  }
+  logger.info('Special types', payload)
+
+  assert.ok(recorded)
+  assert.strictEqual(recorded.VALUE, 'null')
+  assert.strictEqual(recorded.HANDLER, '[Function namedFn]')
+  assert.strictEqual(recorded.KEY, 'Symbol(token)')
+  assert.strictEqual(recorded.DATA, JSON.stringify(payload.data))
+  assert.strictEqual(recorded.SHADOWED, '[Function anonymous]')
+  assert.ok(!('UNUSED' in recorded))
+
+  delete mockGlobal.JOURNALD
+})
+
+it('includes the namespace as SYSLOG_IDENTIFIER in Journald payloads', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.CORE_LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal, namespace: 'core' })
+
+  let recorded
+  logger.journald = (fields) => {
+    recorded = fields
+  }
+
+  logger.info('Namespaced event', { module: 'inventory' })
+
+  assert.ok(recorded)
+  assert.strictEqual(recorded.SYSLOG_IDENTIFIER, 'core')
+  assert.strictEqual(recorded.MESSAGE, 'Namespaced event')
+  assert.strictEqual(recorded.MODULE, 'inventory')
+})
+
+it('calls journald transports that are functions directly', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  const payloads = []
+  logger.journald = (fields) => {
+    payloads.push(fields)
+  }
+
+  logger.info('Function transport')
+
+  assert.strictEqual(payloads.length, 1)
+  assert.strictEqual(payloads[0].LEVEL, 'info')
+  assert.strictEqual(payloads[0].MESSAGE, 'Function transport')
+})
+
+it('prefers send() when the Journald transport exposes it', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  const payloads = []
+  logger.journald = {
+    send (fields) {
+      payloads.push(fields)
+    }
+  }
+
+  logger.info('Send transport')
+
+  assert.strictEqual(payloads.length, 1)
+  assert.strictEqual(payloads[0].MESSAGE, 'Send transport')
+})
+
+it('falls back to log() when send() is unavailable', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  const payloads = []
+  logger.journald = {
+    log (fields) {
+      payloads.push(fields)
+    }
+  }
+
+  logger.info('Log transport')
+
+  assert.strictEqual(payloads.length, 1)
+  assert.strictEqual(payloads[0].MESSAGE, 'Log transport')
+})

package/lib/utilities/journald-socket.js

@@ -0,0 +1,51 @@
+import { createSocket } from 'node:dgram'
+
+const JOURNAL_SOCKET_PATH = '/run/systemd/journal/socket'
+
+function buildTransport (createSocketImplementation) {
+  try {
+    const socket = createSocketImplementation({ type: 'unix_dgram' })
+    let activeSocket = socket
+
+    const cleanup = () => {
+      if (!activeSocket) return
+      activeSocket.close()
+      activeSocket = null
+    }
+
+    socket.on('error', cleanup)
+    socket.on('close', cleanup)
+    socket.connect(JOURNAL_SOCKET_PATH, (error) => {
+      if (error) cleanup()
+    })
+    socket.unref?.()
+
+    return {
+      send (fields) {
+        if (!activeSocket) return
+        const payload = Buffer.from(
+          Object.entries(fields).map(
+            ([key, value]) => `${key}=${value}`).join('\n') + '\n')
+        activeSocket.send(payload, (error) => {
+          if (error) cleanup()
+        })
+      }
+    }
+  } catch (error) {
+    throw error
+  }
+}
+
+export function createJournaldTransport ({ createSocket: createSocketImplementation } = {}) {
+  try {
+    return buildTransport(createSocketImplementation ?? createSocket)
+  } catch (error) {
+    return null
+  }
+}
+
+export const journaldSocket = {
+  createTransport (options) {
+    return createJournaldTransport(options)
+  }
+}

package/lib/utilities/journald-socket.test.js

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict'
+import { it } from 'node:test'
+import { createJournaldTransport, journaldSocket } from './journald-socket.js'
+
+function createFakeSocket ({ connectError = null, sendError = null } = {}) {
+  const events = {}
+  return {
+    events,
+    connectedPath: null,
+    sentPayload: null,
+    sendCalls: 0,
+    closed: false,
+    on (event, callback) {
+      events[event] = callback
+    },
+    connect (path, callback) {
+      this.connectedPath = path
+      callback?.(connectError)
+    },
+    send (payload, callback) {
+      this.sentPayload = payload
+      this.sendCalls += 1
+      callback?.(sendError)
+    },
+    close () {
+      this.closed = true
+    },
+    unref () {}
+  }
+}
+
+it('falls back to the built-in socket factory when no override is supplied', () => {
+  const transport = createJournaldTransport()
+
+  assert.ok(transport === null || typeof transport.send === 'function')
+})
+
+it('establishes a journald socket and encodes payloads', () => {
+  const socket = createFakeSocket()
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  assert.ok(transport)
+  assert.strictEqual(socket.connectedPath, '/run/systemd/journal/socket')
+
+  transport.send({ foo: 'bar', baz: 'qux' })
+  assert.strictEqual(socket.sendCalls, 1)
+  assert.strictEqual(socket.sentPayload.toString(), 'foo=bar\nbaz=qux\n')
+})
+
+it('silently ignores send once cleanup runs after an error event', () => {
+  const socket = createFakeSocket()
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  socket.events.error?.(new Error('boom'))
+
+  transport.send({ foo: 'bar' })
+  assert.strictEqual(socket.sendCalls, 0)
+  assert.strictEqual(socket.closed, true)
+})
+
+it('returns null when the socket factory throws', () => {
+  const transport = createJournaldTransport({ createSocket: () => { throw new Error('failed') } })
+  assert.strictEqual(transport, null)
+})
+
+it('exposes the same transport via journaldSocket.createTransport', () => {
+  const socket = createFakeSocket()
+  const createSocket = () => socket
+  const transport = journaldSocket.createTransport({ createSocket })
+
+  assert.ok(transport)
+  assert.strictEqual(socket.connectedPath, '/run/systemd/journal/socket')
+})
+
+it('runs cleanup when connect reports an error', () => {
+  const socket = createFakeSocket({ connectError: new Error('connect fail') })
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  assert.ok(transport)
+  assert.strictEqual(socket.closed, true)
+
+  transport.send({ foo: 'bar' })
+  assert.strictEqual(socket.sendCalls, 0)
+})
+
+it('runs cleanup when send reports an error', () => {
+  const socket = createFakeSocket({ sendError: new Error('send fail') })
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  transport.send({ foo: 'bar' })
+  assert.strictEqual(socket.closed, true)
+  assert.strictEqual(socket.sendCalls, 1)
+})
+
+it('safely ignores repeated cleanup calls', () => {
+  const socket = createFakeSocket()
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  socket.events.error?.(new Error('boom'))
+  socket.events.error?.(new Error('boom again'))
+
+  transport.send({ foo: 'bar' })
+  assert.strictEqual(socket.closed, true)
+  assert.strictEqual(socket.sendCalls, 0)
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowark/loggarkjs",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Utilitarian Logging Library",
   "main": "./lib/index.js",
   "type": "module",