@meith/web 0.16.0

package/src/server/plugin-admin-actions.ts

@@ -0,0 +1,232 @@
+'use server'
+
+import forumConfig from '@board/config'
+import { revalidatePath } from 'next/cache'
+
+import { CacheTags, env, isAppError, logger, readPluginEnv, ValidationError } from '@meith/core'
+import { clearPluginHealth, getDb, PostgresSettingsRepository } from '@meith/db'
+import { drivers } from '@meith/drivers'
+import {
+  type PluginDefinition,
+  parsePluginSetting,
+  pluginEnabledKey,
+  pluginSettingType,
+  resolvePluginSettingDetails,
+  serialisePluginSetting,
+} from '@meith/plugin-kit'
+import { runPluginLifecycle } from '@meith/runtime'
+
+import { recordAdminAction, requireAdmin, requireFreshAdmin } from './admin'
+import type { FormState } from './auth-form-state'
+import { tr } from './i18n'
+import { syncPluginNavigation } from './navigation'
+import {
+  invalidatePluginHealth,
+  reconcilePluginHealth,
+  recordPluginFault,
+  syncPluginEnablement,
+} from './plugin-host'
+import { emitEvent } from './plugin-view'
+import { getSettingOverrides } from './settings'
+
+function requireDefinition(key: string): PluginDefinition {
+  const entry = (forumConfig.plugins ?? []).find((candidate) => candidate.key === key)
+  const definition = entry?.plugin as PluginDefinition | undefined
+
+  if (entry === undefined) {
+    throw new ValidationError(`No plugin named "${key}" is installed on this board.`)
+  }
+  if (definition === undefined) {
+    throw new ValidationError(
+      `"${key}" is registered without a definition, so there is nothing to configure.`,
+    )
+  }
+  return definition
+}
+
+async function invalidateSettings(): Promise<void> {
+  await drivers().cache.invalidateTags([CacheTags.settings()])
+  revalidatePath('/admin/plugins')
+  revalidatePath('/admin/plugins/[key]/[[...path]]', 'page')
+}
+
+export async function setPluginEnabledAction(_prev: FormState, form: FormData): Promise<FormState> {
+  try {
+    const key = String(form.get('key') ?? '')
+    const enabled = form.get('enabled') === '1'
+
+    if (enabled) {
+      await requireAdmin()
+    } else {
+      await requireFreshAdmin()
+    }
+
+    const definition = requireDefinition(key)
+
+    const repository = new PostgresSettingsRepository(getDb())
+    if (enabled) {
+      await repository.delete([pluginEnabledKey(key)])
+    } else {
+      await repository.save(new Map([[pluginEnabledKey(key), '0']]))
+    }
+
+    await invalidateSettings()
+    await syncPluginEnablement()
+    await syncPluginNavigation()
+
+    /*
+     * After the switch is written, so the callback sees the state it is being
+     * told about, and never for the host's own failure switch: a plugin that
+     * has just failed five times is not one to hand more work to.
+     */
+    await announceSwitch(definition, enabled)
+
+    await recordAdminAction({
+      action: enabled ? 'plugin.enabled' : 'plugin.disabled',
+      detail: { plugin: key },
+    })
+
+    return { notice: enabled ? 'enabled' : 'disabled' }
+  } catch (err) {
+    if (isAppError(err)) return { error: err.message }
+    logger({ module: 'plugin-admin' }).error({ err }, 'failed to change plugin enablement')
+    return { error: await tr('notice.app.something-went-wrong-please-try') }
+  }
+}
+
+/**
+ * The switch has already been thrown by the time this runs, and it stays
+ * thrown: a callback that throws is the plugin's fault, so it is counted and
+ * reported like any other plugin failure rather than being reported as the
+ * operator's action having failed.
+ */
+async function announceSwitch(definition: PluginDefinition, enabled: boolean): Promise<void> {
+  if (enabled) {
+    await emitEvent('plugin.enabled', { pluginKey: definition.key }, {})
+  } else {
+    await emitEvent('plugin.disabled', { pluginKey: definition.key, reason: 'operator' }, {})
+  }
+
+  if (env.DATA_SOURCE !== 'postgres') return
+
+  try {
+    await runPluginLifecycle({
+      db: getDb(),
+      plugin: definition,
+      phase: enabled ? 'enable' : 'disable',
+    })
+  } catch (err) {
+    logger({ module: 'plugin-admin' }).error(
+      { err, plugin: definition.key },
+      `plugin ${enabled ? 'onEnable' : 'onDisable'} failed`,
+    )
+    await recordPluginFault(definition.key, enabled ? 'onEnable' : 'onDisable', err)
+  }
+}
+
+export async function clearPluginHealthAction(
+  _prev: FormState,
+  form: FormData,
+): Promise<FormState> {
+  try {
+    await requireFreshAdmin()
+
+    const key = String(form.get('key') ?? '')
+    requireDefinition(key)
+
+    await clearPluginHealth(getDb(), key)
+    await invalidatePluginHealth()
+    await reconcilePluginHealth()
+
+    revalidatePath('/admin/plugins')
+    revalidatePath('/admin/plugins/[key]/[[...path]]', 'page')
+
+    await recordAdminAction({ action: 'plugin.health-cleared', detail: { plugin: key } })
+
+    return { notice: 'cleared' }
+  } catch (err) {
+    if (isAppError(err)) return { error: err.message }
+    logger({ module: 'plugin-admin' }).error({ err }, 'failed to clear plugin health')
+    return { error: await tr('notice.app.something-went-wrong-please-try') }
+  }
+}
+
+export async function savePluginSettingsAction(
+  _prev: FormState,
+  form: FormData,
+): Promise<FormState> {
+  try {
+    await requireAdmin()
+
+    const key = String(form.get('key') ?? '')
+    const definition = requireDefinition(key)
+    const declared = definition.settings ?? []
+
+    if (declared.length === 0) {
+      throw new ValidationError(`"${key}" declares no settings.`)
+    }
+
+    const resolved = resolvePluginSettingDetails(
+      definition,
+      await getSettingOverrides(),
+      readPluginEnv,
+    )
+    const environmentOwned = new Set(
+      resolved
+        .filter((detail) => detail.source === 'environment')
+        .map((detail) => detail.setting.key),
+    )
+
+    const updates = new Map<string, string>()
+    for (const setting of declared) {
+      const field = `setting.${setting.key}`
+      const type = pluginSettingType(setting)
+      const raw = form.get(field)
+
+      if (environmentOwned.has(setting.key)) continue
+      if (raw === null && type !== 'boolean') continue
+
+      if (type === 'boolean') {
+        updates.set(`plugin.${key}.${setting.key}`, raw === '1' ? '1' : '0')
+        continue
+      }
+
+      if (type === 'secret') {
+        if (typeof raw !== 'string' || raw === '') continue
+        updates.set(`plugin.${key}.${setting.key}`, raw)
+        continue
+      }
+
+      if (type === 'select') {
+        const value = typeof raw === 'string' ? raw : ''
+        if (!(setting.options ?? []).some((option) => option.value === value)) {
+          throw new ValidationError(`“${setting.label}” must be one of its listed options.`)
+        }
+        updates.set(`plugin.${key}.${setting.key}`, value)
+        continue
+      }
+
+      const parsed = parsePluginSetting(setting, typeof raw === 'string' ? raw : '')
+      if (parsed === null) {
+        throw new ValidationError(
+          `“${setting.label}” needs ${typeof setting.default === 'number' ? 'a number' : 'a value'}.`,
+        )
+      }
+      updates.set(`plugin.${key}.${setting.key}`, serialisePluginSetting(parsed))
+    }
+
+    await new PostgresSettingsRepository(getDb()).save(updates)
+    await invalidateSettings()
+
+    await recordAdminAction({
+      action: 'plugin.configured',
+      detail: { plugin: key, keys: [...updates.keys()] },
+    })
+
+    return { notice: 'saved' }
+  } catch (err) {
+    if (isAppError(err)) return { error: err.message }
+    logger({ module: 'plugin-admin' }).error({ err }, 'failed to save plugin settings')
+    return { error: await tr('notice.app.something-went-wrong-please-try') }
+  }
+}

package/src/server/plugin-admin.ts

@@ -0,0 +1,276 @@
+import 'server-only'
+
+import forumConfig from '@board/config'
+
+import { env, logger, readPluginEnv } from '@meith/core'
+import {
+  appliedPluginMigrations,
+  getDb,
+  type PluginHealthRecord,
+  readPluginHealth,
+} from '@meith/db'
+import type { Translator } from '@meith/i18n'
+import {
+  type PluginDefinition,
+  type PluginHealth,
+  type PluginSettingSource,
+  type PluginSettingType,
+  type PluginSettingValue,
+  pluginAdminPath,
+  pluginSettingType,
+  pluginTaskId,
+  resolvePluginSettingDetails,
+} from '@meith/plugin-kit'
+
+import { configuredPlugins, pluginHost, syncPluginEnablement } from './plugin-host'
+import { getSettingOverrides } from './settings'
+
+export type PluginSettingKind = PluginSettingType
+
+export interface PluginSettingRow {
+  readonly key: string
+  readonly label: string
+  readonly description: string | null
+  readonly advanced: boolean
+  readonly kind: PluginSettingKind
+  /** '' for a secret, whatever is stored or not: the value never leaves the server. */
+  readonly default: PluginSettingValue
+  readonly value: PluginSettingValue
+  readonly overridden: boolean
+  readonly source: PluginSettingSource
+  /** For secrets: whether a non-empty value is in force, without saying what it is. */
+  readonly set: boolean
+  readonly options: readonly { readonly value: string; readonly label: string }[]
+  readonly envName: string | null
+  readonly problem: string | null
+}
+
+export interface PluginDurableHealthRow {
+  readonly failures: number
+  readonly disabledAt: string | null
+  readonly reason: string | null
+}
+
+export interface PluginMigrationRow {
+  readonly id: string
+  readonly applied: boolean
+}
+
+export interface PluginTaskRow {
+  readonly id: string
+  readonly registeredId: string
+  readonly intervalSeconds: number
+}
+
+export interface PluginPageRow {
+  readonly path: string
+  readonly title: string
+  readonly href: string
+}
+
+export interface PluginRow {
+  readonly key: string
+  readonly name: string | null
+  readonly version: string | null
+  readonly description: string | null
+  readonly dependsOn: readonly string[]
+  readonly hasDefinition: boolean
+
+  readonly configuredEnabled: boolean
+  readonly operatorEnabled: boolean
+  readonly running: boolean
+
+  readonly health: PluginHealth | null
+  /** The record every instance reconciles against, not this process's tally. */
+  readonly durableHealth: PluginDurableHealthRow | null
+  readonly hooks: readonly string[]
+  readonly regions: readonly string[]
+  readonly settings: readonly PluginSettingRow[]
+  readonly migrations: readonly PluginMigrationRow[]
+  readonly tasks: readonly PluginTaskRow[]
+  readonly pages: readonly PluginPageRow[]
+}
+
+export interface PluginInventory {
+  readonly plugins: readonly PluginRow[]
+  readonly migrationsKnown: boolean
+}
+
+function translated(
+  t: Translator | undefined,
+  key: string | undefined,
+  fallback: string,
+  args?: Parameters<Translator['t']>[1],
+): string {
+  return t !== undefined && key !== undefined && t.has(key) ? t.t(key, args) : fallback
+}
+
+function definitionsByKey(): ReadonlyMap<string, PluginDefinition | undefined> {
+  return new Map(
+    (forumConfig.plugins ?? []).map((entry) => [
+      entry.key,
+      entry.plugin as PluginDefinition | undefined,
+    ]),
+  )
+}
+
+async function durableHealthByPlugin(): Promise<ReadonlyMap<string, PluginHealthRecord>> {
+  if (env.DATA_SOURCE !== 'postgres') return new Map()
+
+  try {
+    return new Map((await readPluginHealth(getDb())).map((row) => [row.pluginKey, row]))
+  } catch (error) {
+    logger().warn({ err: String(error) }, 'could not read plugin health')
+    return new Map()
+  }
+}
+
+async function appliedByPlugin(
+  keys: readonly string[],
+): Promise<ReadonlyMap<string, readonly string[]> | null> {
+  if (keys.length === 0) return new Map()
+  if (env.DATA_SOURCE !== 'postgres') return null
+
+  try {
+    const db = getDb()
+    const applied = new Map<string, readonly string[]>()
+    for (const key of keys) {
+      applied.set(key, await appliedPluginMigrations(db, key))
+    }
+    return applied
+  } catch (error) {
+    logger().warn({ err: String(error) }, 'could not read applied plugin migrations')
+    return null
+  }
+}
+
+export async function pluginInventory(t?: Translator): Promise<PluginInventory> {
+  const definitions = definitionsByKey()
+  const overrides = await getSettingOverrides()
+  await syncPluginEnablement()
+  const health = new Map(pluginHost.health().map((entry) => [entry.key, entry]))
+
+  const withMigrations = [...definitions]
+    .filter(([, definition]) => (definition?.migrations ?? []).length > 0)
+    .map(([key]) => key)
+  const applied = await appliedByPlugin(withMigrations)
+  const durable = await durableHealthByPlugin()
+
+  const plugins = configuredPlugins().map((entry): PluginRow => {
+    const definition = definitions.get(entry.key)
+    const configuredEnabled = entry.enabled
+    const operatorEnabled = overrides.get(`plugin.${entry.key}._enabled`) !== '0'
+    const entryHealth = health.get(entry.key) ?? null
+    const details =
+      definition === undefined
+        ? []
+        : resolvePluginSettingDetails(definition, overrides, readPluginEnv)
+
+    return {
+      key: entry.key,
+      name:
+        definition === undefined
+          ? entry.name
+          : translated(t, definition.nameKey, entry.name ?? definition.name),
+      version: entry.version,
+      description:
+        definition?.description === undefined
+          ? null
+          : translated(
+              t,
+              definition.descriptionKey,
+              definition.description,
+              definition.descriptionArgs,
+            ),
+      dependsOn: definition?.dependsOn ?? [],
+      hasDefinition: entry.hasDefinition,
+
+      configuredEnabled,
+      operatorEnabled,
+      running: configuredEnabled && operatorEnabled && (entryHealth?.enabled ?? false),
+
+      health: entryHealth,
+      durableHealth: toDurableHealth(durable.get(entry.key)),
+      hooks: Object.keys(definition?.hooks ?? {}).sort(),
+      regions: [...new Set((definition?.contributions ?? []).map((c) => c.region))].sort(),
+
+      settings: details.map(({ setting, value, source, problem }): PluginSettingRow => {
+        const kind = pluginSettingType(setting)
+        const secret = kind === 'secret'
+        return {
+          key: setting.key,
+          label: translated(t, setting.labelKey, setting.label),
+          description:
+            setting.description === undefined
+              ? null
+              : translated(t, setting.descriptionKey, setting.description),
+          advanced: setting.advanced === true,
+          kind,
+          default: secret ? '' : setting.default,
+          value: secret ? '' : value,
+          overridden: overrides.has(`plugin.${entry.key}.${setting.key}`),
+          source,
+          set: typeof value === 'string' ? value !== '' : true,
+          options: (setting.options ?? []).map((option) => ({
+            value: option.value,
+            label: translated(t, option.labelKey, option.label),
+          })),
+          envName: setting.env ?? null,
+          problem,
+        }
+      }),
+
+      migrations: (definition?.migrations ?? []).map(
+        (migration): PluginMigrationRow => ({
+          id: migration.id,
+          applied: (applied?.get(entry.key) ?? []).includes(migration.id),
+        }),
+      ),
+
+      tasks: (definition?.tasks ?? []).map(
+        (task): PluginTaskRow => ({
+          id: task.id,
+          registeredId: pluginTaskId(entry.key, task.id),
+          intervalSeconds: task.intervalSeconds,
+        }),
+      ),
+
+      pages: (definition?.adminPages ?? []).map(
+        (page): PluginPageRow => ({
+          path: page.path,
+          title: translated(t, page.titleKey, page.title, page.titleArgs),
+          href: pluginAdminPath(entry.key, page.path),
+        }),
+      ),
+    }
+  })
+
+  return { plugins, migrationsKnown: withMigrations.length === 0 || applied !== null }
+}
+
+function toDurableHealth(record: PluginHealthRecord | undefined): PluginDurableHealthRow | null {
+  if (record === undefined) return null
+
+  return {
+    failures: record.failures,
+    disabledAt: record.disabledAt === null ? null : record.disabledAt.toISOString(),
+    reason: record.reason,
+  }
+}
+
+export async function pluginRow(key: string, t?: Translator): Promise<PluginRow | null> {
+  const inventory = await pluginInventory(t)
+  return inventory.plugins.find((plugin) => plugin.key === key) ?? null
+}
+
+export interface HookListenerRow {
+  readonly hook: string
+  readonly plugins: readonly string[]
+}
+
+export function hookListeners(): readonly HookListenerRow[] {
+  return Object.entries(pluginHost.listeners())
+    .filter(([, plugins]) => plugins.length > 0)
+    .map(([hook, plugins]) => ({ hook, plugins }))
+    .sort((a, b) => (a.hook < b.hook ? -1 : a.hook > b.hook ? 1 : 0))
+}

package/src/server/plugin-host.ts

@@ -0,0 +1,143 @@
+import 'server-only'
+
+import forumConfig from '@board/config'
+import { cache } from 'react'
+
+import { CacheTags, cachedGlobal, env } from '@meith/core'
+import { logger } from '@meith/core/logger'
+import { getDb, readPluginHealth, recordPluginFailure } from '@meith/db'
+import { drivers } from '@meith/drivers'
+import {
+  type DurablyDisabledPlugin,
+  operatorDisabledPlugins,
+  type PluginDefinition,
+  PluginHost,
+} from '@meith/plugin-kit'
+
+import { getSettingOverrides } from './settings'
+
+const HEALTH_TTL_SECONDS = 30
+
+export const FAILURE_THRESHOLD = 5
+
+export interface ConfiguredPlugin {
+  readonly key: string
+  readonly enabled: boolean
+  readonly hasDefinition: boolean
+  readonly name: string | null
+  readonly version: string | null
+}
+
+export function configuredPlugins(): readonly ConfiguredPlugin[] {
+  return (forumConfig.plugins ?? []).map((entry) => {
+    const definition = entry.plugin as PluginDefinition | undefined
+    return {
+      key: entry.key,
+      enabled: entry.enabled !== false,
+      hasDefinition: definition !== undefined,
+      name: definition?.name ?? null,
+      version: definition?.version ?? null,
+    }
+  })
+}
+
+export function activeDefinitions(): readonly PluginDefinition[] {
+  return (forumConfig.plugins ?? [])
+    .filter((entry) => entry.enabled !== false && entry.plugin !== undefined)
+    .map((entry) => entry.plugin as PluginDefinition)
+}
+
+export const pluginHost = new PluginHost({
+  plugins: activeDefinitions(),
+  failureThreshold: FAILURE_THRESHOLD,
+  logger: {
+    warn: (message, detail) => logger().warn(detail, message),
+    error: (message, detail) => logger().error(detail, message),
+  },
+  health: {
+    failed: (failure) => {
+      void persistFailure(failure.pluginKey, failure.threshold, failure.hook, failure.message)
+    },
+  },
+})
+
+/**
+ * A plugin failing somewhere the host does not itself dispatch — a lifecycle
+ * callback — counted and reported exactly as a failing hook is. There is one
+ * failure record per plugin, and an operator reading it should not have to know
+ * which door the plugin was behind when it broke.
+ */
+export async function recordPluginFault(
+  pluginKey: string,
+  surface: string,
+  error: unknown,
+): Promise<void> {
+  await persistFailure(
+    pluginKey,
+    FAILURE_THRESHOLD,
+    surface,
+    error instanceof Error ? error.message : String(error),
+  )
+}
+
+async function persistFailure(
+  pluginKey: string,
+  threshold: number,
+  hook: string,
+  message: string,
+): Promise<void> {
+  if (env.DATA_SOURCE !== 'postgres') return
+
+  try {
+    const record = await recordPluginFailure(getDb(), {
+      pluginKey,
+      threshold,
+      reason: `${threshold} failures, most recently in "${hook}": ${message}`,
+    })
+    if (record.disabledAt !== null) {
+      await invalidatePluginHealth()
+      await pluginHost.emit('plugin.disabled', { pluginKey, reason: 'failures' }, {})
+    }
+  } catch (error) {
+    logger().warn({ err: String(error), plugin: pluginKey }, 'could not record plugin failure')
+  }
+}
+
+export async function invalidatePluginHealth(): Promise<void> {
+  await drivers().cache.invalidateTags([CacheTags.pluginHealth()])
+}
+
+export async function durablyDisabledPlugins(): Promise<readonly DurablyDisabledPlugin[]> {
+  if (env.DATA_SOURCE !== 'postgres') return []
+
+  return cachedGlobal<readonly DurablyDisabledPlugin[]>(
+    drivers().cache,
+    {
+      key: ['plugin', 'health', 'disabled'],
+      tags: [CacheTags.pluginHealth()],
+      revalidate: HEALTH_TTL_SECONDS,
+    },
+    async () =>
+      (await readPluginHealth(getDb()))
+        .filter((row) => row.disabledAt !== null)
+        .map((row) => ({ key: row.pluginKey, reason: row.reason ?? 'repeated failures' })),
+  )
+}
+
+export async function reconcilePluginHealth(): Promise<void> {
+  pluginHost.setDurablyDisabled(await durablyDisabledPlugins())
+}
+
+export const syncPluginEnablement = cache(async (): Promise<void> => {
+  try {
+    pluginHost.setOperatorDisabled(operatorDisabledPlugins(await getSettingOverrides()))
+  } catch (error) {
+    logger().warn({ err: String(error) }, 'could not read plugin enablement')
+  }
+
+  try {
+    pluginHost.setDurablyDisabled(await durablyDisabledPlugins())
+  } catch (error) {
+    logger().warn({ err: String(error) }, 'could not read plugin health')
+  }
+})