task API

The Task API allows for an easy way to create long-lived tasks that
require reporting back to user with progress/logs. It will be used in
the upcoming game importing.

server/server/internal/library/README.md

@@ -0,0 +1,11 @@
+# Library Format
+
+Drop uses a filesystem-based library format, as it targets homelabs and not enterprise-grade solutions. The format works as follows:
+
+## /{game name}
+
+The game name is only used for initial matching, and doesn't affect actual metadata. Metadata is linked to the game's database entry, which is linked to it's filesystem name (they, however, can be completely different).
+
+## /{game name}/{version name}
+
+The version name can be anything. Versions have to manually imported within the web UI. There, you can change the order of the updates and mark them as deltas. Delta updates apply files over the previous versions. 

server/server/internal/tasks/index.ts

@@ -0,0 +1,145 @@
+/**
+ * The TaskHandler setups up two-way connections to web clients and manages the state for them
+ * This allows long-running tasks (like game imports and such) to report progress, success and error states
+ * easily without re-inventing the wheel every time.
+ */
+
+type TaskRegistryEntry = {
+  runPromise: Promise<void>;
+  success: boolean;
+  progress: number;
+  log: string[];
+  error: string | undefined;
+  clients: { [key: string]: boolean };
+  name: string;
+};
+
+class TaskHandler {
+  private taskRegistry: { [key: string]: TaskRegistryEntry } = {};
+  private clientRegistry: { [key: string]: PeerImpl } = {};
+
+  constructor() {}
+
+  create(task: Task) {
+    let updateCollectTimeout: NodeJS.Timeout | undefined;
+
+    const updateAllClients = () => {
+      if (updateCollectTimeout) return;
+      updateCollectTimeout = setTimeout(() => {
+        const taskEntry = this.taskRegistry[task.id];
+        if (!taskEntry) return;
+        const taskMessage: TaskMessage = {
+          id: task.id,
+          success: taskEntry.success,
+          progress: taskEntry.progress,
+          error: taskEntry.error,
+          log: taskEntry.log,
+        };
+        for (const client of Object.keys(taskEntry.clients)) {
+          if (!this.clientRegistry[client]) continue;
+          this.clientRegistry[client].send(taskMessage);
+        }
+        updateCollectTimeout = undefined;
+      }, 500);
+    };
+
+    const progress = (progress: number) => {
+      const taskEntry = this.taskRegistry[task.id];
+      if (!taskEntry) return;
+      this.taskRegistry[task.id].progress = progress;
+      updateAllClients();
+    };
+
+    const log = (entry: string) => {
+      const taskEntry = this.taskRegistry[task.id];
+      if (!taskEntry) return;
+      this.taskRegistry[task.id].log.push(entry);
+      updateAllClients();
+    };
+
+    const promiseRun = task.run({ progress, log });
+    promiseRun.then(() => {
+      const taskEntry = this.taskRegistry[task.id];
+      if (!taskEntry) return;
+      this.taskRegistry[task.id].success = true;
+      updateAllClients();
+    });
+    promiseRun.catch((error) => {
+      const taskEntry = this.taskRegistry[task.id];
+      if (!taskEntry) return;
+      this.taskRegistry[task.id].success = false;
+      this.taskRegistry[task.id].error = error;
+      updateAllClients();
+    });
+    this.taskRegistry[task.id] = {
+      name: task.name,
+      runPromise: promiseRun,
+      success: false,
+      progress: 0,
+      error: undefined,
+      log: [],
+      clients: {},
+    };
+  }
+
+  connect(id: string, taskId: string, peer: PeerImpl) {
+    const task = this.taskRegistry[taskId];
+    if (!task) return false;
+
+    this.clientRegistry[id] = peer;
+    this.taskRegistry[taskId].clients[id] = true; // Uniquely insert client to avoid sending duplicate traffic
+
+    const catchupMessage: TaskMessage = {
+      id: taskId,
+      success: task.success,
+      error: task.error,
+      log: task.log,
+      progress: task.progress,
+    };
+    peer.send(catchupMessage);
+
+    return true;
+  }
+
+  disconnect(id: string, taskId: string) {
+    if (!this.taskRegistry[taskId]) return false;
+
+    delete this.taskRegistry[taskId].clients[id];
+
+    const allClientIds = Object.values(this.taskRegistry)
+      .map((_) => Object.keys(_.clients))
+      .flat();
+
+    if (!allClientIds.includes(id)) {
+      delete this.clientRegistry[id];
+    }
+
+    return true;
+  }
+}
+
+export type TaskRunContext = {
+  progress: (progress: number) => void;
+  log: (message: string) => void;
+};
+
+export interface Task {
+  id: string;
+  name: string;
+  run: (context: TaskRunContext) => Promise<void>;
+}
+
+export type TaskMessage = {
+  id: string;
+  success: boolean;
+  progress: number;
+  error: undefined | string;
+  log: string[];
+};
+
+export type PeerImpl = {
+  send: (message: TaskMessage) => void;
+};
+
+export const taskHandler = new TaskHandler();
+export default taskHandler;