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

package/src/compose.ts

@@ -0,0 +1,220 @@
+import { RateLimitedError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+import { type NewPoll, type ValidatedPoll, validatePoll } from '@meith/polls'
+
+export interface ForumPostingRules {
+  readonly id: number
+  readonly type: 'category' | 'forum' | 'link'
+  readonly isOpen: boolean
+  readonly allowThreads: boolean
+  readonly allowReplies: boolean
+  readonly allowPolls: boolean
+  readonly allowAttachments: boolean
+  readonly requiresPrefix: boolean
+  readonly moderateNewThreads: boolean
+  readonly moderateNewPosts: boolean
+}
+
+export interface ThreadAuthor {
+  readonly userId: number
+  readonly username: string
+}
+
+export interface AuthorRestriction {
+  readonly suspended: boolean
+  readonly moderated: boolean
+}
+
+export const UNRESTRICTED: AuthorRestriction = {
+  suspended: false,
+  moderated: false,
+}
+
+export interface ComposeThreadInput {
+  readonly title: string
+  readonly message: string
+  readonly prefixId: number | null
+  readonly subscribe: boolean
+  readonly poll?: NewPoll | undefined
+  readonly mayPostPoll?: boolean | undefined
+  readonly bypassesModeration: boolean
+  readonly heldAsNewMember: boolean
+  readonly requiresApproval: boolean
+  readonly bypassesFlood: boolean
+  readonly restriction?: AuthorRestriction | undefined
+}
+
+export interface NewThreadRecord {
+  readonly forumId: number
+  readonly title: string
+  readonly slug: string
+  readonly message: string
+  readonly prefixId: number | null
+  readonly authorUserId: number
+  readonly authorUsername: string
+  readonly visibility: 'visible' | 'unapproved'
+  readonly subscribe: boolean
+  readonly poll?: ValidatedPoll | undefined
+  readonly createdAt: Date
+}
+
+export interface CreatedThread {
+  readonly threadId: number
+  readonly postId: number
+  readonly slug: string
+  readonly visibility: 'visible' | 'unapproved'
+}
+
+export interface PrefixOption {
+  readonly id: number
+  readonly label: string
+  readonly token: string | null
+}
+
+export type ForumPostingTarget = ForumPostingRules & { readonly slug: string }
+
+export interface ThreadWriteRepository {
+  postingRules(forumId: number): Promise<ForumPostingTarget | null>
+  create(record: NewThreadRecord): Promise<CreatedThread>
+
+  lastPostAt(userId: number): Promise<Date | null>
+
+  allowedPrefixIds(forumId: number): Promise<readonly number[]>
+
+  listPrefixes(forumId: number): Promise<readonly PrefixOption[]>
+}
+
+export interface ThreadComposerConfig {
+  readonly floodSeconds: number
+  readonly maxLength: number
+}
+
+export const TITLE_MIN = 3
+export const TITLE_MAX = 120
+export const MESSAGE_MIN = 2
+
+export function threadSlug(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60)
+    .replace(/-+$/g, '')
+
+  return slug.length > 0 ? slug : 'thread'
+}
+
+export class ThreadComposer {
+  private readonly threads: ThreadWriteRepository
+  private readonly config: ThreadComposerConfig
+  private readonly now: () => Date
+
+  constructor(deps: {
+    threads: ThreadWriteRepository
+    config: ThreadComposerConfig
+    now?: () => Date
+  }) {
+    this.threads = deps.threads
+    this.config = deps.config
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async create(
+    input: ComposeThreadInput,
+    author: ThreadAuthor,
+    forum: ForumPostingRules,
+  ): Promise<CreatedThread> {
+    const title = input.title.trim()
+    const message = input.message.trim()
+
+    if (forum.type === 'link') {
+      throw new ValidationError(msg('error.threads.threads-posted-here'))
+    }
+    if (!forum.isOpen || !forum.allowThreads) {
+      throw new ValidationError(msg('error.threads.forum-closed-new-threads'))
+    }
+
+    const restriction = input.restriction ?? UNRESTRICTED
+    if (restriction.suspended) {
+      throw new ValidationError(msg('error.threads.posting-privileges-currently-suspended'))
+    }
+
+    if (title.length < TITLE_MIN) {
+      throw new ValidationError(msg('error.threads.title-min', { min: TITLE_MIN }))
+    }
+    if (title.length > TITLE_MAX) {
+      throw new ValidationError(msg('error.threads.title-max', { max: TITLE_MAX }))
+    }
+    if (message.length < MESSAGE_MIN) {
+      throw new ValidationError(msg('error.threads.post-needs-message'))
+    }
+    if (message.length > this.config.maxLength) {
+      throw new ValidationError(msg('error.posts.post-length', { max: this.config.maxLength }))
+    }
+
+    const prefixId = await this.resolvePrefix(input.prefixId, forum)
+    const poll = input.poll === undefined ? undefined : validatePoll(input.poll, this.now())
+    if (poll !== undefined && (input.mayPostPoll !== true || !forum.allowPolls)) {
+      throw new ValidationError(msg('error.threads.attach-poll-forum'))
+    }
+
+    await this.enforceFlood(input, author)
+
+    const visibility =
+      ((forum.moderateNewThreads || input.requiresApproval) && !input.bypassesModeration) ||
+      input.heldAsNewMember ||
+      restriction.moderated
+        ? 'unapproved'
+        : 'visible'
+
+    return this.threads.create({
+      forumId: forum.id,
+      title,
+      slug: threadSlug(title),
+      message,
+      prefixId,
+      authorUserId: author.userId,
+      authorUsername: author.username,
+      visibility,
+      subscribe: input.subscribe,
+      poll,
+      createdAt: this.now(),
+    })
+  }
+
+  private async resolvePrefix(
+    prefixId: number | null,
+    forum: ForumPostingRules,
+  ): Promise<number | null> {
+    if (prefixId === null) {
+      if (forum.requiresPrefix) {
+        throw new ValidationError(msg('error.threads.forum-requires-prefix'))
+      }
+      return null
+    }
+
+    const allowed = await this.threads.allowedPrefixIds(forum.id)
+    if (!allowed.includes(prefixId)) {
+      throw new ValidationError(msg('error.threads.prefix-used-forum'))
+    }
+    return prefixId
+  }
+
+  private async enforceFlood(input: ComposeThreadInput, author: ThreadAuthor): Promise<void> {
+    if (this.config.floodSeconds <= 0 || input.bypassesFlood) return
+
+    const last = await this.threads.lastPostAt(author.userId)
+    if (last === null) return
+
+    const elapsed = (this.now().getTime() - last.getTime()) / 1000
+    if (elapsed >= this.config.floodSeconds) return
+
+    const wait = Math.max(1, Math.ceil(this.config.floodSeconds - elapsed))
+    throw new RateLimitedError(
+      wait,
+      `Please wait ${wait} more second${wait === 1 ? '' : 's'} before posting again.`,
+    )
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+export {
+  type AuthorRestriction,
+  type ComposeThreadInput,
+  type CreatedThread,
+  type ForumPostingRules,
+  type ForumPostingTarget,
+  MESSAGE_MIN,
+  type NewThreadRecord,
+  type PrefixOption,
+  type ThreadAuthor,
+  ThreadComposer,
+  type ThreadComposerConfig,
+  type ThreadWriteRepository,
+  TITLE_MAX,
+  TITLE_MIN,
+  threadSlug,
+  UNRESTRICTED,
+} from './compose'
+export type { ThreadLocation, ThreadRepository } from './ports'
+export type { ReadState, ReadStateRepository } from './read-state'
+export {
+  type ComposeReplyInput,
+  type CreatedReply,
+  type NewReplyRecord,
+  quotePrefill,
+  ReplyComposer,
+  type ReplyComposerConfig,
+  type ReplyTarget,
+  type ReplyWriteRepository,
+} from './reply'
+export type {
+  ThreadCursor,
+  ThreadLastPost,
+  ThreadListingRow,
+  ThreadPage,
+  ThreadSort,
+} from './types'

package/src/ports.ts

@@ -0,0 +1,30 @@
+import type { ContentScope, ThreadAuthorFilter } from '@meith/core'
+
+import type { ThreadCursor, ThreadListingRow, ThreadPage, ThreadSort } from './types'
+
+export interface ThreadLocation {
+  readonly forumId: number
+  readonly authorUserId: number | null
+}
+
+export interface ThreadRepository {
+  findById(
+    id: number,
+    scope: ContentScope,
+    authors: ThreadAuthorFilter,
+  ): Promise<ThreadListingRow | null>
+
+  locate(threadId: number): Promise<ThreadLocation | null>
+
+  listForum(
+    forumId: number,
+    options: {
+      readonly after?: ThreadCursor
+      readonly offset?: number
+      readonly limit: number
+      readonly scope: ContentScope
+      readonly authors: ThreadAuthorFilter
+      readonly sort?: ThreadSort
+    },
+  ): Promise<ThreadPage>
+}

package/src/read-state.ts

@@ -0,0 +1,11 @@
+export interface ReadState {
+  readonly forumReadAt: ReadonlyMap<number, Date>
+  readonly threadLastPostId: ReadonlyMap<number, number>
+  readonly unreadForumIds: ReadonlySet<number>
+}
+
+export interface ReadStateRepository {
+  forUser(userId: number): Promise<ReadState>
+  markForumsRead(userId: number, forumIds: readonly number[], at: Date): Promise<void>
+  markThreadRead(userId: number, threadId: number, postId: number, at: Date): Promise<void>
+}

package/src/reply.ts

@@ -0,0 +1,180 @@
+import { RateLimitedError, ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+import { quoteBlock } from '@meith/markdown'
+
+import {
+  type AuthorRestriction,
+  type ForumPostingTarget,
+  MESSAGE_MIN,
+  type ThreadAuthor,
+  UNRESTRICTED,
+} from './compose'
+
+export interface ReplyTarget {
+  readonly threadId: number
+  readonly slug: string
+  readonly title: string
+  readonly authorUserId: number | null
+  readonly isLocked: boolean
+  readonly visibility: 'visible' | 'unapproved' | 'deleted'
+  readonly lastPostId: number | null
+  readonly replyCount: number
+  readonly forum: ForumPostingTarget
+}
+
+export interface ComposeReplyInput {
+  readonly message: string
+  readonly subscribe: boolean
+  readonly seenLastPostId: number | null
+  readonly bypassesModeration: boolean
+  readonly heldAsNewMember: boolean
+  readonly requiresApproval: boolean
+  readonly bypassesFlood: boolean
+  readonly bypassesLock: boolean
+  readonly restriction?: AuthorRestriction | undefined
+}
+
+export interface NewReplyRecord {
+  readonly threadId: number
+  readonly forumId: number
+  readonly threadTitle: string
+  readonly message: string
+  readonly authorUserId: number
+  readonly authorUsername: string
+  readonly visibility: 'visible' | 'unapproved'
+  readonly subscribe: boolean
+  readonly createdAt: Date
+}
+
+export interface CreatedReply {
+  readonly postId: number
+  readonly threadId: number
+  readonly slug: string
+  readonly visibility: 'visible' | 'unapproved'
+  readonly raced: boolean
+  readonly repliesBefore: number
+}
+
+export interface ReplyWriteRepository {
+  replyTarget(threadId: number): Promise<ReplyTarget | null>
+
+  createReply(record: NewReplyRecord): Promise<{ postId: number }>
+
+  lastPostAt(userId: number): Promise<Date | null>
+}
+
+export interface ReplyComposerConfig {
+  readonly floodSeconds: number
+  readonly maxLength: number
+}
+
+export class ReplyComposer {
+  private readonly posts: ReplyWriteRepository
+  private readonly config: ReplyComposerConfig
+  private readonly now: () => Date
+
+  constructor(deps: {
+    posts: ReplyWriteRepository
+    config: ReplyComposerConfig
+    now?: () => Date
+  }) {
+    this.posts = deps.posts
+    this.config = deps.config
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async create(
+    input: ComposeReplyInput,
+    author: ThreadAuthor,
+    target: ReplyTarget,
+  ): Promise<CreatedReply> {
+    const message = input.message.trim()
+
+    if (target.visibility !== 'visible') {
+      throw new ValidationError(msg('error.threads.thread-available'))
+    }
+    if (target.forum.type === 'link' || !target.forum.isOpen || !target.forum.allowReplies) {
+      throw new ValidationError(msg('error.threads.forum-closed-replies'))
+    }
+    if (target.isLocked && !input.bypassesLock) {
+      throw new ValidationError(msg('error.threads.thread-locked'))
+    }
+
+    const restriction = input.restriction ?? UNRESTRICTED
+    if (restriction.suspended) {
+      throw new ValidationError(msg('error.threads.posting-privileges-currently-suspended'))
+    }
+
+    if (message.length < MESSAGE_MIN) {
+      throw new ValidationError(msg('error.threads.post-needs-message'))
+    }
+    if (message.length > this.config.maxLength) {
+      throw new ValidationError(`A post may be at most ${this.config.maxLength} characters.`)
+    }
+
+    await this.enforceFlood(input, author)
+
+    const visibility =
+      ((target.forum.moderateNewPosts || input.requiresApproval) && !input.bypassesModeration) ||
+      input.heldAsNewMember ||
+      restriction.moderated
+        ? 'unapproved'
+        : 'visible'
+
+    const { postId } = await this.posts.createReply({
+      threadId: target.threadId,
+      forumId: target.forum.id,
+      threadTitle: target.title,
+      message,
+      authorUserId: author.userId,
+      authorUsername: author.username,
+      visibility,
+      subscribe: input.subscribe,
+      createdAt: this.now(),
+    })
+
+    const raced =
+      input.seenLastPostId !== null &&
+      target.lastPostId !== null &&
+      target.lastPostId !== input.seenLastPostId
+
+    return {
+      postId,
+      threadId: target.threadId,
+      slug: target.slug,
+      visibility,
+      raced,
+      repliesBefore: target.replyCount,
+    }
+  }
+
+  private async enforceFlood(input: ComposeReplyInput, author: ThreadAuthor): Promise<void> {
+    if (this.config.floodSeconds <= 0 || input.bypassesFlood) return
+
+    const last = await this.posts.lastPostAt(author.userId)
+    if (last === null) return
+
+    const elapsed = (this.now().getTime() - last.getTime()) / 1000
+    if (elapsed >= this.config.floodSeconds) return
+
+    const wait = Math.max(1, Math.ceil(this.config.floodSeconds - elapsed))
+    throw new RateLimitedError(
+      wait,
+      `Please wait ${wait} more second${wait === 1 ? '' : 's'} before posting again.`,
+    )
+  }
+}
+
+export function quotePrefill(quoted: {
+  readonly authorUsername: string
+  readonly message: string
+  readonly sourceHref?: string | null
+  readonly sourceLabel?: string
+}): string {
+  return `${quoteBlock({
+    author: quoted.authorUsername,
+    markdown: quoted.message,
+    sourceHref: quoted.sourceHref ?? null,
+    ...(quoted.sourceLabel === undefined ? {} : { sourceLabel: quoted.sourceLabel }),
+  })}\n\n`
+}

package/src/types.ts

@@ -0,0 +1,45 @@
+export type ThreadSort = 'activity' | 'rating'
+
+export interface ThreadLastPost {
+  readonly postId: number
+  readonly userId: number | null
+  readonly username: string
+  readonly at: Date
+}
+
+export interface ThreadListingRow {
+  readonly id: number
+  readonly forumId: number
+  readonly title: string
+  readonly slug: string
+  readonly prefix: {
+    readonly label: string
+    readonly token: string | null
+  } | null
+  readonly authorUserId: number | null
+  readonly authorUsername: string
+  readonly replyCount: number
+  readonly viewCount: number
+  readonly ratingTotal: number
+  readonly ratingCount: number
+  readonly visibility: 'visible' | 'unapproved' | 'deleted'
+  readonly isSticky: boolean
+  readonly isLocked: boolean
+  readonly isMoved: boolean
+  readonly lastPost: ThreadLastPost | null
+  readonly lastPostAt: Date
+}
+
+export interface ThreadCursor {
+  readonly sort: ThreadSort
+  readonly isSticky: boolean
+  readonly lastPostAt: Date
+  readonly ratingTotal: number
+  readonly ratingCount: number
+  readonly id: number
+}
+
+export interface ThreadPage {
+  readonly rows: readonly ThreadListingRow[]
+  readonly nextCursor: ThreadCursor | null
+}