@meith/runtime 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@meith/runtime",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/runtime"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/api": "0.16.0",
+    "@meith/attachments": "0.16.0",
+    "@meith/core": "0.16.0",
+    "@meith/avatars": "0.16.0",
+    "@meith/drivers": "0.16.0",
+    "@meith/i18n": "0.16.0",
+    "@meith/accounts": "0.16.0",
+    "@meith/events": "0.16.0",
+    "@meith/groups": "0.16.0",
+    "@meith/marketplace": "0.16.0",
+    "@meith/mail": "0.16.0",
+    "@meith/db": "0.16.0",
+    "@meith/markdown": "0.16.0",
+    "@meith/notifications": "0.16.0",
+    "@meith/moderation": "0.16.0",
+    "@meith/plugin-kit": "0.16.0",
+    "@meith/tasks": "0.16.0",
+    "@meith/settings": "0.16.0",
+    "@meith/theme-default": "0.16.0"
+  }
+}

package/src/event-handlers.ts

@@ -0,0 +1,98 @@
+import { EventRegistry } from '@meith/events'
+
+export interface EventHandlerDeps {
+  readonly counters: {
+    rollUpAncestors(postId: number): Promise<boolean>
+    applyVisibilityChange(postId: number): Promise<boolean>
+  }
+  readonly notifications?: {
+    deliverEmail?(notificationId: number): Promise<void>
+    deliverPush?(notificationId: number): Promise<void>
+  }
+  readonly attachments?: {
+    process(attachmentId: number): Promise<unknown>
+  }
+  readonly avatars?: {
+    process(userId: number): Promise<unknown>
+  }
+  readonly massMail?: {
+    send(input: { massMailId: number; userId: number; email: string }): Promise<void>
+  }
+}
+
+export function buildEventRegistry(deps: EventHandlerDeps): EventRegistry {
+  const registry = new EventRegistry()
+    .register({
+      id: 'counters.rollup',
+      event: 'post.created',
+      async handle(payload) {
+        await deps.counters.rollUpAncestors(payload.postId)
+      },
+    })
+    .register({
+      id: 'counters.visibility',
+      event: 'post.visibility_changed',
+      async handle(payload) {
+        await deps.counters.applyVisibilityChange(payload.postId)
+      },
+    })
+
+  if (deps.attachments !== undefined) {
+    registry.register({
+      id: 'attachments.process',
+      event: 'attachment.uploaded',
+      async handle(payload) {
+        await deps.attachments!.process(payload.attachmentId)
+      },
+    })
+  }
+
+  if (deps.avatars !== undefined) {
+    registry.register({
+      id: 'avatars.process',
+      event: 'avatar.uploaded',
+      async handle(payload) {
+        await deps.avatars!.process(payload.userId)
+      },
+    })
+  }
+
+  if (deps.massMail !== undefined) {
+    registry.register({
+      id: 'admin.mass_mail',
+      event: 'admin.mass_mail_queued',
+      async handle(payload) {
+        await deps.massMail!.send({
+          massMailId: payload.massMailId,
+          userId: payload.userId,
+          email: payload.email,
+        })
+      },
+    })
+  }
+
+  const notifications = deps.notifications
+  if (notifications === undefined) return registry
+
+  if (notifications.deliverEmail !== undefined) {
+    registry.register({
+      id: 'notifications.email',
+      event: 'notification.created',
+      async handle(payload) {
+        await notifications.deliverEmail!(payload.notificationId)
+      },
+    })
+  }
+
+  if (notifications.deliverPush !== undefined) {
+    registry.register({
+      id: 'notifications.push',
+      event: 'notification.created',
+      async handle(payload) {
+        await notifications.deliverPush!(payload.notificationId)
+      },
+    })
+  }
+
+  return registry
+}

package/src/groups.ts

@@ -0,0 +1,9 @@
+export const SEED_GROUP = {
+  guest: 1,
+  registered: 2,
+  administrators: 3,
+  superModerators: 4,
+  moderators: 5,
+  awaitingActivation: 6,
+  banned: 7,
+} as const

package/src/index.ts

@@ -0,0 +1,14 @@
+export { buildEventRegistry, type EventHandlerDeps } from './event-handlers'
+export { SEED_GROUP } from './groups'
+export {
+  DEFAULT_THEME_KEY,
+  type MailBrandDeps,
+  resolveMailBrand,
+  SHIPPED_TOKENS,
+  type ThemeTokenRegistry,
+} from './mail-brand'
+export { PLUGIN_STATEMENT_TIMEOUT_MS, pluginRuntimeContext } from './plugin-context'
+export { type PluginLifecyclePhase, runPluginLifecycle } from './plugin-lifecycle'
+export { pluginTasks } from './plugin-tasks'
+export { buildSchedulerBundle, type SchedulerBundle } from './scheduler-bundle'
+export { defaultPromotionGuards, type TaskWorkerDeps, taskWorkers } from './task-workers'

package/src/mail-brand.ts

@@ -0,0 +1,83 @@
+import { env, logger } from '@meith/core'
+import { type Database, PostgresSettingsRepository, PostgresThemeRepository } from '@meith/db'
+import {
+  buildMailBrand,
+  type MailBrand,
+  mergeTokenOverrides,
+  type ThemeTokenSet,
+} from '@meith/mail'
+import { resolveBoardUrl, SettingsSnapshot } from '@meith/settings'
+import { DARK_TOKENS, LIGHT_TOKENS } from '@meith/theme-default'
+
+export const DEFAULT_THEME_KEY = 'default'
+
+export type ThemeTokenRegistry = Readonly<Record<string, ThemeTokenSet>>
+
+export const SHIPPED_TOKENS: ThemeTokenRegistry = {
+  [DEFAULT_THEME_KEY]: { light: LIGHT_TOKENS, dark: DARK_TOKENS },
+}
+
+export interface MailBrandDeps {
+  readonly db: Database
+  readonly themeKey?: string
+  readonly themeTokens?: ThemeTokenRegistry
+}
+
+async function themeTokens(deps: MailBrandDeps): Promise<ThemeTokenSet | null> {
+  const registry = deps.themeTokens ?? SHIPPED_TOKENS
+  const buildKey = deps.themeKey ?? DEFAULT_THEME_KEY
+
+  const rows = await new PostgresThemeRepository(deps.db).listRuntime()
+  const claimed = rows.find(
+    (row) => row.isDefault && row.enabled && registry[row.key] !== undefined,
+  )
+
+  const key = claimed?.key ?? buildKey
+  const baseline = registry[key] ?? registry[DEFAULT_THEME_KEY] ?? SHIPPED_TOKENS[DEFAULT_THEME_KEY]
+  if (baseline === undefined) return null
+
+  const overrides = rows.find((row) => row.key === key)?.tokenOverrides ?? null
+
+  return mergeTokenOverrides(baseline, overrides)
+}
+
+export async function resolveMailBrand(deps: MailBrandDeps): Promise<MailBrand> {
+  let boardName = ''
+  let fromName = ''
+  let boardUrl = ''
+  let logo: { lightKey: string; darkKey: string; alt: string } | undefined
+  let tokens: ThemeTokenSet | null = null
+
+  try {
+    const overrides = await new PostgresSettingsRepository(deps.db).loadAll()
+    const settings = SettingsSnapshot.fromOverrides(new Map(overrides))
+
+    boardName = settings.get('board.name')
+    fromName = settings.get('mail.from_name')
+    boardUrl = resolveBoardUrl({ environment: env, settings }).url
+
+    const alt = settings.get('board.logo_alt').trim()
+    logo = {
+      lightKey: settings.get('board.logo_light'),
+      darkKey: settings.get('board.logo_dark'),
+      alt: alt === '' ? boardName : alt,
+    }
+  } catch (err) {
+    logger({ module: 'mail-brand' }).warn({ err }, 'could not read board name for mail')
+  }
+
+  try {
+    tokens = await themeTokens(deps)
+  } catch (err) {
+    logger({ module: 'mail-brand' }).warn({ err }, 'could not read theme tokens for mail')
+    tokens = SHIPPED_TOKENS[DEFAULT_THEME_KEY] ?? null
+  }
+
+  return buildMailBrand({
+    boardName,
+    fromName,
+    boardUrl,
+    tokens,
+    ...(logo === undefined ? {} : { logo }),
+  })
+}

package/src/plugin-context.ts

@@ -0,0 +1,56 @@
+import { logger, readPluginEnv } from '@meith/core'
+import {
+  type Database,
+  PostgresNotificationRepository,
+  PostgresSettingsRepository,
+  pluginData,
+  pluginGrants,
+  pluginUsers,
+} from '@meith/db'
+import { NotificationService } from '@meith/notifications'
+import {
+  type PluginDefinition,
+  type PluginRuntimeContext,
+  pluginNotificationKindSpecs,
+  pluginNotify,
+  resolvePluginSettings,
+} from '@meith/plugin-kit'
+
+export const PLUGIN_STATEMENT_TIMEOUT_MS = 30_000
+
+/**
+ * The context every plugin callback is handed: its resolved settings, a logger
+ * that says which plugin is talking, and the four runtime capabilities. Built
+ * in one place so a task, an install and a purge cannot drift into offering a
+ * plugin different powers depending on which door it came through.
+ */
+export async function pluginRuntimeContext(input: {
+  readonly db: Database
+  readonly plugin: PluginDefinition
+  readonly component: string
+  readonly overrides?: ReadonlyMap<string, string>
+  readonly statementTimeoutMs?: number
+}): Promise<PluginRuntimeContext> {
+  const overrides = input.overrides ?? (await new PostgresSettingsRepository(input.db).loadAll())
+  const log = logger({ component: input.component, plugin: input.plugin.key })
+
+  const notifications = new NotificationService({
+    notifications: new PostgresNotificationRepository(input.db),
+    extraKinds: pluginNotificationKindSpecs(input.plugin.key, input.plugin.notifications ?? []),
+  })
+
+  return {
+    settings: resolvePluginSettings(input.plugin, overrides, readPluginEnv),
+    logger: {
+      info: (message, detail) => log.info(detail ?? {}, message),
+      warn: (message, detail) => log.warn(detail ?? {}, message),
+      error: (message, detail) => log.error(detail ?? {}, message),
+    },
+    grants: pluginGrants(input.db, input.plugin.key),
+    data: pluginData(input.db, input.plugin.key, {
+      statementTimeoutMs: input.statementTimeoutMs ?? PLUGIN_STATEMENT_TIMEOUT_MS,
+    }),
+    users: pluginUsers(input.db),
+    notify: pluginNotify(input.plugin.key, input.plugin.notifications ?? [], notifications),
+  }
+}

package/src/plugin-lifecycle.ts

@@ -0,0 +1,41 @@
+import type { Database } from '@meith/db'
+import type { PluginDefinition } from '@meith/plugin-kit'
+
+import { pluginRuntimeContext } from './plugin-context'
+
+export type PluginLifecyclePhase = 'install' | 'enable' | 'disable' | 'uninstall'
+
+const CALLBACKS: Readonly<Record<PluginLifecyclePhase, keyof PluginDefinition>> = {
+  install: 'onInstall',
+  enable: 'onEnable',
+  disable: 'onDisable',
+  uninstall: 'onUninstall',
+}
+
+/**
+ * Run one lifecycle callback, or report that the plugin declares none.
+ *
+ * It throws what the callback throws, deliberately. These do not run inside the
+ * host's try/catch, because that isolation exists to keep a page rendering and
+ * none of these is on a page: an install that half-worked should stop the
+ * deploy rather than be swallowed, and each caller states its own policy.
+ */
+export async function runPluginLifecycle(input: {
+  readonly db: Database
+  readonly plugin: PluginDefinition
+  readonly phase: PluginLifecyclePhase
+  readonly overrides?: ReadonlyMap<string, string>
+}): Promise<{ readonly ran: boolean }> {
+  const callback = input.plugin[CALLBACKS[input.phase]]
+  if (typeof callback !== 'function') return { ran: false }
+
+  const context = await pluginRuntimeContext({
+    db: input.db,
+    plugin: input.plugin,
+    component: `plugin-${input.phase}`,
+    ...(input.overrides === undefined ? {} : { overrides: input.overrides }),
+  })
+
+  await (callback as (ctx: typeof context) => Promise<void> | void)(context)
+  return { ran: true }
+}

package/src/plugin-rendering.ts

@@ -0,0 +1,60 @@
+import type { MailDriver, OutgoingMail } from '@meith/core'
+import type { MarkdownPipeline } from '@meith/markdown'
+import type { PluginHost } from '@meith/plugin-kit'
+
+export function pluginMarkdownPipeline(host: PluginHost): MarkdownPipeline {
+  return {
+    text: (text, context) =>
+      host.applyFilter('markdown.parse.text', text, {
+        ...context.viewer,
+        source: context.source,
+      }),
+
+    html: (html, context) =>
+      host.applyFilter('markdown.render.html', html, {
+        ...context.viewer,
+        source: context.source,
+      }),
+
+    vocabulary: async (source) => ({
+      revision: source.revision,
+      directives: await host.applyFilter('markdown.directives', source.directives, {}),
+      smilies: await host.applyFilter('smilies.list', source.smilies, {}),
+    }),
+  }
+}
+
+/**
+ * A message on its way out of the worker, past the plugins first. Returning
+ * null from `mail.send.before` drops it; nothing tells the recipient, because
+ * nobody was waiting on a page for it.
+ */
+export async function sendAudited(
+  host: PluginHost,
+  mail: MailDriver,
+  template: string,
+  outgoing: OutgoingMail,
+): Promise<void> {
+  const proposed = await host.applyFilter(
+    'mail.send.before',
+    {
+      to: outgoing.to,
+      subject: outgoing.subject,
+      textBody: outgoing.text,
+      htmlBody: outgoing.html ?? null,
+    },
+    { template },
+  )
+
+  if (proposed === null) return
+
+  await mail.send({
+    ...outgoing,
+    to: proposed.to,
+    subject: proposed.subject,
+    text: proposed.textBody,
+    ...(proposed.htmlBody === null ? {} : { html: proposed.htmlBody }),
+  })
+
+  await host.emit('mail.sent', { to: proposed.to, template }, { requestId: null })
+}

package/src/plugin-tasks.ts

@@ -0,0 +1,52 @@
+import { type Database, PostgresSettingsRepository, readPluginHealth } from '@meith/db'
+import { type PluginDefinition, pluginEnabledKey, pluginTaskId } from '@meith/plugin-kit'
+import type { TaskDefinition } from '@meith/tasks'
+
+import { pluginRuntimeContext } from './plugin-context'
+
+const MAX_DURATION_SECONDS = 60
+
+export function pluginTasks(options: {
+  readonly db: Database
+  readonly plugins: readonly PluginDefinition[]
+}): TaskDefinition[] {
+  const definitions: TaskDefinition[] = []
+
+  for (const plugin of options.plugins) {
+    for (const task of plugin.tasks ?? []) {
+      const id = pluginTaskId(plugin.key, task.id)
+
+      definitions.push({
+        id,
+        title: `${plugin.name}: ${task.id}`,
+        description: `Scheduled task contributed by the "${plugin.key}" plugin.`,
+        intervalSeconds: task.intervalSeconds,
+        maxDurationSeconds: MAX_DURATION_SECONDS,
+        async run() {
+          const overrides = await new PostgresSettingsRepository(options.db).loadAll()
+          if (overrides.get(pluginEnabledKey(plugin.key)) === '0') return {}
+
+          const health = (await readPluginHealth(options.db)).find(
+            (row) => row.pluginKey === plugin.key,
+          )
+          if (health?.disabledAt != null) {
+            return { detail: { skipped: 'disabled after repeated failures' } }
+          }
+
+          await task.run(
+            await pluginRuntimeContext({
+              db: options.db,
+              plugin,
+              component: 'plugin-task',
+              overrides,
+            }),
+          )
+
+          return {}
+        },
+      })
+    }
+  }
+
+  return definitions
+}