@meith/subscriptions 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,25 @@
+{
+  "name": "@meith/subscriptions",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/subscriptions"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/core": "0.16.0",
+    "@meith/i18n": "0.16.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export {
+  CADENCE_INTERVAL_MS,
+  DIGEST_CADENCES,
+  type DigestCadence,
+  isDigestCadence,
+  MODE_LABELS,
+  parseSubscriptionMode,
+  parseSubscriptionTarget,
+  SUBSCRIPTION_MODES,
+  type SubscriptionMode,
+  type SubscriptionTarget,
+} from './modes'
+export {
+  type DigestThread,
+  groupByThread,
+  MAX_POSTS_PER_USER,
+  MAX_THREADS_IN_DIGEST,
+  MAX_USERS_PER_RUN,
+  type RunOutcome,
+  SubscriptionNotifier,
+} from './notifier'
+export {
+  SUBSCRIPTIONS_PAGE_SIZE,
+  SubscriptionService,
+} from './service'
+export {
+  mintUnsubscribeToken,
+  readUnsubscribeToken,
+  type UnsubscribeClaim,
+} from './tokens'
+export type {
+  PendingForUser,
+  PendingPost,
+  SubscriptionNotifierPort,
+  SubscriptionRepository,
+  SubscriptionRow,
+  VisibleForumSource,
+} from './types'

package/src/modes.ts

@@ -0,0 +1,33 @@
+export const SUBSCRIPTION_MODES = ['instant', 'daily', 'weekly', 'none'] as const
+
+export type SubscriptionMode = (typeof SUBSCRIPTION_MODES)[number]
+
+export const DIGEST_CADENCES = ['daily', 'weekly'] as const
+
+export type DigestCadence = (typeof DIGEST_CADENCES)[number]
+
+export const CADENCE_INTERVAL_MS: Readonly<Record<DigestCadence, number>> = {
+  daily: 24 * 60 * 60 * 1000,
+  weekly: 7 * 24 * 60 * 60 * 1000,
+}
+
+export const MODE_LABELS: Readonly<Record<SubscriptionMode, string>> = {
+  instant: 'As it happens',
+  daily: 'Daily digest',
+  weekly: 'Weekly digest',
+  none: 'Do not notify me',
+}
+
+export function parseSubscriptionMode(value: string): SubscriptionMode | null {
+  return SUBSCRIPTION_MODES.includes(value as SubscriptionMode) ? (value as SubscriptionMode) : null
+}
+
+export function isDigestCadence(value: string): value is DigestCadence {
+  return DIGEST_CADENCES.includes(value as DigestCadence)
+}
+
+export type SubscriptionTarget = 'thread' | 'forum'
+
+export function parseSubscriptionTarget(value: string): SubscriptionTarget | null {
+  return value === 'thread' || value === 'forum' ? value : null
+}

package/src/notifier.ts

@@ -0,0 +1,184 @@
+import { CADENCE_INTERVAL_MS, type DigestCadence, type SubscriptionMode } from './modes'
+import { mintUnsubscribeToken } from './tokens'
+import type {
+  PendingPost,
+  SubscriptionNotifierPort,
+  SubscriptionRepository,
+  VisibleForumSource,
+} from './types'
+
+export const MAX_USERS_PER_RUN = 50
+
+export const MAX_POSTS_PER_USER = 200
+
+export const MAX_THREADS_IN_DIGEST = 10
+
+export interface DigestThread {
+  readonly threadId: number
+  readonly title: string
+  readonly href: string
+  readonly posts: number
+  readonly lastAuthor: string | null
+}
+
+export function groupByThread(posts: readonly PendingPost[]): readonly DigestThread[] {
+  const byThread = new Map<number, { thread: PendingPost; count: number; last: PendingPost }>()
+
+  for (const post of posts) {
+    const entry = byThread.get(post.threadId)
+    if (entry === undefined) {
+      byThread.set(post.threadId, { thread: post, count: 1, last: post })
+      continue
+    }
+    entry.count += 1
+    if (post.postId > entry.last.postId) entry.last = post
+  }
+
+  return [...byThread.values()]
+    .sort((a, b) => b.count - a.count || a.thread.threadId - b.thread.threadId)
+    .map(({ thread, count, last }) => ({
+      threadId: thread.threadId,
+      title: thread.threadTitle,
+      href: `/thread/${thread.threadId}-${thread.threadSlug}?after=${thread.postId - 1}`,
+      posts: count,
+      lastAuthor: last.authorUsername,
+    }))
+}
+
+export interface RunOutcome {
+  readonly notified: number
+  readonly considered: number
+}
+
+export class SubscriptionNotifier {
+  private readonly subscriptions: SubscriptionRepository
+  private readonly notifications: SubscriptionNotifierPort
+  private readonly forums: VisibleForumSource
+  private readonly now: () => Date
+
+  private readonly secret: string | null
+
+  constructor(deps: {
+    subscriptions: SubscriptionRepository
+    notifications: SubscriptionNotifierPort
+    forums: VisibleForumSource
+    unsubscribeSecret?: string | null
+    now?: () => Date
+  }) {
+    this.subscriptions = deps.subscriptions
+    this.notifications = deps.notifications
+    this.forums = deps.forums
+    this.secret = deps.unsubscribeSecret ?? null
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  private token(
+    userId: number,
+    scope: 'thread' | 'forum' | 'email',
+    targetId: number,
+  ): string | null {
+    return this.secret === null
+      ? null
+      : mintUnsubscribeToken({ userId, scope, targetId }, this.secret)
+  }
+
+  async runInstant(limit = MAX_USERS_PER_RUN, signal?: AbortSignal): Promise<RunOutcome> {
+    return this.run('instant', null, limit, signal, (userId, threads) =>
+      Promise.all(
+        threads.map((thread) =>
+          this.notifications.raise({
+            userId,
+            kind: 'subscription.reply',
+            data: {
+              threadTitle: thread.title,
+              posts: thread.posts,
+              lastAuthor: thread.lastAuthor,
+              unsubscribe: this.token(userId, 'thread', thread.threadId),
+            },
+            href: thread.href,
+            dedupeKey: `subscription.reply:${thread.threadId}`,
+          }),
+        ),
+      ).then(() => undefined),
+    )
+  }
+
+  async runDigest(
+    cadence: DigestCadence,
+    limit = MAX_USERS_PER_RUN,
+    signal?: AbortSignal,
+  ): Promise<RunOutcome> {
+    const at = this.now()
+    const dueBefore = new Date(at.getTime() - CADENCE_INTERVAL_MS[cadence])
+
+    return this.run(cadence, dueBefore, limit, signal, async (userId, threads) => {
+      const totalPosts = threads.reduce((sum, thread) => sum + thread.posts, 0)
+
+      await this.notifications.raise({
+        userId,
+        kind: 'subscription.digest',
+        data: {
+          cadence,
+          threadCount: threads.length,
+          postCount: totalPosts,
+          threads: threads.slice(0, MAX_THREADS_IN_DIGEST).map((thread) => ({
+            title: thread.title,
+            href: thread.href,
+            posts: thread.posts,
+            lastAuthor: thread.lastAuthor,
+          })),
+          more: Math.max(0, threads.length - MAX_THREADS_IN_DIGEST),
+          unsubscribe: this.token(userId, 'email', 0),
+        },
+        href: '/subscriptions',
+        dedupeKey: null,
+      })
+
+      await this.subscriptions.recordDigestRun({ userId, cadence, at })
+    })
+  }
+
+  private async run(
+    mode: SubscriptionMode,
+    dueBefore: Date | null,
+    limit: number,
+    signal: AbortSignal | undefined,
+    tell: (userId: number, threads: readonly DigestThread[]) => Promise<void>,
+  ): Promise<RunOutcome> {
+    const users = await this.subscriptions.usersWithPending({ mode, dueBefore, limit })
+
+    let notified = 0
+    let considered = 0
+    for (const userId of users) {
+      if (signal?.aborted === true) break
+      considered += 1
+
+      try {
+        const visibleForumIds = await this.forums.visibleForumIdsFor(userId)
+        const pending = await this.subscriptions.pendingFor({
+          userId,
+          mode,
+          visibleForumIds,
+          limit: MAX_POSTS_PER_USER,
+        })
+
+        const threads = groupByThread(pending.posts)
+        if (threads.length > 0) {
+          await tell(userId, threads)
+          notified += 1
+        }
+
+        if (pending.watermarks.length > 0) {
+          await this.subscriptions.advanceWatermarks({
+            userId,
+            watermarks: pending.watermarks,
+          })
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+
+    return { notified, considered }
+  }
+}

package/src/service.ts

@@ -0,0 +1,67 @@
+import { ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import { parseSubscriptionMode, type SubscriptionMode, type SubscriptionTarget } from './modes'
+import type { SubscriptionRepository, SubscriptionRow } from './types'
+
+export const SUBSCRIPTIONS_PAGE_SIZE = 200
+
+export class SubscriptionService {
+  private readonly repository: SubscriptionRepository
+  private readonly now: () => Date
+
+  constructor(deps: { subscriptions: SubscriptionRepository; now?: () => Date }) {
+    this.repository = deps.subscriptions
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async subscribe(input: {
+    readonly userId: number
+    readonly target: SubscriptionTarget
+    readonly targetId: number
+    readonly mode: string
+    readonly mayView: boolean
+  }): Promise<SubscriptionMode> {
+    if (!input.mayView) throw new ValidationError(msg('error.subscriptions.exist'))
+
+    const mode = parseSubscriptionMode(input.mode)
+    if (mode === null) throw new ValidationError(msg('error.subscriptions.notification-setting'))
+
+    const written = await this.repository.subscribe({
+      userId: input.userId,
+      target: input.target,
+      targetId: input.targetId,
+      mode,
+      at: this.now(),
+    })
+    if (!written) throw new ValidationError(msg('error.subscriptions.exist'))
+
+    return mode
+  }
+
+  async unsubscribe(input: {
+    readonly userId: number
+    readonly target: SubscriptionTarget
+    readonly targetId: number
+  }): Promise<boolean> {
+    return this.repository.unsubscribe(input)
+  }
+
+  async modeFor(
+    userId: number,
+    target: SubscriptionTarget,
+    targetId: number,
+  ): Promise<SubscriptionMode | null> {
+    return this.repository.modeFor(userId, target, targetId)
+  }
+
+  async list(
+    userId: number,
+    visibleForumIds: readonly number[],
+  ): Promise<readonly SubscriptionRow[]> {
+    return this.repository.listFor(userId, {
+      visibleForumIds,
+      limit: SUBSCRIPTIONS_PAGE_SIZE,
+    })
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,61 @@
+import { createHmac } from 'node:crypto'
+
+import { timingSafeEqualString } from '@meith/core'
+
+import type { SubscriptionTarget } from './modes'
+
+export type UnsubscribeScope = SubscriptionTarget | 'email'
+
+export function parseUnsubscribeScope(value: string): UnsubscribeScope | null {
+  return value === 'thread' || value === 'forum' || value === 'email' ? value : null
+}
+
+export interface UnsubscribeClaim {
+  readonly userId: number
+  readonly scope: UnsubscribeScope
+  readonly targetId: number
+}
+
+const VERSION = 'v1'
+
+const DIGEST_LENGTH = 32
+
+function digest(payload: string, secret: string): string {
+  return createHmac('sha256', secret).update(payload).digest('base64url').slice(0, DIGEST_LENGTH)
+}
+
+function payloadOf(claim: UnsubscribeClaim): string {
+  return `${VERSION}.${claim.userId}.${claim.scope}.${claim.targetId}`
+}
+
+export function mintUnsubscribeToken(claim: UnsubscribeClaim, secret: string): string {
+  return `${payloadOf(claim)}.${digest(payloadOf(claim), secret)}`
+}
+
+export function readUnsubscribeToken(token: string, secret: string): UnsubscribeClaim | null {
+  const parts = token.split('.')
+  if (parts.length !== 5) return null
+
+  const [version, rawUserId, rawScope, rawTargetId, signature] = parts as [
+    string,
+    string,
+    string,
+    string,
+    string,
+  ]
+  if (version !== VERSION) return null
+
+  const scope = parseUnsubscribeScope(rawScope)
+  if (scope === null) return null
+
+  const targetPattern = scope === 'email' ? /^0$/ : /^[1-9]\d*$/
+  if (!/^[1-9]\d*$/.test(rawUserId) || !targetPattern.test(rawTargetId)) return null
+  const userId = Number(rawUserId)
+  const targetId = Number(rawTargetId)
+  if (!Number.isSafeInteger(userId) || !Number.isSafeInteger(targetId)) return null
+
+  const claim: UnsubscribeClaim = { userId, scope, targetId }
+  if (!timingSafeEqualString(signature, digest(payloadOf(claim), secret))) return null
+
+  return claim
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+import type { DigestCadence, SubscriptionMode, SubscriptionTarget } from './modes'
+
+export interface SubscriptionRow {
+  readonly target: SubscriptionTarget
+  readonly targetId: number
+  readonly title: string
+  readonly href: string
+  readonly mode: SubscriptionMode
+  readonly createdAt: Date
+  readonly pending: number
+}
+
+export interface PendingPost {
+  readonly postId: number
+  readonly threadId: number
+  readonly threadTitle: string
+  readonly threadSlug: string
+  readonly forumId: number
+  readonly authorUsername: string | null
+  readonly createdAt: Date
+}
+
+export interface PendingForUser {
+  readonly userId: number
+  readonly posts: readonly PendingPost[]
+  readonly watermarks: readonly {
+    readonly target: SubscriptionTarget
+    readonly targetId: number
+    readonly lastPostId: number
+  }[]
+}
+
+export interface SubscriptionRepository {
+  subscribe(input: {
+    readonly userId: number
+    readonly target: SubscriptionTarget
+    readonly targetId: number
+    readonly mode: SubscriptionMode
+    readonly at: Date
+  }): Promise<boolean>
+
+  unsubscribe(input: {
+    readonly userId: number
+    readonly target: SubscriptionTarget
+    readonly targetId: number
+  }): Promise<boolean>
+
+  modeFor(
+    userId: number,
+    target: SubscriptionTarget,
+    targetId: number,
+  ): Promise<SubscriptionMode | null>
+
+  listFor(
+    userId: number,
+    options: { readonly visibleForumIds: readonly number[]; readonly limit: number },
+  ): Promise<readonly SubscriptionRow[]>
+
+  usersWithPending(input: {
+    readonly mode: SubscriptionMode
+    readonly dueBefore: Date | null
+    readonly limit: number
+  }): Promise<readonly number[]>
+
+  pendingFor(input: {
+    readonly userId: number
+    readonly mode: SubscriptionMode
+    readonly visibleForumIds: readonly number[]
+    readonly limit: number
+  }): Promise<PendingForUser>
+
+  advanceWatermarks(input: {
+    readonly userId: number
+    readonly watermarks: PendingForUser['watermarks']
+  }): Promise<void>
+
+  recordDigestRun(input: {
+    readonly userId: number
+    readonly cadence: DigestCadence
+    readonly at: Date
+  }): Promise<void>
+}
+
+export interface SubscriptionNotifierPort {
+  raise(input: {
+    readonly userId: number
+    readonly kind: 'subscription.reply' | 'subscription.digest'
+    readonly data: Record<string, unknown>
+    readonly href: string | null
+    readonly dedupeKey: string | null
+  }): Promise<void>
+}
+
+export interface VisibleForumSource {
+  visibleForumIdsFor(userId: number): Promise<readonly number[]>
+}