@meith/drivers 0.16.0

package/src/highlighting/shiki-highlighter.ts

@@ -0,0 +1,92 @@
+import { createHighlighter, type Highlighter } from 'shiki'
+
+const LANGUAGES = [
+  'bash',
+  'c',
+  'cpp',
+  'csharp',
+  'css',
+  'diff',
+  'dockerfile',
+  'go',
+  'graphql',
+  'html',
+  'http',
+  'ini',
+  'java',
+  'json',
+  'kotlin',
+  'markdown',
+  'php',
+  'python',
+  'ruby',
+  'rust',
+  'sql',
+  'swift',
+  'toml',
+  'tsx',
+  'typescript',
+  'yaml',
+] as const
+
+type Language = (typeof LANGUAGES)[number]
+
+const ALIASES: Readonly<Record<string, Language>> = {
+  sh: 'bash',
+  shell: 'bash',
+  zsh: 'bash',
+  console: 'bash',
+  'c++': 'cpp',
+  cs: 'csharp',
+  js: 'typescript',
+  jsx: 'tsx',
+  javascript: 'typescript',
+  mjs: 'typescript',
+  cjs: 'typescript',
+  ts: 'typescript',
+  py: 'python',
+  python3: 'python',
+  rb: 'ruby',
+  rs: 'rust',
+  md: 'markdown',
+  yml: 'yaml',
+  env: 'ini',
+  docker: 'dockerfile',
+  golang: 'go',
+}
+
+function resolveLanguage(requested: string | undefined): Language | null {
+  if (requested === undefined) return null
+  const lower = requested.toLowerCase()
+  const resolved = ALIASES[lower] ?? lower
+  return (LANGUAGES as readonly string[]).includes(resolved) ? (resolved as Language) : null
+}
+
+let highlighter: Promise<Highlighter> | null = null
+
+function getHighlighter(): Promise<Highlighter> {
+  highlighter ??= createHighlighter({
+    themes: ['vitesse-light', 'vitesse-dark'],
+    langs: [...LANGUAGES],
+  })
+  return highlighter
+}
+
+export interface CodeHighlighter {
+  highlight(code: string, language: string | undefined): Promise<string | null>
+}
+
+export const codeHighlighter: CodeHighlighter = {
+  async highlight(code, language) {
+    const resolved = resolveLanguage(language)
+    if (resolved === null) return null
+
+    const shiki = await getHighlighter()
+    return shiki.codeToHtml(code, {
+      lang: resolved,
+      themes: { light: 'vitesse-light', dark: 'vitesse-dark' },
+      defaultColor: false,
+      structure: 'inline',
+    })
+  },
+}

package/src/images/codec.ts

@@ -0,0 +1,76 @@
+import decodeJpeg, { init as initJpegDecode } from '@jsquash/jpeg/decode.js'
+import encodeJpeg, { init as initJpegEncode } from '@jsquash/jpeg/encode.js'
+import decodePng, { init as initPngDecode } from '@jsquash/png/decode.js'
+import encodePng, { init as initPngEncode } from '@jsquash/png/encode.js'
+import resizeImage, { initResize } from '@jsquash/resize'
+
+import { compileAsset } from './locate-wasm'
+
+const WASM = {
+  png: '@jsquash/png/codec/pkg/squoosh_png_bg.wasm',
+  jpegDecode: '@jsquash/jpeg/codec/dec/mozjpeg_dec.wasm',
+  jpegEncode: '@jsquash/jpeg/codec/enc/mozjpeg_enc.wasm',
+  resize: '@jsquash/resize/lib/resize/pkg/squoosh_resize_bg.wasm',
+} as const
+
+let ready: Promise<void> | null = null
+
+async function initOne(
+  init: (module: WebAssembly.Module) => Promise<unknown>,
+  specifier: string,
+): Promise<void> {
+  await init(await compileAsset(specifier))
+}
+
+function initialise(): Promise<void> {
+  ready ??= (async () => {
+    await Promise.all([
+      initOne(initPngDecode, WASM.png),
+      initOne(initPngEncode, WASM.png),
+      initOne(initJpegDecode, WASM.jpegDecode),
+      initOne(initJpegEncode, WASM.jpegEncode),
+      initOne(initResize, WASM.resize),
+    ])
+  })().catch((error: unknown) => {
+    ready = null
+    throw error
+  })
+  return ready
+}
+
+export interface DecodedImage {
+  readonly width: number
+  readonly height: number
+  readonly data: Uint8ClampedArray<ArrayBuffer>
+  readonly colorSpace: PredefinedColorSpace
+}
+
+export type ImageFormat = 'png' | 'jpeg'
+
+export async function decodeImage(bytes: ArrayBuffer, format: ImageFormat): Promise<DecodedImage> {
+  await initialise()
+  return format === 'png' ? decodePng(bytes) : decodeJpeg(bytes)
+}
+
+export async function encodeImage(
+  image: DecodedImage,
+  format: ImageFormat,
+  quality = 82,
+): Promise<ArrayBuffer> {
+  await initialise()
+  return format === 'png' ? encodePng(image) : encodeJpeg(image, { quality })
+}
+
+export async function resizeToFit(
+  image: DecodedImage,
+  max: { readonly width: number; readonly height: number },
+): Promise<DecodedImage> {
+  await initialise()
+  const scale = Math.min(max.width / image.width, max.height / image.height, 1)
+  if (scale >= 1) return image
+
+  return resizeImage(image, {
+    width: Math.max(1, Math.round(image.width * scale)),
+    height: Math.max(1, Math.round(image.height * scale)),
+  })
+}

package/src/images/index.ts

@@ -0,0 +1,9 @@
+export {
+  type DecodedImage,
+  decodeImage,
+  encodeImage,
+  type ImageFormat,
+  resizeToFit,
+} from './codec'
+export { compileAsset, locateAsset } from './locate-wasm'
+export { imageProcessor } from './processor'

package/src/images/locate-wasm.ts

@@ -0,0 +1,108 @@
+import { access, readdir, readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join, parse } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const found = new Map<string, string>()
+
+const cacheKey = (specifier: string, from: string) => `${from}\u0000${specifier}`
+
+export function moduleFile(metaUrl: unknown, filename: unknown): string | undefined {
+  if (typeof metaUrl === 'string' && metaUrl.startsWith('file:')) return fileURLToPath(metaUrl)
+  return typeof filename === 'string' && filename !== '' ? filename : undefined
+}
+
+function ownRequire(): NodeRequire | undefined {
+  try {
+    const here = moduleFile(
+      import.meta.url,
+      typeof __filename === 'string' ? __filename : undefined,
+    )
+    return here === undefined ? undefined : createRequire(here)
+  } catch {
+    return undefined
+  }
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function storePrefix(specifier: string): string {
+  const parts = specifier.split('/')
+  return specifier.startsWith('@') ? `${parts[0]}+${parts[1]}@` : `${parts[0]}@`
+}
+
+function ancestors(from: string): string[] {
+  const root = parse(from).root
+  const chain: string[] = []
+  let current = from
+  while (true) {
+    chain.push(current)
+    if (current === root) return chain
+    const next = dirname(current)
+    if (next === current) return chain
+    current = next
+  }
+}
+
+async function candidatesUnder(nodeModules: string, specifier: string): Promise<string[]> {
+  const paths = [join(nodeModules, specifier)]
+
+  const prefix = storePrefix(specifier)
+  let entries: string[]
+  try {
+    entries = await readdir(join(nodeModules, '.pnpm'))
+  } catch {
+    return paths
+  }
+
+  for (const entry of entries
+    .filter((e) => e.startsWith(prefix))
+    .sort()
+    .reverse()) {
+    paths.push(join(nodeModules, '.pnpm', entry, 'node_modules', specifier))
+  }
+  return paths
+}
+
+export async function locateAsset(specifier: string, from = process.cwd()): Promise<string> {
+  const key = cacheKey(specifier, from)
+  const cached = found.get(key)
+  if (cached !== undefined) return cached
+
+  const required = ownRequire()
+  if (required !== undefined) {
+    try {
+      const path = required.resolve(specifier)
+      found.set(key, path)
+      return path
+    } catch {
+      /* ignore */
+    }
+  }
+
+  for (const dir of ancestors(from)) {
+    for (const candidate of await candidatesUnder(join(dir, 'node_modules'), specifier)) {
+      if (await exists(candidate)) {
+        found.set(key, candidate)
+        return candidate
+      }
+    }
+  }
+
+  throw new Error(
+    `Could not find "${specifier}" in any node_modules above ${from}. ` +
+      'The deployment did not copy the package — check `serverExternalPackages`.',
+  )
+}
+
+export async function compileAsset(specifier: string): Promise<WebAssembly.Module> {
+  const path = await locateAsset(specifier)
+  return WebAssembly.compile(await readFile(/* turbopackIgnore: true */ path))
+}

package/src/images/processor.ts

@@ -0,0 +1,40 @@
+import { type ImageProcessor, MAX_IMAGE, type ProcessedImage, THUMBNAIL } from '@meith/attachments'
+
+import { decodeImage, encodeImage, resizeToFit } from './codec'
+
+const ATTACHMENT_QUALITY = 85
+
+const THUMBNAIL_QUALITY = 70
+
+function toBytes(buffer: ArrayBuffer): Uint8Array {
+  return new Uint8Array(buffer)
+}
+
+export const imageProcessor: ImageProcessor = {
+  async process(input) {
+    const decoded = await decodeImage(input.bytes.slice().buffer as ArrayBuffer, input.codec)
+
+    const fitted = await resizeToFit(decoded, input.fit ?? MAX_IMAGE)
+    const bytes = toBytes(await encodeImage(fitted, input.codec, ATTACHMENT_QUALITY))
+
+    const wantsThumbnail = input.thumbnail ?? true
+    const preview = wantsThumbnail ? await resizeToFit(fitted, THUMBNAIL) : fitted
+
+    const processed: ProcessedImage = {
+      bytes,
+      contentType: input.codec === 'png' ? 'image/png' : 'image/jpeg',
+      width: fitted.width,
+      height: fitted.height,
+      ...(preview === fitted
+        ? {}
+        : {
+            thumbnail: {
+              bytes: toBytes(await encodeImage(preview, 'jpeg', THUMBNAIL_QUALITY)),
+              contentType: 'image/jpeg',
+            },
+          }),
+    }
+
+    return processed
+  },
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { MemoryCache } from './cache/memory-cache'
+export { NextCacheDriver } from './cache/next-cache'
+export { RedisCacheDriver, type RedisCacheOptions } from './cache/redis-cache'
+export { LocalFileStore } from './files/local-file-store'
+export { S3FileStore, type S3FileStoreConfig, type S3Like } from './files/s3-file-store'
+export {
+  ConfiguredMailDriver,
+  createMailDriver,
+  formatSender,
+  HttpMailDriver,
+  LogMailDriver,
+  MemoryMailDriver,
+  SmtpMailDriver,
+} from './mail'
+export { MemoryQueue } from './queue/memory-queue'
+export { PostgresQueue } from './queue/postgres-queue'
+export { currentMailConfig, drivers, resetDriversForTests } from './resolve'

package/src/mail/index.ts

@@ -0,0 +1,113 @@
+import { ConfigurationError, logger, type MailDriver, type OutgoingMail } from '@meith/core'
+import {
+  canSendMail,
+  describeMailConfig,
+  type HttpMailConfig,
+  type MailConfig,
+  mailConfigProblems,
+} from '@meith/settings'
+
+import { formatSender } from './sender'
+import { SmtpMailDriver } from './smtp'
+
+export { formatSender } from './sender'
+export { SmtpMailDriver } from './smtp'
+
+export class LogMailDriver implements MailDriver {
+  send(mail: OutgoingMail): Promise<void> {
+    logger({ driver: 'log' }).info(
+      { to: mail.to, subject: mail.subject },
+      'mail (not actually sent)',
+    )
+    return Promise.resolve()
+  }
+}
+
+export class MemoryMailDriver implements MailDriver {
+  readonly sent: OutgoingMail[] = []
+
+  send(mail: OutgoingMail): Promise<void> {
+    this.sent.push(mail)
+    return Promise.resolve()
+  }
+
+  reset(): void {
+    this.sent.length = 0
+  }
+}
+
+export class HttpMailDriver implements MailDriver {
+  constructor(private readonly config: HttpMailConfig) {}
+
+  async send(mail: OutgoingMail): Promise<void> {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 10_000)
+
+    try {
+      const response = await fetch(this.config.endpoint, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: `Bearer ${this.config.token}`,
+        },
+        body: JSON.stringify({
+          from: formatSender(this.config.from, mail.fromName),
+          to: mail.to,
+          subject: mail.subject,
+          text: mail.text,
+          ...(mail.html ? { html: mail.html } : {}),
+          ...(mail.replyTo ? { reply_to: mail.replyTo } : {}),
+        }),
+        signal: controller.signal,
+      })
+
+      if (!response.ok) {
+        const body = await response.text().catch(() => '')
+        const detail = `${response.status} ${body.slice(0, 200)}`
+
+        if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+          throw new ConfigurationError(`Mail provider rejected the message: ${detail}`)
+        }
+        throw new Error(`Mail provider error: ${detail}`)
+      }
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+}
+
+export function createMailDriver(config: MailConfig): MailDriver {
+  if (config.transport === 'log') return new LogMailDriver()
+
+  const problems = mailConfigProblems(config)
+  if (problems.length > 0) {
+    throw new ConfigurationError(`Mail is not fully configured: ${problems.join(' ')}`)
+  }
+
+  return config.transport === 'http' ? new HttpMailDriver(config) : new SmtpMailDriver(config)
+}
+
+export class ConfiguredMailDriver implements MailDriver {
+  private cached: { readonly fingerprint: string; readonly driver: MailDriver } | null = null
+
+  constructor(private readonly resolve: () => Promise<MailConfig>) {}
+
+  async send(mail: OutgoingMail): Promise<void> {
+    const config = await this.resolve()
+
+    if (!canSendMail(config)) {
+      logger({ driver: 'mail' }).warn(
+        { to: mail.to, subject: mail.subject, config: describeMailConfig(config) },
+        'mail not sent: this board has no working mail configuration',
+      )
+      return
+    }
+
+    const fingerprint = JSON.stringify(config)
+    if (this.cached === null || this.cached.fingerprint !== fingerprint) {
+      this.cached = { fingerprint, driver: createMailDriver(config) }
+    }
+
+    await this.cached.driver.send(mail)
+  }
+}

package/src/mail/sender.ts

@@ -0,0 +1,12 @@
+export function formatSender(address: string, name?: string): string {
+  const cleaned = stripControlCharacters(name ?? '').trim()
+  if (cleaned === '') return address
+
+  const escaped = cleaned.replace(/([\\"])/g, '\\$1')
+  return `"${escaped}" <${address}>`
+}
+
+function stripControlCharacters(value: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is this function's job
+  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, '')
+}

package/src/mail/smtp.ts

@@ -0,0 +1,77 @@
+import nodemailer, { type Transporter } from 'nodemailer'
+
+import { ConfigurationError, logger, type MailDriver, type OutgoingMail } from '@meith/core'
+import type { SmtpMailConfig } from '@meith/settings'
+
+import { formatSender } from './sender'
+
+const CONNECTION_TIMEOUT_MS = 10_000
+const GREETING_TIMEOUT_MS = 10_000
+const SOCKET_TIMEOUT_MS = 20_000
+
+function isPermanent(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false
+  const candidate = error as { responseCode?: unknown; code?: unknown }
+
+  if (typeof candidate.responseCode === 'number') {
+    return candidate.responseCode >= 500 && candidate.responseCode < 600
+  }
+
+  return candidate.code === 'EAUTH'
+}
+
+function describe(error: unknown): string {
+  if (typeof error !== 'object' || error === null) return String(error)
+  const candidate = error as { responseCode?: unknown; code?: unknown; message?: unknown }
+
+  const code =
+    typeof candidate.responseCode === 'number'
+      ? String(candidate.responseCode)
+      : typeof candidate.code === 'string'
+        ? candidate.code
+        : ''
+  const message = typeof candidate.message === 'string' ? candidate.message : String(error)
+
+  return (code === '' ? message : `${code} ${message}`).slice(0, 300)
+}
+
+export class SmtpMailDriver implements MailDriver {
+  private readonly transport: Transporter
+
+  constructor(private readonly config: SmtpMailConfig) {
+    this.transport = nodemailer.createTransport({
+      host: config.host,
+      port: config.port,
+      secure: config.security === 'tls',
+      requireTLS: config.security === 'starttls',
+      ...(config.username === '' ? {} : { auth: { user: config.username, pass: config.password } }),
+      connectionTimeout: CONNECTION_TIMEOUT_MS,
+      greetingTimeout: GREETING_TIMEOUT_MS,
+      socketTimeout: SOCKET_TIMEOUT_MS,
+    })
+  }
+
+  async send(mail: OutgoingMail): Promise<void> {
+    try {
+      await this.transport.sendMail({
+        from: formatSender(this.config.from, mail.fromName),
+        to: mail.to,
+        subject: mail.subject,
+        text: mail.text,
+        ...(mail.html === undefined ? {} : { html: mail.html }),
+        ...(mail.replyTo === undefined ? {} : { replyTo: mail.replyTo }),
+      })
+    } catch (error) {
+      const detail = describe(error)
+      logger({ driver: 'smtp', host: this.config.host }).warn(
+        { to: mail.to, err: detail },
+        'smtp send failed',
+      )
+
+      if (isPermanent(error)) {
+        throw new ConfigurationError(`The SMTP server rejected the message: ${detail}`)
+      }
+      throw new Error(`SMTP error: ${detail}`, { cause: error })
+    }
+  }
+}

package/src/queue/memory-queue.ts

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto'
+
+import type { EnqueueOptions, Job, QueueDriver } from '@meith/core'
+
+interface Row {
+  id: string
+  kind: string
+  payload: unknown
+  runAt: number
+  attempts: number
+  maxAttempts: number
+  status: 'pending' | 'running' | 'done' | 'dead'
+  dedupeKey?: string
+  lastError?: string
+}
+
+export class MemoryQueue implements QueueDriver {
+  private rows: Row[] = []
+
+  private backoffMs(attempt: number): number {
+    return Math.min(10 * attempt * attempt, 3600) * 1000
+  }
+
+  enqueue<TPayload>(
+    kind: string,
+    payload: TPayload,
+    options: EnqueueOptions = {},
+  ): Promise<{ id: string; deduplicated: boolean }> {
+    if (options.dedupeKey) {
+      const live = this.rows.find(
+        (r) => r.dedupeKey === options.dedupeKey && r.status === 'pending',
+      )
+      if (live) return Promise.resolve({ id: live.id, deduplicated: true })
+    }
+
+    const row: Row = {
+      id: randomUUID(),
+      kind,
+      payload,
+      runAt: options.runAt?.getTime() ?? Date.now(),
+      attempts: 0,
+      maxAttempts: options.maxAttempts ?? 5,
+      status: 'pending',
+    }
+    if (options.dedupeKey) row.dedupeKey = options.dedupeKey
+
+    this.rows.push(row)
+    return Promise.resolve({ id: row.id, deduplicated: false })
+  }
+
+  async drain(
+    limit: number,
+    handler: (job: Job) => Promise<void>,
+    options: { readonly signal?: AbortSignal } = {},
+  ): Promise<{ processed: number; failed: number }> {
+    const now = Date.now()
+
+    const claimed = this.rows
+      .filter((r) => r.status === 'pending' && r.runAt <= now && r.attempts < r.maxAttempts)
+      .slice(0, limit)
+
+    for (const row of claimed) {
+      row.status = 'running'
+      row.attempts += 1
+    }
+
+    let processed = 0
+    let failed = 0
+
+    for (const [index, row] of claimed.entries()) {
+      if (options.signal?.aborted === true) {
+        for (const unrun of claimed.slice(index)) {
+          unrun.status = 'pending'
+          unrun.attempts -= 1
+        }
+        break
+      }
+
+      try {
+        await handler({
+          id: row.id,
+          kind: row.kind,
+          payload: row.payload,
+          attempt: row.attempts,
+        })
+        row.status = 'done'
+        processed += 1
+      } catch (error) {
+        failed += 1
+        row.lastError = error instanceof Error ? error.message : String(error)
+        row.status = row.attempts >= row.maxAttempts ? 'dead' : 'pending'
+        row.runAt = Date.now() + this.backoffMs(row.attempts)
+      }
+    }
+
+    return { processed, failed }
+  }
+
+  deadLettered(limit: number): Promise<readonly Job[]> {
+    return Promise.resolve(
+      this.rows
+        .filter((r) => r.status === 'dead')
+        .slice(0, limit)
+        .map((r) => ({
+          id: r.id,
+          kind: r.kind,
+          payload: r.payload,
+          attempt: r.attempts,
+        })),
+    )
+  }
+
+  retry(jobId: string): Promise<boolean> {
+    const row = this.rows.find((r) => r.id === jobId && r.status === 'dead')
+    if (!row) return Promise.resolve(false)
+
+    row.status = 'pending'
+    row.attempts = 0
+    row.runAt = Date.now()
+    delete row.lastError
+    return Promise.resolve(true)
+  }
+
+  size(): number {
+    return this.rows.length
+  }
+
+  pending(): readonly Job[] {
+    return this.rows
+      .filter((r) => r.status === 'pending')
+      .map((r) => ({ id: r.id, kind: r.kind, payload: r.payload, attempt: r.attempts }))
+  }
+
+  reset(): void {
+    this.rows = []
+  }
+}