feat(server): add comment-attachment storage (#12911)

close CLOUD-230












#### PR Dependency Tree


* **PR #12911** 👈
  * **PR #12761**
    * **PR #12924**
      * **PR #12925**

This tree was auto-generated by
[Charcoal](https://github.com/danerwilliams/charcoal)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added support for uploading and retrieving comment attachments in
workspace documents via a new API endpoint.
* Introduced a service for managing comment attachments, including
storage, retrieval, deletion, and URL generation.
* Implemented localized error messages and improved error handling for
missing comment attachments.

* **Bug Fixes**
  * Improved error feedback when comment attachments are not found.

* **Tests**
* Added comprehensive tests for comment attachment storage, retrieval,
deletion, API endpoint behavior, and permission checks.

* **Documentation**
* Updated GraphQL schema and localization files to include new error
types for comment attachments.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

packages/backend/server/src/core/storage/__tests__/comment-attachment.spec.ts

@@ -0,0 +1,141 @@
+import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
+
+import test from 'ava';
+
+import { createModule } from '../../../__tests__/create-module';
+import { Mockers } from '../../../__tests__/mocks';
+import { Models } from '../../../models';
+import { CommentAttachmentStorage, StorageModule } from '..';
+
+const module = await createModule({
+  imports: [StorageModule],
+});
+const storage = module.get(CommentAttachmentStorage);
+const models = module.get(Models);
+
+test.before(async () => {
+  await storage.onConfigInit();
+});
+
+test.after.always(async () => {
+  await module.close();
+});
+
+test('should put comment attachment', async t => {
+  const workspace = await module.create(Mockers.Workspace);
+  const docId = randomUUID();
+  const key = randomUUID();
+  const blob = Buffer.from('test');
+
+  await storage.put(workspace.id, docId, key, 'test.txt', blob);
+
+  const item = await models.commentAttachment.get(workspace.id, docId, key);
+
+  t.truthy(item);
+  t.is(item?.workspaceId, workspace.id);
+  t.is(item?.docId, docId);
+  t.is(item?.key, key);
+  t.is(item?.mime, 'text/plain');
+  t.is(item?.size, blob.length);
+  t.is(item?.name, 'test.txt');
+});
+
+test('should get comment attachment', async t => {
+  const workspace = await module.create(Mockers.Workspace);
+  const docId = randomUUID();
+  const key = randomUUID();
+  const blob = Buffer.from('test');
+
+  await storage.put(workspace.id, docId, key, 'test.txt', blob);
+
+  const item = await storage.get(workspace.id, docId, key);
+
+  t.truthy(item);
+  t.is(item?.metadata?.contentType, 'text/plain');
+  t.is(item?.metadata?.contentLength, blob.length);
+  // body is readable stream
+  t.truthy(item?.body);
+  const bytes = await readableToBytes(item?.body as Readable);
+  t.is(bytes.toString(), 'test');
+});
+
+test('should get comment attachment with access url', async t => {
+  const workspace = await module.create(Mockers.Workspace);
+  const docId = randomUUID();
+  const key = randomUUID();
+  const blob = Buffer.from('test');
+
+  await storage.put(workspace.id, docId, key, 'test.txt', blob);
+
+  const url = storage.getUrl(workspace.id, docId, key);
+
+  t.truthy(url);
+  t.is(
+    url,
+    `http://localhost:3010/api/workspaces/${workspace.id}/docs/${docId}/comment-attachments/${key}`
+  );
+});
+
+test('should delete comment attachment', async t => {
+  const workspace = await module.create(Mockers.Workspace);
+  const docId = randomUUID();
+  const key = randomUUID();
+  const blob = Buffer.from('test');
+
+  await storage.put(workspace.id, docId, key, 'test.txt', blob);
+
+  await storage.delete(workspace.id, docId, key);
+
+  const item = await models.commentAttachment.get(workspace.id, docId, key);
+
+  t.is(item, null);
+});
+
+test('should handle comment.attachment.delete event', async t => {
+  const workspace = await module.create(Mockers.Workspace);
+  const docId = randomUUID();
+  const key = randomUUID();
+  const blob = Buffer.from('test');
+
+  await storage.put(workspace.id, docId, key, 'test.txt', blob);
+
+  await storage.onCommentAttachmentDelete({
+    workspaceId: workspace.id,
+    docId,
+    key,
+  });
+
+  const item = await models.commentAttachment.get(workspace.id, docId, key);
+
+  t.is(item, null);
+});
+
+test('should handle workspace.deleted event', async t => {
+  const workspace = await module.create(Mockers.Workspace);
+  const docId = randomUUID();
+  const key1 = randomUUID();
+  const key2 = randomUUID();
+  const blob1 = Buffer.from('test');
+  const blob2 = Buffer.from('test2');
+
+  await storage.put(workspace.id, docId, key1, 'test.txt', blob1);
+  await storage.put(workspace.id, docId, key2, 'test.txt', blob2);
+
+  const count = module.event.count('comment.attachment.delete');
+
+  await storage.onWorkspaceDeleted({
+    id: workspace.id,
+  });
+
+  t.is(module.event.count('comment.attachment.delete'), count + 2);
+});
+
+async function readableToBytes(stream: Readable) {
+  const chunks: Buffer[] = [];
+  let chunk: Buffer;
+  for await (chunk of stream) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}

packages/backend/server/src/core/storage/index.ts

@@ -2,12 +2,16 @@ import './config';
 
 import { Module } from '@nestjs/common';
 
-import { AvatarStorage, WorkspaceBlobStorage } from './wrappers';
+import {
+  AvatarStorage,
+  CommentAttachmentStorage,
+  WorkspaceBlobStorage,
+} from './wrappers';
 
 @Module({
-  providers: [WorkspaceBlobStorage, AvatarStorage],
-  exports: [WorkspaceBlobStorage, AvatarStorage],
+  providers: [WorkspaceBlobStorage, AvatarStorage, CommentAttachmentStorage],
+  exports: [WorkspaceBlobStorage, AvatarStorage, CommentAttachmentStorage],
 })
 export class StorageModule {}
 
-export { AvatarStorage, WorkspaceBlobStorage };
+export { AvatarStorage, CommentAttachmentStorage, WorkspaceBlobStorage };

packages/backend/server/src/core/storage/wrappers/comment-attachment.ts

@@ -0,0 +1,128 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+import {
+  autoMetadata,
+  Config,
+  EventBus,
+  OnEvent,
+  type StorageProvider,
+  StorageProviderFactory,
+  URLHelper,
+} from '../../../base';
+import { Models } from '../../../models';
+
+declare global {
+  interface Events {
+    'comment.attachment.delete': {
+      workspaceId: string;
+      docId: string;
+      key: string;
+    };
+  }
+}
+
+@Injectable()
+export class CommentAttachmentStorage {
+  private readonly logger = new Logger(CommentAttachmentStorage.name);
+  private provider!: StorageProvider;
+
+  get config() {
+    return this.AFFiNEConfig.storages.blob;
+  }
+
+  constructor(
+    private readonly AFFiNEConfig: Config,
+    private readonly event: EventBus,
+    private readonly storageFactory: StorageProviderFactory,
+    private readonly models: Models,
+    private readonly url: URLHelper
+  ) {}
+
+  @OnEvent('config.init')
+  async onConfigInit() {
+    this.provider = this.storageFactory.create(this.config.storage);
+  }
+
+  @OnEvent('config.changed')
+  async onConfigChanged(event: Events['config.changed']) {
+    if (event.updates.storages?.blob?.storage) {
+      this.provider = this.storageFactory.create(this.config.storage);
+    }
+  }
+
+  private storageKey(workspaceId: string, docId: string, key: string) {
+    return `comment-attachments/${workspaceId}/${docId}/${key}`;
+  }
+
+  async put(
+    workspaceId: string,
+    docId: string,
+    key: string,
+    name: string,
+    blob: Buffer
+  ) {
+    const meta = autoMetadata(blob);
+
+    await this.provider.put(
+      this.storageKey(workspaceId, docId, key),
+      blob,
+      meta
+    );
+    await this.models.commentAttachment.upsert({
+      workspaceId,
+      docId,
+      key,
+      name,
+      mime: meta.contentType ?? 'application/octet-stream',
+      size: blob.length,
+    });
+  }
+
+  async get(
+    workspaceId: string,
+    docId: string,
+    key: string,
+    signedUrl?: boolean
+  ) {
+    return await this.provider.get(
+      this.storageKey(workspaceId, docId, key),
+      signedUrl
+    );
+  }
+
+  async delete(workspaceId: string, docId: string, key: string) {
+    await this.provider.delete(this.storageKey(workspaceId, docId, key));
+    await this.models.commentAttachment.delete(workspaceId, docId, key);
+    this.logger.log(
+      `deleted comment attachment ${workspaceId}/${docId}/${key}`
+    );
+  }
+
+  getUrl(workspaceId: string, docId: string, key: string) {
+    return this.url.link(
+      `/api/workspaces/${workspaceId}/docs/${docId}/comment-attachments/${key}`
+    );
+  }
+
+  @OnEvent('workspace.deleted')
+  async onWorkspaceDeleted({ id }: Events['workspace.deleted']) {
+    const attachments = await this.models.commentAttachment.list(id);
+
+    for (const attachment of attachments) {
+      this.event.emit('comment.attachment.delete', {
+        workspaceId: id,
+        docId: attachment.docId,
+        key: attachment.key,
+      });
+    }
+  }
+
+  @OnEvent('comment.attachment.delete')
+  async onCommentAttachmentDelete({
+    workspaceId,
+    docId,
+    key,
+  }: Events['comment.attachment.delete']) {
+    await this.delete(workspaceId, docId, key);
+  }
+}

packages/backend/server/src/core/storage/wrappers/index.ts

@@ -1,2 +1,3 @@
 export { AvatarStorage } from './avatar';
 export { WorkspaceBlobStorage } from './blob';
+export { CommentAttachmentStorage } from './comment-attachment';

packages/backend/server/src/core/workspaces/controller.ts

@@ -4,6 +4,7 @@ import type { Response } from 'express';
 import {
   BlobNotFound,
   CallMetric,
+  CommentAttachmentNotFound,
   DocHistoryNotFound,
   DocNotFound,
   InvalidHistoryTimestamp,
@@ -13,7 +14,7 @@ import { CurrentUser, Public } from '../auth';
 import { PgWorkspaceDocStorageAdapter } from '../doc';
 import { DocReader } from '../doc/reader';
 import { AccessController } from '../permission';
-import { WorkspaceBlobStorage } from '../storage';
+import { CommentAttachmentStorage, WorkspaceBlobStorage } from '../storage';
 import { DocID } from '../utils/doc';
 
 @Controller('/api/workspaces')
@@ -21,6 +22,7 @@ export class WorkspacesController {
   logger = new Logger(WorkspacesController.name);
   constructor(
     private readonly storage: WorkspaceBlobStorage,
+    private readonly commentAttachmentStorage: CommentAttachmentStorage,
     private readonly ac: AccessController,
     private readonly workspace: PgWorkspaceDocStorageAdapter,
     private readonly docReader: DocReader,
@@ -180,4 +182,41 @@ export class WorkspacesController {
       });
     }
   }
+
+  @Get('/:id/docs/:docId/comment-attachments/:key')
+  @CallMetric('controllers', 'workspace_get_comment_attachment')
+  async commentAttachment(
+    @CurrentUser() user: CurrentUser,
+    @Param('id') workspaceId: string,
+    @Param('docId') docId: string,
+    @Param('key') key: string,
+    @Res() res: Response
+  ) {
+    await this.ac.user(user.id).doc(workspaceId, docId).assert('Doc.Read');
+
+    const { body, metadata, redirectUrl } =
+      await this.commentAttachmentStorage.get(workspaceId, docId, key);
+
+    if (redirectUrl) {
+      return res.redirect(redirectUrl);
+    }
+
+    if (!body) {
+      throw new CommentAttachmentNotFound();
+    }
+
+    // metadata should always exists if body is not null
+    if (metadata) {
+      res.setHeader('content-type', metadata.contentType);
+      res.setHeader('last-modified', metadata.lastModified.toUTCString());
+      res.setHeader('content-length', metadata.contentLength);
+    } else {
+      this.logger.warn(
+        `Comment attachment ${workspaceId}/${docId}/${key} has no metadata`
+      );
+    }
+
+    res.setHeader('cache-control', 'private, max-age=2592000, immutable');
+    body.pipe(res);
+  }
 }