@lincyaw/classroom-server 0.0.0-stage → 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @lincyaw/classroom-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Presmium's classroom sync server: the y-websocket rooms classroom sessions sync through.
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which turns lectures written in MyST Markdown into web pages, slides, Jupyter notebooks and narrated lectures.
+
+## Usage
+
+```sh
+pnpm exec presmium-classroom-server --port 1234
+```
+
+Documents point to it in their headmatter: `presmium: { presmium.session: { server: ws://<host>:1234 } }`. `presmium dev` and `presmium serve` also run one on their own port. Options: `--port`, `--host`, `--deck` (where archived classrooms are written). Run it on the classroom's own network: anyone with a join link can join.
+
+## Documentation
+
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/lecture.en.md)
+
+## License
+
+Apache-2.0

package/bin/server.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { createJiti } from 'jiti'
+
+const jiti = createJiti(import.meta.url)
+const { main } = await jiti.import('../src/cli.ts')
+const code = await main(process.argv.slice(2))
+if (code !== undefined) process.exitCode = code

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@lincyaw/classroom-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.0",
+  "description": "Presmium's classroom sync server: y-websocket rooms",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/classroom-server"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/classroom-server#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium",
+    "yjs",
+    "classroom"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "presmium-classroom-server": "./bin/server.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "lib0": "^0.2.119",
+    "ws": "^8.22.0",
+    "y-protocols": "^1.0.7",
+    "yjs": "^13.6.33",
+    "@lincyaw/kernel": "1.0.0-rc.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.2",
+    "y-websocket": "^3.1.0"
+  },
+  "scripts": {
+    "start": "node bin/server.mjs"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,56 @@
+import { networkInterfaces } from 'node:os'
+import { parseArgs } from 'node:util'
+import { errorMessage } from '@lincyaw/kernel'
+import { startClassroomServer } from './index.ts'
+
+const USAGE = `Usage: presmium-classroom-server [--port <n>] [--host <address>] [--deck <dir>]
+
+Starts the room server that classroom sessions sync through. Decks point to it
+in their frontmatter: presmium: { presmium.session: { server: ws://<host>:<port> } }
+Listening on every interface, it also prints its addresses on the local network:
+learners' devices reach it there, not at localhost.
+
+  --port <n>          port to listen on; 0 picks a free one (default: 1234)
+  --host <address>    address to listen on (default: every interface)
+  --deck <dir>        deck directory: archived classrooms are written to
+                      <dir>/.presmium/classroom/<room>.json (default: the working directory)
+  -h, --help          show this help
+
+Run it on the classroom's own network: anyone with a join link can join. Only
+the window that created a classroom can end or archive it, open and close its
+quizzes or move its learners; the others write only their own answers,
+questions, votes and submissions.`
+
+export async function main(argv: string[]): Promise<number | undefined> {
+  let port: number
+  let host: string | undefined
+  let deck: string | undefined
+  try {
+    const { values } = parseArgs({
+      args: argv,
+      options: { port: { type: 'string' }, host: { type: 'string' }, deck: { type: 'string' }, help: { type: 'boolean', short: 'h' } },
+    })
+    if (values.help) {
+      process.stdout.write(`${USAGE}\n`)
+      return 0
+    }
+    port = Number(values.port ?? 1234)
+    if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`invalid port "${values.port}"`)
+    host = values.host
+    deck = values.deck
+  } catch (error) {
+    process.stderr.write(`presmium-classroom-server: ${errorMessage(error)}\n\n${USAGE}\n`)
+    return 2
+  }
+  const server = await startClassroomServer({ port, host, deck })
+  const network = !host || host === '0.0.0.0' || host === '::' ? lanAddresses().map(address => `network           ws://${address}:${server.port}\n`) : []
+  process.stdout.write(`classroom server  ${server.url}\n${network.join('')}archives          ${server.archiveDir}\n`)
+  const stop = () => void server.close().then(() => process.exit(0))
+  process.once('SIGINT', stop)
+  process.once('SIGTERM', stop)
+  return undefined
+}
+
+function lanAddresses(): string[] {
+  return Object.values(networkInterfaces()).flatMap(entries => entries ?? []).filter(entry => entry.family === 'IPv4' && !entry.internal).map(entry => entry.address)
+}

package/src/index.ts

@@ -0,0 +1,447 @@
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { createServer } from 'node:http'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { join, resolve } from 'node:path'
+import { errorMessage } from '@lincyaw/kernel'
+import * as decoding from 'lib0/decoding'
+import * as encoding from 'lib0/encoding'
+import { WebSocket, WebSocketServer } from 'ws'
+import * as awarenessProtocol from 'y-protocols/awareness'
+import * as syncProtocol from 'y-protocols/sync'
+import * as Y from 'yjs'
+
+const MESSAGE_SYNC = 0
+const MESSAGE_AWARENESS = 1
+const PING_INTERVAL = 30_000
+const ROOM = /^[\w.-]{1,128}$/
+export const ARCHIVED_CLOSE_CODE = 4410
+export const REFUSED_CLOSE_CODE = 4403
+export const ARCHIVE_DIR = '.presmium/classroom'
+const MAX_MESSAGE = 1 << 20
+const MAX_ENTRY = 16 << 10
+
+class Room extends Y.Doc {
+  readonly conns = new Map<WebSocket, Set<number>>()
+  readonly writers = new Map<WebSocket, string>()
+  readonly authors = new Map<number, string>()
+  readonly awareness?: awarenessProtocol.Awareness
+  archived = false
+  claim?: Buffer
+  readonly participants = new Map<string, Buffer>()
+  readonly personal: boolean
+
+  constructor(name: string) {
+    super({ gc: true })
+    this.authors.set(this.clientID, '')
+    this.personal = name.includes('.')
+    this.on('update', (update: Uint8Array) => {
+      const encoder = encoding.createEncoder()
+      encoding.writeVarUint(encoder, MESSAGE_SYNC)
+      syncProtocol.writeUpdate(encoder, update)
+      this.broadcast(encoding.toUint8Array(encoder))
+    })
+    if (this.personal) return
+    const awareness = this.awareness = new awarenessProtocol.Awareness(this)
+    awareness.setLocalState(null)
+    awareness.on('update', ({ added, updated, removed }: Record<'added' | 'updated' | 'removed', number[]>, conn: WebSocket | null) => {
+      const changed = [...added, ...updated, ...removed]
+      const controlled = conn && this.conns.get(conn)
+      if (controlled) {
+        added.forEach(id => controlled.add(id))
+        removed.forEach(id => controlled.delete(id))
+        const writer = this.writers.get(conn)!
+        for (const id of added) if (!this.authors.has(id)) this.authors.set(id, writer)
+      }
+      this.broadcast(awarenessMessage(awareness, changed))
+    })
+  }
+
+  get session(): Y.Map<unknown> {
+    return this.getMap('session')
+  }
+
+  get ended(): boolean {
+    return this.session.get('status') === 'ended'
+  }
+
+  broadcast(message: Uint8Array): void {
+    for (const conn of this.conns.keys()) send(conn, message)
+  }
+
+  content(): Record<string, unknown> {
+    return Object.fromEntries([...this.share.keys()].map(key => [key, this.getMap(key).toJSON()]))
+  }
+
+  override destroy(): void {
+    this.awareness?.destroy()
+    super.destroy()
+  }
+}
+
+function awarenessMessage(awareness: awarenessProtocol.Awareness, clients: number[]): Uint8Array {
+  const encoder = encoding.createEncoder()
+  encoding.writeVarUint(encoder, MESSAGE_AWARENESS)
+  encoding.writeVarUint8Array(encoder, awarenessProtocol.encodeAwarenessUpdate(awareness, clients))
+  return encoding.toUint8Array(encoder)
+}
+
+function send(conn: WebSocket, message: Uint8Array): void {
+  if (conn.readyState !== WebSocket.OPEN) return
+  conn.send(message, error => error && conn.close())
+}
+
+function roomName(url = '/'): string | undefined {
+  const name = url.slice(1).split('?')[0]!
+  return ROOM.test(name) ? name : undefined
+}
+
+function paramsOf(url = '/'): URLSearchParams {
+  return new URL(url, 'http://classroom').searchParams
+}
+
+function digest(key: string): Buffer {
+  return createHash('sha256').update(key).digest()
+}
+
+function sameKey(known: Buffer | undefined, key: string | null): boolean {
+  return Boolean(known && key && timingSafeEqual(known, digest(key)))
+}
+
+function readBody(request: IncomingMessage, limit = 1024): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let text = ''
+    request.setEncoding('utf8')
+    request.on('data', (chunk: string) => {
+      text += chunk
+      if (text.length > limit) request.destroy(new Error('request too large'))
+    })
+    request.on('end', () => resolve(text))
+    request.on('error', reject)
+  })
+}
+
+export interface ClassroomWriter {
+  presenter: boolean
+  participant?: string
+}
+
+function writerKey(writer: ClassroomWriter): string {
+  return writer.presenter ? 'presenter' : `participant:${writer.participant ?? ''}`
+}
+
+function structClients(update: Uint8Array): number[] {
+  return [...Y.parseUpdateMeta(update).from.keys()]
+}
+
+const PARTICIPANT_FIRST = new Set(['store:questions'])
+
+function ownKey(name: string, key: string, participant: string): boolean {
+  return PARTICIPANT_FIRST.has(name) ? key.slice(0, key.indexOf(':')) === participant : key.slice(key.lastIndexOf(':') + 1) === participant
+}
+
+function names(value: unknown, participant: string): boolean {
+  const entry = value as { participant?: unknown, author?: unknown } | null
+  return typeof entry === 'object' && entry !== null && !(entry instanceof Y.AbstractType) && (entry.participant === participant || entry.author === participant)
+}
+
+function entryRefusal(name: string, key: string | null, before: unknown, value: unknown, participant: string | undefined): string | undefined {
+  if (!participant) return 'a write from a connection that proved no participant'
+  if (key === null || !name.startsWith('store:') || name === 'store:quizzes') return `a write to ${name}, which is the presenter's`
+  if (!key.includes(':') || !ownKey(name, key, participant)) return `a write to ${name} under another participant's key`
+  if (before !== undefined && !names(before, participant)) return `a change to another participant's entry in ${name}`
+  if (value === undefined) return undefined
+  if (!names(value, participant)) return `a value in ${name} that does not name its participant`
+  return JSON.stringify(value).length > MAX_ENTRY ? `a value in ${name} over ${MAX_ENTRY} bytes` : undefined
+}
+
+function entryBefore(room: Y.Doc, name: string, key: string | null): unknown {
+  if (key === null || !room.share.has(name)) return undefined
+  try {
+    return room.getMap(name).get(key)
+  } catch {
+    return undefined
+  }
+}
+
+function pending(doc: Y.Doc): [structs: Uint8Array, deletions: Uint8Array] {
+  return [doc.store.pendingStructs?.update ?? new Uint8Array(), doc.store.pendingDs ?? new Uint8Array()]
+}
+
+function refusal(room: Room, update: Uint8Array, writer: ClassroomWriter): string | undefined {
+  const own = writerKey(writer)
+  if (structClients(update).some(client => (room.authors.get(client) ?? own) !== own)) return 'an update in the name of another writer\'s client'
+  const probe = new Y.Doc()
+  Y.applyUpdate(probe, Y.encodeStateAsUpdate(room))
+  const before = pending(probe)
+  const changes: [type: unknown, keys: Set<string | null>][] = []
+  probe.on('afterTransaction', (transaction: Y.Transaction) => changes.push(...transaction.changed))
+  Y.applyUpdate(probe, update)
+  const after = pending(probe)
+  let refused = before.every((bytes, i) => Buffer.compare(bytes, after[i]!) === 0) ? undefined : 'an update that does not integrate into the room'
+  for (const [type, keys] of changes) {
+    const name = [...probe.share].find(([, shared]) => shared === type)?.[0]
+    for (const key of keys) {
+      refused ??= name === undefined ? 'a change inside a nested type' : entryRefusal(name, key, entryBefore(room, name, key), key === null ? undefined : probe.getMap(name).get(key), writer.participant)
+    }
+  }
+  probe.destroy()
+  return refused
+}
+
+function changes(update: Uint8Array): boolean {
+  const { structs, ds } = Y.decodeUpdate(update)
+  return structs.length > 0 || ds.clients.size > 0
+}
+
+function ownAwareness(room: Room, awareness: awarenessProtocol.Awareness, conn: WebSocket, update: Uint8Array, writer: ClassroomWriter): { update: Uint8Array, dropped: number } {
+  const decoder = decoding.createDecoder(update)
+  const kept: [client: number, clock: number, state: string][] = []
+  let dropped = 0
+  const count = decoding.readVarUint(decoder)
+  for (let i = 0; i < count; i++) {
+    const entry: [number, number, string] = [decoding.readVarUint(decoder), decoding.readVarUint(decoder), decoding.readVarString(decoder)]
+    const [client, clock, state] = entry
+    const known = awareness.meta.get(client)?.clock ?? -1
+    if (clock < known || (clock === known && !(state === 'null' && awareness.getStates().has(client)))) continue
+    if (ownClient(room, conn, client, writer) && ownState(state, writer)) kept.push(entry)
+    else dropped++
+  }
+  const encoder = encoding.createEncoder()
+  encoding.writeVarUint(encoder, kept.length)
+  for (const [client, clock, state] of kept) {
+    encoding.writeVarUint(encoder, client)
+    encoding.writeVarUint(encoder, clock)
+    encoding.writeVarString(encoder, state)
+  }
+  return { update: encoding.toUint8Array(encoder), dropped }
+}
+
+function ownClient(room: Room, conn: WebSocket, client: number, writer: ClassroomWriter): boolean {
+  const own = writerKey(writer)
+  return (room.authors.get(client) ?? own) === own && ![...room.conns].some(([other, clients]) => other !== conn && clients.has(client))
+}
+
+function ownState(json: string, writer: ClassroomWriter): boolean {
+  if (writer.presenter) return true
+  try {
+    const participant = (JSON.parse(json) as { participant?: { id?: unknown, role?: unknown } | null } | null)?.participant
+    return participant == null || (writer.participant !== undefined && participant.id === writer.participant && participant.role === 'learner')
+  } catch {
+    return false
+  }
+}
+
+function handle(room: Room, conn: WebSocket, data: Uint8Array, writer: ClassroomWriter, drop: (reason: string) => void): void {
+  const decoder = decoding.createDecoder(data)
+  const type = decoding.readVarUint(decoder)
+  if (type === MESSAGE_SYNC) {
+    if (decoding.peekVarUint(decoder) !== syncProtocol.messageYjsSyncStep1) {
+      const message = decoding.clone(decoder)
+      decoding.readVarUint(message)
+      const update = decoding.readVarUint8Array(message)
+      if (room.ended) {
+        if (changes(update)) drop('an update after the classroom ended')
+        return
+      }
+      const refused = writer.presenter || room.personal ? undefined : refusal(room, update, writer)
+      if (refused) {
+        drop(refused)
+        conn.close(REFUSED_CLOSE_CODE, 'update refused')
+        return
+      }
+      const key = writerKey(writer)
+      for (const client of structClients(update)) if (!room.authors.has(client)) room.authors.set(client, key)
+    }
+    const encoder = encoding.createEncoder()
+    encoding.writeVarUint(encoder, MESSAGE_SYNC)
+    syncProtocol.readSyncMessage(decoder, encoder, room, conn)
+    if (encoding.length(encoder) > 1) send(conn, encoding.toUint8Array(encoder))
+  } else if (type === MESSAGE_AWARENESS && room.awareness) {
+    const own = ownAwareness(room, room.awareness, conn, decoding.readVarUint8Array(decoder), writer)
+    if (own.dropped > 0) drop(`${own.dropped} awareness state(s) of other clients or participants`)
+    awarenessProtocol.applyAwarenessUpdate(room.awareness, own.update, conn)
+  }
+}
+
+function reply(response: ServerResponse, status: number, body: Record<string, unknown>): void {
+  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' })
+  response.end(`${JSON.stringify(body)}\n`)
+}
+
+export interface ClassroomServerOptions {
+  port?: number
+  host?: string
+  deck?: string
+  onDropped?(room: string, writer: ClassroomWriter, reason: string): void
+}
+
+export interface ClassroomServer {
+  readonly port: number
+  readonly url: string
+  readonly archiveDir: string
+  close(): Promise<void>
+}
+
+function warnDropped(room: string, writer: ClassroomWriter, reason: string): void {
+  const who = writer.presenter ? 'the presenter' : writer.participant ? `participant ${writer.participant}` : 'an unidentified participant'
+  console.warn(`[classroom] room ${room}: dropped ${reason} from ${who}`)
+}
+
+export async function startClassroomServer(options: ClassroomServerOptions = {}): Promise<ClassroomServer> {
+  const rooms = new Map<string, Room>()
+  const archivedNames = new Set<string>()
+  const archiveDir = resolve(options.deck ?? '.', ARCHIVE_DIR)
+  const isArchived = (name: string) => [...archivedNames].some(archived => name === archived || name.startsWith(`${archived}.`))
+  const onDropped = options.onDropped ?? warnDropped
+
+  async function archive(name: string, key: string): Promise<{ status: number, body: Record<string, unknown> }> {
+    if (archivedNames.has(name)) return { status: 410, body: { error: `课堂 ${name} 已归档` } }
+    const room = rooms.get(name)
+    if (!room) return { status: 404, body: { error: `没有课堂 ${name}` } }
+    if (!sameKey(room.claim, key)) return { status: 403, body: { error: '只有创建课堂的主讲可以归档' } }
+    const now = Date.now()
+    room.transact(() => {
+      if (!room.ended) {
+        room.session.set('status', 'ended')
+        room.session.set('endedAt', now)
+      }
+    })
+    const file = join(ARCHIVE_DIR, `${name}.json`)
+    await mkdir(archiveDir, { recursive: true })
+    await writeFile(join(archiveDir, `${name}.json`), `${JSON.stringify({ room: name, archivedAt: new Date(now).toISOString(), document: room.content() }, null, 2)}\n`)
+    room.transact(() => {
+      room.session.set('archivedAt', now)
+      room.session.set('archive', file)
+    })
+    archivedNames.add(name)
+    for (const [key, freed] of rooms) {
+      if (!isArchived(key)) continue
+      rooms.delete(key)
+      freed.archived = true
+      if (freed.conns.size === 0) freed.destroy()
+      for (const conn of freed.conns.keys()) conn.close(ARCHIVED_CLOSE_CODE, 'classroom archived')
+    }
+    console.log(`[classroom] room ${name} archived to ${join(archiveDir, `${name}.json`)}`)
+    return { status: 200, body: { file } }
+  }
+
+  const http = createServer((request, response) => {
+    response.setHeader('Access-Control-Allow-Origin', '*')
+    const target = /^\/archive\/([^/?]+)(?:\?|$)/.exec(request.url ?? '')
+    if (request.method === 'OPTIONS') {
+      response.writeHead(204, { 'Access-Control-Allow-Methods': 'POST' })
+      response.end()
+    } else if (request.method === 'POST' && target && ROOM.test(target[1]!)) {
+      readBody(request).then(key => archive(target[1]!, key.trim())).then(
+        ({ status, body }) => reply(response, status, body),
+        (error: unknown) => {
+          console.error(`[classroom] room ${target[1]}: archive failed`, error)
+          reply(response, 500, { error: errorMessage(error) })
+        },
+      )
+    } else {
+      response.writeHead(200, { 'Content-Type': 'text/plain' })
+      response.end('presmium classroom server\n')
+    }
+  })
+  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_MESSAGE })
+
+  function connect(conn: WebSocket, request: IncomingMessage): void {
+    conn.on('error', error => console.error('[classroom] connection error:', error.message))
+    const name = roomName(request.url)
+    if (!name) {
+      conn.close(1008, 'invalid room name')
+      return
+    }
+    if (isArchived(name)) {
+      conn.close(ARCHIVED_CLOSE_CODE, 'classroom archived')
+      return
+    }
+    let room = rooms.get(name)
+    if (!room) rooms.set(name, room = new Room(name))
+    const current = room
+    const params = paramsOf(request.url)
+    const claim = params.get('claim')
+    if (claim && !current.claim) current.claim = digest(claim)
+    const writer: ClassroomWriter = { presenter: sameKey(current.claim, claim) }
+    const participant = params.get('participant')
+    const key = params.get('key')
+    if (participant && key && ROOM.test(participant)) {
+      if (!current.participants.has(participant)) current.participants.set(participant, digest(key))
+      if (sameKey(current.participants.get(participant), key)) writer.participant = participant
+    }
+    current.conns.set(conn, new Set())
+    current.writers.set(conn, writerKey(writer))
+    conn.binaryType = 'arraybuffer'
+    conn.on('message', (data: ArrayBuffer) => {
+      try {
+        handle(current, conn, new Uint8Array(data), writer, reason => onDropped(name, writer, reason))
+      } catch (error) {
+        console.error(`[classroom] room ${name}: bad message`, error)
+      }
+    })
+    let alive = true
+    conn.on('pong', () => alive = true)
+    const ping = setInterval(() => {
+      if (!alive || conn.readyState !== WebSocket.OPEN) {
+        conn.terminate()
+        return
+      }
+      alive = false
+      conn.ping()
+    }, PING_INTERVAL)
+    conn.on('close', () => {
+      clearInterval(ping)
+      const controlled = current.conns.get(conn)
+      current.conns.delete(conn)
+      current.writers.delete(conn)
+      if (current.archived) {
+        if (current.conns.size === 0) current.destroy()
+        return
+      }
+      if (controlled?.size && current.awareness) awarenessProtocol.removeAwarenessStates(current.awareness, [...controlled], null)
+      if (current.conns.size === 0 && current.store.clients.size === 0 && rooms.get(name) === current) {
+        rooms.delete(name)
+        current.destroy()
+      }
+    })
+    const encoder = encoding.createEncoder()
+    encoding.writeVarUint(encoder, MESSAGE_SYNC)
+    syncProtocol.writeSyncStep1(encoder, current)
+    send(conn, encoding.toUint8Array(encoder))
+    const states = current.awareness ? [...current.awareness.getStates().keys()] : []
+    if (current.awareness && states.length > 0) send(conn, awarenessMessage(current.awareness, states))
+  }
+
+  wss.on('connection', (conn: WebSocket, request: IncomingMessage) => {
+    try {
+      connect(conn, request)
+    } catch (error) {
+      console.error('[classroom] connection failed', error)
+      conn.terminate()
+    }
+  })
+  http.on('upgrade', (request, socket, head) => {
+    wss.handleUpgrade(request, socket, head, conn => wss.emit('connection', conn, request))
+  })
+  await new Promise<void>((resolve, reject) => {
+    http.once('error', reject)
+    http.listen(options.port ?? 1234, options.host ?? '0.0.0.0', () => resolve())
+  })
+  const { port } = http.address() as AddressInfo
+  const shown = !options.host || options.host === '0.0.0.0' || options.host === '::' ? 'localhost' : options.host
+  return {
+    port,
+    url: `ws://${shown.includes(':') ? `[${shown}]` : shown}:${port}`,
+    archiveDir,
+    async close() {
+      for (const client of wss.clients) client.terminate()
+      await new Promise<void>(resolve => wss.close(() => resolve()))
+      await new Promise<void>(resolve => http.close(() => resolve()))
+      for (const room of rooms.values()) room.destroy()
+      rooms.clear()
+    },
+  }
+}