feat: attachments on tickets and comments

Files are uploaded over REST, stored on disk (a volume in Docker) and
recorded on the ticket as events; the bytes are written first, so no
attachment ever points at a missing file. Only images, video, audio, PDF
and plain text are shown inline, everything with nosniff and a sandbox CSP.
The web shows thumbnails, uploads by drag and drop or by pasting a
screenshot, and attaches files to new comments.

Also adds `nx run api:contracts`, which writes schema.gql and
openapi.json without starting the API or any database.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

libs/api/tracker/application/src/lib/commands/attach-file.command-handler.ts

@@ -0,0 +1,57 @@
+import { randomUUID } from 'node:crypto';
+import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+import { BusinessRuleError } from '@task-stream/api/shared/domain';
+import { AttachmentStorage, attachmentKey } from '../ports/attachment-storage';
+import { AttachFileCommand } from './attach-file.command';
+import { CommandResult, ack } from './command-result';
+import { WriteAccess } from './write-access';
+
+/**
+ * Stores the bytes first and records them on the ticket after: a file with no
+ * record is cleaned up here, never a record with no file.
+ */
+@CommandHandler(AttachFileCommand)
+export class AttachFileCommandHandler
+  implements ICommandHandler<AttachFileCommand>
+{
+  constructor(
+    private readonly access: WriteAccess,
+    private readonly storage: AttachmentStorage,
+  ) {}
+
+  async execute(command: AttachFileCommand): Promise<CommandResult> {
+    const { issue } = await this.access.issueForContributor(
+      command.issueId,
+      command.actorId,
+    );
+    if (command.commentId) {
+      const comment = await this.access.comment(command.commentId);
+      if (comment.issueId !== issue.id) {
+        throw new BusinessRuleError(
+          `That comment belongs to another ticket, not ${issue.key}`,
+        );
+      }
+    }
+
+    const id = randomUUID();
+    const key = attachmentKey(issue.projectId, issue.id, id);
+    issue.attach(command.actorId, {
+      id,
+      fileName: command.file.fileName,
+      mimeType: command.file.mimeType,
+      size: command.file.content.length,
+      uploadedBy: command.actorId,
+      uploadedAt: new Date().toISOString(),
+      commentId: command.commentId,
+    });
+
+    await this.storage.put(key, command.file.content);
+    try {
+      await issue.commitAndWait();
+    } catch (error) {
+      await this.storage.remove(key);
+      throw error;
+    }
+    return ack(issue);
+  }
+}

libs/api/tracker/application/src/lib/commands/attach-file.command.ts

@@ -0,0 +1,20 @@
+import { Command } from '@nestjs/cqrs';
+import { CommandResult } from './command-result';
+
+export interface IncomingFile {
+  fileName: string;
+  mimeType: string;
+  content: Buffer;
+}
+
+export class AttachFileCommand extends Command<CommandResult> {
+  constructor(
+    public readonly actorId: string,
+    public readonly issueId: string,
+    public readonly file: IncomingFile,
+    /** Places it under one of the ticket's comments. */
+    public readonly commentId: string | null = null,
+  ) {
+    super();
+  }
+}

libs/api/tracker/application/src/lib/commands/command-handlers.ts

@@ -25,6 +25,8 @@ import { PurgeCommentCommandHandler } from './purge-comment.command-handler';
 import { DropLinksToIssueCommandHandler } from './drop-links-to-issue.command-handler';
 import { DetachIssueFromReleaseCommandHandler } from './detach-issue-from-release.command-handler';
 import { UnassignIssueCommandHandler } from './unassign-issue.command-handler';
+import { AttachFileCommandHandler } from './attach-file.command-handler';
+import { DetachFileCommandHandler } from './detach-file.command-handler';
 
 export const COMMAND_HANDLERS = [
   CreateProjectCommandHandler,
@@ -55,4 +57,6 @@ export const COMMAND_HANDLERS = [
   DropLinksToIssueCommandHandler,
   DetachIssueFromReleaseCommandHandler,
   UnassignIssueCommandHandler,
+  AttachFileCommandHandler,
+  DetachFileCommandHandler,
 ];

libs/api/tracker/application/src/lib/commands/commands.spec.ts

@@ -12,6 +12,7 @@ import {
 } from '@task-stream/api/shared/domain';
 import {
   Comment,
+  Issue,
   IssueStatus,
   Project,
   IssueType,
@@ -20,6 +21,7 @@ import {
 } from '@task-stream/api/tracker/domain';
 import {
   FakeUserDirectory,
+  InMemoryAttachmentStorage,
   InMemoryEventStore,
   InMemoryEventStorePublisher,
   InMemoryIssueNumbers,
@@ -32,9 +34,12 @@ import { IssueNumbersRepository } from '../ports/issue-numbers.repository';
 import { ProjectKeysRepository } from '../ports/project-keys.repository';
 import { ReleaseNamesRepository } from '../ports/release-names.repository';
 import { UserDirectory } from '../ports/user-directory';
+import { AttachmentStorage } from '../ports/attachment-storage';
 import { AddCommentCommand } from './add-comment.command';
 import { AddProjectMemberCommand } from './add-project-member.command';
 import { AssignIssueCommand } from './assign-issue.command';
+import { AttachFileCommand } from './attach-file.command';
+import { DetachFileCommand } from './detach-file.command';
 import { ChangeIssueStatusCommand } from './change-issue-status.command';
 import { COMMAND_HANDLERS } from './command-handlers';
 import { CommandResult } from './command-result';
@@ -48,6 +53,7 @@ import { WriteAccess } from './write-access';
 
 async function setup() {
   const store = new InMemoryEventStore();
+  const files = new InMemoryAttachmentStorage();
   const users = new FakeUserDirectory()
     .add('owner')
     .add('dev')
@@ -62,6 +68,7 @@ async function setup() {
       WriteAccess,
       AggregateRehydrator,
       { provide: EventStore, useValue: store },
+      { provide: AttachmentStorage, useValue: files },
       { provide: UserDirectory, useValue: users },
       { provide: ProjectKeysRepository, useClass: InMemoryProjectKeys },
       { provide: IssueNumbersRepository, useClass: InMemoryIssueNumbers },
@@ -78,7 +85,12 @@ async function setup() {
   const commandBus = moduleRef.get(CommandBus);
   const run = (command: object): Promise<CommandResult> =>
     commandBus.execute(command as never);
-  return { store, run, rehydrator: moduleRef.get(AggregateRehydrator) };
+  return {
+    store,
+    files,
+    run,
+    rehydrator: moduleRef.get(AggregateRehydrator),
+  };
 }
 
 async function projectWithTeam(run: (c: object) => Promise<CommandResult>) {
@@ -178,6 +190,74 @@ describe('tracker commands (event sourced)', () => {
     ).rejects.toThrow(BusinessRuleError);
   });
 
+  describe('attachments', () => {
+    const png = {
+      fileName: 'captura.png',
+      mimeType: 'image/png',
+      content: Buffer.from('fake png'),
+    };
+
+    it('stores the file and records it on the ticket', async () => {
+      const { run, files, rehydrator } = await setup();
+      const projectId = await projectWithTeam(run);
+      const issue = await run(
+        new CreateIssueCommand('qa', projectId, IssueType.BUG, 'Crash', {}),
+      );
+
+      await run(new AttachFileCommand('qa', issue.id, png));
+
+      const rebuilt = await rehydrator.rehydrate(issue.id, Issue);
+      expect(rebuilt.attachments).toHaveLength(1);
+      expect(rebuilt.attachments[0]).toMatchObject({
+        fileName: 'captura.png',
+        size: 8,
+        uploadedBy: 'qa',
+      });
+      expect([...files.files.keys()]).toEqual([
+        `${projectId}/${issue.id}/${rebuilt.attachments[0].id}`,
+      ]);
+    });
+
+    it('keeps no file when the ticket cannot take it', async () => {
+      const { run, files } = await setup();
+      const projectId = await projectWithTeam(run);
+      const issue = await run(
+        new CreateIssueCommand('qa', projectId, IssueType.BUG, 'Crash', {}),
+      );
+
+      await expect(
+        run(new AttachFileCommand('pm', issue.id, png)),
+      ).rejects.toThrow(ForbiddenError);
+      await expect(
+        run(
+          new AttachFileCommand('qa', issue.id, {
+            ...png,
+            content: Buffer.alloc(0),
+          }),
+        ),
+      ).rejects.toThrow();
+      expect(files.files.size).toBe(0);
+    });
+
+    it('lets the uploader or an admin remove it, and deletes the bytes', async () => {
+      const { run, files, rehydrator } = await setup();
+      const projectId = await projectWithTeam(run);
+      const issue = await run(
+        new CreateIssueCommand('qa', projectId, IssueType.BUG, 'Crash', {}),
+      );
+      await run(new AttachFileCommand('qa', issue.id, png));
+      const [attachment] = (await rehydrator.rehydrate(issue.id, Issue))
+        .attachments;
+
+      await expect(
+        run(new DetachFileCommand('dev', issue.id, attachment.id)),
+      ).rejects.toThrow(ForbiddenError);
+      await run(new DetachFileCommand('owner', issue.id, attachment.id));
+
+      expect(files.files.size).toBe(0);
+    });
+  });
+
   it('does not let viewers modify tickets', async () => {
     const { run } = await setup();
     const projectId = await projectWithTeam(run);

libs/api/tracker/application/src/lib/commands/detach-file.command-handler.ts

@@ -0,0 +1,35 @@
+import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+import { ProjectRole } from '@task-stream/api/tracker/domain';
+import { AttachmentStorage, attachmentKey } from '../ports/attachment-storage';
+import { CommandResult, ack } from './command-result';
+import { DetachFileCommand } from './detach-file.command';
+import { WriteAccess } from './write-access';
+
+/** Removes the record first; the bytes go once nothing points at them. */
+@CommandHandler(DetachFileCommand)
+export class DetachFileCommandHandler
+  implements ICommandHandler<DetachFileCommand>
+{
+  constructor(
+    private readonly access: WriteAccess,
+    private readonly storage: AttachmentStorage,
+  ) {}
+
+  async execute(command: DetachFileCommand): Promise<CommandResult> {
+    const { issue, project } = await this.access.issueForContributor(
+      command.issueId,
+      command.actorId,
+    );
+    const role = project.roleOf(command.actorId);
+    issue.detach(
+      command.actorId,
+      command.attachmentId,
+      role === ProjectRole.OWNER || role === ProjectRole.ADMIN,
+    );
+    await issue.commitAndWait();
+    await this.storage.remove(
+      attachmentKey(issue.projectId, issue.id, command.attachmentId),
+    );
+    return ack(issue);
+  }
+}

libs/api/tracker/application/src/lib/commands/detach-file.command.ts

@@ -0,0 +1,12 @@
+import { Command } from '@nestjs/cqrs';
+import { CommandResult } from './command-result';
+
+export class DetachFileCommand extends Command<CommandResult> {
+  constructor(
+    public readonly actorId: string,
+    public readonly issueId: string,
+    public readonly attachmentId: string,
+  ) {
+    super();
+  }
+}

libs/api/tracker/application/src/lib/commands/index.ts

@@ -26,3 +26,5 @@ export * from './purge-comment.command';
 export * from './drop-links-to-issue.command';
 export * from './detach-issue-from-release.command';
 export * from './unassign-issue.command';
+export * from './attach-file.command';
+export * from './detach-file.command';

libs/api/tracker/application/src/lib/event-handlers/activity-summary.ts

@@ -3,6 +3,8 @@ import {
   CommentDeletedEvent,
   CommentEditedEvent,
   IssueAssignedEvent,
+  IssueAttachmentAddedEvent,
+  IssueAttachmentRemovedEvent,
   IssueCreatedEvent,
   IssueLinkedEvent,
   IssueLinkType,
@@ -135,6 +137,11 @@ export function describeEvent(
       : `${actor} sacó ${issueKey} de su release`;
   }
 
+  if (event instanceof IssueAttachmentAddedEvent)
+    return `${actor} adjuntó ${event.attachment.fileName} a ${issueKey}`;
+  if (event instanceof IssueAttachmentRemovedEvent)
+    return `${actor} quitó el adjunto ${event.fileName} de ${issueKey}`;
+
   if (event instanceof CommentAddedEvent)
     return `${actor} comentó en ${issueKey}`;
   if (event instanceof CommentEditedEvent)

libs/api/tracker/application/src/lib/event-handlers/activity.event-handler.ts

@@ -5,6 +5,8 @@ import {
   CommentDeletedEvent,
   CommentEditedEvent,
   IssueAssignedEvent,
+  IssueAttachmentAddedEvent,
+  IssueAttachmentRemovedEvent,
   IssueCreatedEvent,
   IssueLinkedEvent,
   IssueReleaseChangedEvent,
@@ -51,6 +53,8 @@ import { versionOf } from './read-model-notifier';
   IssueLinkedEvent,
   IssueUnlinkedEvent,
   IssueReleaseChangedEvent,
+  IssueAttachmentAddedEvent,
+  IssueAttachmentRemovedEvent,
   CommentAddedEvent,
   CommentEditedEvent,
   CommentDeletedEvent,

libs/api/tracker/application/src/lib/event-handlers/attachment-cleanup.event-handler.ts

@@ -0,0 +1,20 @@
+import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
+import { IssueDeletedEvent } from '@task-stream/api/tracker/domain';
+import {
+  AttachmentStorage,
+  issueAttachmentsPrefix,
+} from '../ports/attachment-storage';
+
+/** A deleted ticket takes its files with it. */
+@EventsHandler(IssueDeletedEvent)
+export class AttachmentCleanupEventHandler
+  implements IEventHandler<IssueDeletedEvent>
+{
+  constructor(private readonly storage: AttachmentStorage) {}
+
+  async handle(event: IssueDeletedEvent) {
+    await this.storage.removePrefix(
+      issueAttachmentsPrefix(event.projectId, event.aggregateId),
+    );
+  }
+}

libs/api/tracker/application/src/lib/event-handlers/event-handlers.ts

@@ -24,6 +24,9 @@ import { ProjectSettingsChangedEventHandler } from './project-settings-changed.e
 import { ProjectDeletedEventHandler } from './project-deleted.event-handler';
 import { IssueDeletedEventHandler } from './issue-deleted.event-handler';
 import { ReleaseDeletedEventHandler } from './release-deleted.event-handler';
+import { IssueAttachmentAddedEventHandler } from './issue-attachment-added.event-handler';
+import { IssueAttachmentRemovedEventHandler } from './issue-attachment-removed.event-handler';
+import { AttachmentCleanupEventHandler } from './attachment-cleanup.event-handler';
 
 /** Read-model projections (MongoDB) + realtime, fed by the EventsBridge. */
 export const EVENT_HANDLERS = [
@@ -52,6 +55,9 @@ export const EVENT_HANDLERS = [
   ReleaseCreatedEventHandler,
   ReleaseShippedEventHandler,
   ReleaseUpdatedEventHandler,
+  IssueAttachmentAddedEventHandler,
+  IssueAttachmentRemovedEventHandler,
+  AttachmentCleanupEventHandler,
 ];
 
 export { ReadModelNotifier };

libs/api/tracker/application/src/lib/event-handlers/issue-attachment-added.event-handler.ts

@@ -0,0 +1,31 @@
+import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
+import { IssueAttachmentAddedEvent } from '@task-stream/api/tracker/domain';
+import { UpsertMaterializedIssueRepository } from '../ports/upsert-materialized-issue.repository';
+import { UserDirectory } from '../ports/user-directory';
+import { ReadModelNotifier, versionOf } from './read-model-notifier';
+
+@EventsHandler(IssueAttachmentAddedEvent)
+export class IssueAttachmentAddedEventHandler
+  implements IEventHandler<IssueAttachmentAddedEvent>
+{
+  constructor(
+    private readonly upsertMaterializedIssueRepository: UpsertMaterializedIssueRepository,
+    private readonly users: UserDirectory,
+    private readonly notifier: ReadModelNotifier,
+  ) {}
+
+  async handle(event: IssueAttachmentAddedEvent) {
+    const { attachment } = event;
+    const users = await this.users.refs([attachment.uploadedBy]);
+    await this.upsertMaterializedIssueRepository.upsert({
+      id: event.aggregateId,
+      updatedAt: event.occurredAt,
+      version: versionOf(event),
+    });
+    await this.upsertMaterializedIssueRepository.addAttachment(
+      event.aggregateId,
+      { ...attachment, uploadedBy: users.of(attachment.uploadedBy) },
+    );
+    await this.notifier.issue(event.aggregateId, event);
+  }
+}

libs/api/tracker/application/src/lib/event-handlers/issue-attachment-removed.event-handler.ts

@@ -0,0 +1,27 @@
+import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
+import { IssueAttachmentRemovedEvent } from '@task-stream/api/tracker/domain';
+import { UpsertMaterializedIssueRepository } from '../ports/upsert-materialized-issue.repository';
+import { ReadModelNotifier, versionOf } from './read-model-notifier';
+
+@EventsHandler(IssueAttachmentRemovedEvent)
+export class IssueAttachmentRemovedEventHandler
+  implements IEventHandler<IssueAttachmentRemovedEvent>
+{
+  constructor(
+    private readonly upsertMaterializedIssueRepository: UpsertMaterializedIssueRepository,
+    private readonly notifier: ReadModelNotifier,
+  ) {}
+
+  async handle(event: IssueAttachmentRemovedEvent) {
+    await this.upsertMaterializedIssueRepository.upsert({
+      id: event.aggregateId,
+      updatedAt: event.occurredAt,
+      version: versionOf(event),
+    });
+    await this.upsertMaterializedIssueRepository.removeAttachment(
+      event.aggregateId,
+      event.attachmentId,
+    );
+    await this.notifier.issue(event.aggregateId, event);
+  }
+}

libs/api/tracker/application/src/lib/issues.service.ts

@@ -7,6 +7,11 @@ import {
   IssueReadModel,
 } from '@task-stream/api/tracker/domain';
 import { AssignIssueCommand } from './commands/assign-issue.command';
+import {
+  AttachFileCommand,
+  IncomingFile,
+} from './commands/attach-file.command';
+import { DetachFileCommand } from './commands/detach-file.command';
 import { ChangeIssueStatusCommand } from './commands/change-issue-status.command';
 import { CommandResult } from './commands/command-result';
 import { CreateIssueCommand } from './commands/create-issue.command';
@@ -16,6 +21,10 @@ import { UnlinkIssuesCommand } from './commands/unlink-issues.command';
 import { UpdateIssueCommand } from './commands/update-issue.command';
 import { IssueFilter, Page } from './ports/find-issues.repository';
 import { GetActivityQuery } from './queries/get-activity.query';
+import {
+  AttachmentDownload,
+  GetAttachmentQuery,
+} from './queries/get-attachment.query';
 import { GetIssueQuery } from './queries/get-issue.query';
 import { GetIssuesByIdsQuery } from './queries/get-issues-by-ids.query';
 import { SearchIssuesQuery } from './queries/search-issues.query';
@@ -126,6 +135,39 @@ export class IssuesService {
     );
   }
 
+  /** Attaches a file to the ticket, or to one of its comments. */
+  attach(
+    actorId: string,
+    issueId: string,
+    file: IncomingFile,
+    commentId: string | null = null,
+  ): Promise<CommandResult> {
+    return this.commandBus.execute(
+      new AttachFileCommand(actorId, issueId, file, commentId),
+    );
+  }
+
+  detach(
+    actorId: string,
+    issueId: string,
+    attachmentId: string,
+  ): Promise<CommandResult> {
+    return this.commandBus.execute(
+      new DetachFileCommand(actorId, issueId, attachmentId),
+    );
+  }
+
+  /** A ticket's file, with its bytes, for whoever can read the ticket. */
+  download(
+    viewerId: string | null,
+    issueId: string,
+    attachmentId: string,
+  ): Promise<AttachmentDownload> {
+    return this.queryBus.execute(
+      new GetAttachmentQuery(viewerId, issueId, attachmentId),
+    );
+  }
+
   findOne(viewerId: string | null, idOrKey: string): Promise<IssueReadModel> {
     return this.queryBus.execute(new GetIssueQuery(viewerId, idOrKey));
   }

libs/api/tracker/application/src/lib/ports/attachment-storage.ts

@@ -0,0 +1,24 @@
+import type { Readable } from 'node:stream';
+
+/** Where the bytes of attached files live (the tickets only record them). */
+export abstract class AttachmentStorage {
+  abstract put(key: string, content: Buffer): Promise<void>;
+  /** Fails with NotFoundError when there is nothing at `key`. */
+  abstract read(key: string): Promise<Readable>;
+  /** Idempotent: removing what is not there is fine. */
+  abstract remove(key: string): Promise<void>;
+  /** Everything under `prefix` (a ticket's files, when it is deleted). */
+  abstract removePrefix(prefix: string): Promise<void>;
+}
+
+/** One folder per project and ticket, so a ticket's files go together. */
+export const attachmentKey = (
+  projectId: string,
+  issueId: string,
+  attachmentId: string,
+): string => `${projectId}/${issueId}/${attachmentId}`;
+
+export const issueAttachmentsPrefix = (
+  projectId: string,
+  issueId: string,
+): string => `${projectId}/${issueId}/`;

libs/api/tracker/application/src/lib/ports/index.ts

@@ -17,3 +17,4 @@ export * from './release-issues.repository';
 export * from './upsert-materialized-timeline.repository';
 export * from './find-timeline.repository';
 export * from './tracker-streams.repository';
+export * from './attachment-storage';

libs/api/tracker/application/src/lib/ports/upsert-materialized-issue.repository.ts

@@ -1,4 +1,5 @@
 import {
+  AttachmentReadModel,
   IssueLinkReadModel,
   IssueReadModel,
   StatusCategory,
@@ -8,7 +9,7 @@ export abstract class UpsertMaterializedIssueRepository {
   /** Applied only if `version` is newer than the stored one (idempotent). */
   abstract upsert(
     issue: Pick<IssueReadModel, 'id' | 'version'> &
-      Partial<Omit<IssueReadModel, 'links' | 'commentCount'>>,
+      Partial<Omit<IssueReadModel, 'links' | 'commentCount' | 'attachments'>>,
   ): Promise<void>;
   /** Adds a relation to an issue (idempotent). */
   abstract addLink(issueId: string, link: IssueLinkReadModel): Promise<void>;
@@ -16,6 +17,15 @@ export abstract class UpsertMaterializedIssueRepository {
     issueId: string,
     link: Omit<IssueLinkReadModel, 'issueKey'>,
   ): Promise<void>;
+  /** Adds a file to an issue (idempotent). */
+  abstract addAttachment(
+    issueId: string,
+    attachment: AttachmentReadModel,
+  ): Promise<void>;
+  abstract removeAttachment(
+    issueId: string,
+    attachmentId: string,
+  ): Promise<void>;
   abstract setCommentCount(
     issueId: string,
     commentCount: number,

libs/api/tracker/application/src/lib/queries/get-attachment.query-handler.ts

@@ -0,0 +1,39 @@
+import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
+import { NotFoundError } from '@task-stream/api/shared/domain';
+import { AttachmentStorage, attachmentKey } from '../ports/attachment-storage';
+import { FindIssuesRepository } from '../ports/find-issues.repository';
+import { AttachmentDownload, GetAttachmentQuery } from './get-attachment.query';
+import { ReadAccess } from './read-access';
+
+@QueryHandler(GetAttachmentQuery)
+export class GetAttachmentQueryHandler
+  implements IQueryHandler<GetAttachmentQuery, AttachmentDownload>
+{
+  constructor(
+    private readonly findIssues: FindIssuesRepository,
+    private readonly storage: AttachmentStorage,
+    private readonly access: ReadAccess,
+  ) {}
+
+  async execute(query: GetAttachmentQuery): Promise<AttachmentDownload> {
+    const issue = this.access.assertFound(
+      await this.findIssues.findById(query.issueId),
+      'Attachment',
+      query.attachmentId,
+    );
+    await this.access.assertCanView(issue.projectId, query.viewerId, {
+      entity: 'Attachment',
+      ref: query.attachmentId,
+    });
+    const attachment = (issue.attachments ?? []).find(
+      (a) => a.id === query.attachmentId,
+    );
+    if (!attachment) throw new NotFoundError('Attachment', query.attachmentId);
+    return {
+      attachment,
+      content: await this.storage.read(
+        attachmentKey(issue.projectId, issue.id, attachment.id),
+      ),
+    };
+  }
+}

libs/api/tracker/application/src/lib/queries/get-attachment.query.ts

@@ -0,0 +1,20 @@
+import { Query } from '@nestjs/cqrs';
+import { AttachmentReadModel } from '@task-stream/api/tracker/domain';
+import type { Readable } from 'node:stream';
+
+export interface AttachmentDownload {
+  attachment: AttachmentReadModel;
+  content: Readable;
+}
+
+/** A ticket's file, for whoever can read the ticket. */
+export class GetAttachmentQuery extends Query<AttachmentDownload> {
+  constructor(
+    /** Null: anonymous (public projects only). */
+    public readonly viewerId: string | null,
+    public readonly issueId: string,
+    public readonly attachmentId: string,
+  ) {
+    super();
+  }
+}

libs/api/tracker/application/src/lib/queries/index.ts

@@ -16,3 +16,4 @@ export * from './get-upcoming-releases.query';
 export * from './search-issues.query';
 export * from './search-my-issues.query';
 export * from './get-public-projects.query';
+export * from './get-attachment.query';

libs/api/tracker/application/src/lib/queries/query-handlers.ts

@@ -1,3 +1,4 @@
+import { GetAttachmentQueryHandler } from './get-attachment.query-handler';
 import { GetPublicProjectsQueryHandler } from './get-public-projects.query-handler';
 import { CanViewProjectQueryHandler } from './can-view-project.query-handler';
 import { GetActivityQueryHandler } from './get-activity.query-handler';
@@ -36,4 +37,5 @@ export const QUERY_HANDLERS = [
   GetUpcomingReleasesQueryHandler,
   SearchIssuesQueryHandler,
   SearchMyIssuesQueryHandler,
+  GetAttachmentQueryHandler,
 ];

libs/api/tracker/application/src/lib/sagas/sagas.spec.ts

@@ -23,6 +23,7 @@ import {
 import { lastValueFrom, of, toArray } from 'rxjs';
 import {
   FakeUserDirectory,
+  InMemoryAttachmentStorage,
   InMemoryEventStore,
   InMemoryEventStorePublisher,
   InMemoryIssueNumbers,
@@ -51,12 +52,14 @@ import { ReleaseIssuesRepository } from '../ports/release-issues.repository';
 import { ReleaseNamesRepository } from '../ports/release-names.repository';
 import { TrackerStreamsRepository } from '../ports/tracker-streams.repository';
 import { UserDirectory } from '../ports/user-directory';
+import { AttachmentStorage } from '../ports/attachment-storage';
 import { ProjectDeletionSaga } from './project-deletion.saga';
 import { ReleaseArchivedSaga } from './release-archived.saga';
 import { UserDeactivatedSaga } from './user-deactivated.saga';
 
 async function setup() {
   const store = new InMemoryEventStore();
+  const files = new InMemoryAttachmentStorage();
   const users = new FakeUserDirectory().add('owner').add('dev').add('qa');
   // Read model double for the user saga: open tickets are tracked by the test.
   const openAssigned = new Map<string, string[]>();
@@ -71,6 +74,7 @@ async function setup() {
       WriteAccess,
       AggregateRehydrator,
       { provide: EventStore, useValue: store },
+      { provide: AttachmentStorage, useValue: files },
       { provide: UserDirectory, useValue: users },
       { provide: ProjectKeysRepository, useClass: InMemoryProjectKeys },
       { provide: IssueNumbersRepository, useClass: InMemoryIssueNumbers },