Загрузка файлов: поток мимо памяти, лимиты, чужое имя файла

// Сборка тела — на подложке: её читатель собирал руками в части V
declare const BOUNDARY: string;
declare function buildMultipart(parts: { name: string; filename?: string; type?: string; value: string | Uint8Array }[]): Uint8Array;
declare function photoBytes(size: number): Uint8Array;
declare function chunksOf(bytes: Uint8Array, size: number): Uint8Array[];

type PartHeaders = { name: string; filename?: string; type?: string };

// Пустая строка между заголовками части и её содержимым
const BLANK = new TextEncoder().encode("\r\n\r\n");

// Поиск подстроки в байтах: у Uint8Array нет ни indexOf для массива, ни includes
function indexOfBytes(haystack: Uint8Array, needle: Uint8Array, from: number): number {
  outer: for (let i = from; i + needle.length <= haystack.length; i += 1) {
    for (let j = 0; j < needle.length; j += 1) if (haystack[i + j] !== needle[j]) continue outer;
    return i;
  }
  return -1;
}

// Заголовки части: имя поля, имя файла и тип содержимого
function partHeaders(text: string): PartHeaders {
  const headers: Record<string, string> = Object.create(null);
  for (const line of text.split("\r\n")) {
    const colon = line.indexOf(":");
    headers[line.slice(0, colon).toLowerCase()] = line.slice(colon + 1).trim();
  }
  const disposition = headers["content-disposition"] ?? "";
  // name= ищется от начала или после точки с запятой: иначе он нашёлся бы внутри filename=
  const name = disposition.match(/(?:^|;\s*)name="([^"]*)"/);
  const filename = disposition.match(/;\s*filename="([^"]*)"/);
  return { name: name ? name[1] : "", filename: filename ? filename[1] : undefined, type: headers["content-type"] };
}

interface Sink {
  start(headers: PartHeaders): void;
  data(chunk: Uint8Array): void;
  end(): void;
}

class MultipartParser {
  // наибольший буфер за разбор: сколько байт тела разборщик держал в памяти
  peak = 0;
  #delimiter: Uint8Array;
  #buffer: Uint8Array;
  #state: "delimiter" | "headers" | "body" | "done" = "delimiter";
  #sink: Sink;

  constructor(boundary: string, sink: Sink) {
    const enc = new TextEncoder();
    this.#delimiter = enc.encode("\r\n--" + boundary);
    // перед первой границей CRLF нет — поэтому буфер начинается с него
    this.#buffer = enc.encode("\r\n");
    this.#sink = sink;
  }

  push(chunk: Uint8Array): void {
    const next = new Uint8Array(this.#buffer.length + chunk.length);
    next.set(this.#buffer);
    next.set(chunk, this.#buffer.length);
    this.#buffer = next;
    this.peak = Math.max(this.peak, next.length);
    this.#parse();
  }

  #parse(): void {
    for (;;) {
      if (this.#state === "done") return;
      if (this.#state === "delimiter") {
        const at = indexOfBytes(this.#buffer, this.#delimiter, 0);
        if (at === -1) return;
        this.#buffer = this.#buffer.slice(at + this.#delimiter.length);
        this.#state = "headers";
        continue;
      }
      if (this.#state === "headers") {
        // после границы либо «--» и конец тела, либо CRLF и заголовки части
        if (this.#buffer.length < 2) return;
        if (this.#buffer[0] === 45 && this.#buffer[1] === 45) {
          this.#state = "done";
          return;
        }
        const blank = indexOfBytes(this.#buffer, BLANK, 0);
        if (blank === -1) return;
        this.#sink.start(partHeaders(new TextDecoder().decode(this.#buffer.subarray(2, blank))));
        this.#buffer = this.#buffer.slice(blank + 4);
        this.#state = "body";
        continue;
      }
      const at = indexOfBytes(this.#buffer, this.#delimiter, 0);
      if (at === -1) {
        // в хвосте длиной в разделитель без одного байта граница может только
        // начинаться — его придерживаем, остальное отдаём приёмнику
        const keep = this.#delimiter.length - 1;
        if (this.#buffer.length > keep) {
          this.#sink.data(this.#buffer.subarray(0, this.#buffer.length - keep));
          this.#buffer = this.#buffer.slice(this.#buffer.length - keep);
        }
        return;
      }
      this.#sink.data(this.#buffer.subarray(0, at));
      this.#sink.end();
      this.#buffer = this.#buffer.slice(at + this.#delimiter.length);
      this.#state = "headers";
    }
  }
}

// Прибор: каждую часть разборщик объявляет, а её содержимое выдаёт кусками
type Seen = { headers: PartHeaders; bytes: number; chunks: number };
const seen: Seen[] = [];
const sink: Sink = {
  start(headers) {
    seen.push({ headers, bytes: 0, chunks: 0 });
  },
  data(chunk) {
    const part = seen[seen.length - 1];
    part.bytes += chunk.length;
    part.chunks += 1;
  },
  end() {},
};

// тело телефона: сначала поле photoId, потом файл под именем от пикера
const snapshot = photoBytes(3000);
const body = buildMultipart([
  { name: "photoId", value: "A-2" },
  { name: "file", filename: "../../etc/passwd", type: "image/jpeg", value: snapshot },
]);

const parser = new MultipartParser(BOUNDARY, sink);
for (const chunk of chunksOf(body, 64)) parser.push(chunk);

console.log("байтов в теле:", body.length, "· из них снимка:", snapshot.length);
for (const part of seen) {
  const what = part.headers.filename === undefined ? "поле" : 'файл ' + JSON.stringify(part.headers.filename) + ", " + part.headers.type;
  console.log("часть " + part.headers.name + ":", what, "· байтов", part.bytes, "· кусков", part.chunks);
}
console.log("наибольший буфер разборщика:", parser.peak, "Б");

// Сборка тела и разборщик границ — на подложке (разобраны выше)
declare const BOUNDARY: string;
declare function buildMultipart(parts: { name: string; filename?: string; type?: string; value: string | Uint8Array }[]): Uint8Array;
declare function photoBytes(size: number): Uint8Array;
declare function chunksOf(bytes: Uint8Array, size: number): Uint8Array[];
type PartHeaders = { name: string; filename?: string; type?: string };
interface Sink {
  start(headers: PartHeaders): void;
  data(chunk: Uint8Array): void;
  end(): void;
}
declare class MultipartParser {
  constructor(boundary: string, sink: Sink);
  push(chunk: Uint8Array): void;
}

type Handle = { write(chunk: Uint8Array): void; close(): void };

// Диск: файл открывают, пишут кусками и закрывают — как createWriteStream
class Disk {
  #files = new Map<string, number>();

  open(path: string): Handle {
    this.#files.set(path, 0);
    return {
      write: (chunk) => this.#files.set(path, this.#files.get(path)! + chunk.length),
      close: () => {},
    };
  }

  remove(path: string): boolean {
    return this.#files.delete(path);
  }

  list(): string {
    return this.#files.size === 0 ? "(пусто)" : [...this.#files].map(([path, size]) => path + " " + size + " Б").join(", ");
  }
}

// Приёмник тела: поля собирает строками, файл пишет на диск куском за куском
class UploadSink implements Sink {
  fields: Record<string, string> = {};
  path = "";
  size = 0;
  truncated = false;
  #file: Handle | null = null;
  #part: PartHeaders = { name: "" };
  #decoder = new TextDecoder();
  #value = "";
  #disk: Disk;
  #limit: number;
  #pathOf: (fields: Record<string, string>, headers: PartHeaders) => string;

  constructor(disk: Disk, limit: number, pathOf: (fields: Record<string, string>, headers: PartHeaders) => string) {
    this.#disk = disk;
    this.#limit = limit;
    this.#pathOf = pathOf;
  }

  start(headers: PartHeaders): void {
    this.#part = headers;
    // один декодер на всю часть: хвост разрезанной буквы он придержит (глава 4)
    this.#decoder = new TextDecoder();
    this.#value = "";
    // путь считают ПОЛЯ, а они приезжают раньше файла: имя файла в нём не участвует
    if (headers.filename !== undefined) {
      this.path = this.#pathOf(this.fields, headers);
      this.#file = this.#disk.open(this.path);
    }
  }

  data(chunk: Uint8Array): void {
    if (this.#part.filename === undefined) {
      this.#value += this.#decoder.decode(chunk, { stream: true });
      return;
    }
    if (this.truncated) return;
    // предел считается в байтах и ДО записи: иначе он считался бы после неё
    if (this.size + chunk.length > this.#limit) {
      this.#file!.write(chunk.subarray(0, this.#limit - this.size));
      this.size = this.#limit;
      this.truncated = true;
      return;
    }
    this.#file!.write(chunk);
    this.size += chunk.length;
  }

  end(): void {
    if (this.#part.filename === undefined) {
      this.fields[this.#part.name] = this.#value + this.#decoder.decode();
      return;
    }
    this.#file!.close();
    this.#file = null;
  }
}

const LIMIT = 1024;
const EXT: Record<string, string> = { "image/jpeg": "jpg", "image/png": "png" };
// расширение — из типа части, а не из имени файла: имя пришло от клиента
const pathOf = (fields: Record<string, string>, headers: PartHeaders): string => fields.photoId + "." + (EXT[headers.type ?? ""] ?? "bin");

type Answer = { status: number; body: string };

function receive(body: Uint8Array): { sink: UploadSink; disk: Disk } {
  const disk = new Disk();
  const sink = new UploadSink(disk, LIMIT, pathOf);
  const parser = new MultipartParser(BOUNDARY, sink);
  for (const chunk of chunksOf(body, 64)) parser.push(chunk);
  return { sink, disk };
}

// Наивная ручка: дождалась конца тела и ответила адресом
function naive(body: Uint8Array): [Answer, Disk] {
  const { sink, disk } = receive(body);
  return [{ status: 200, body: JSON.stringify({ url: "/photos/" + sink.path }) }, disk];
}

// Осторожная: сначала спрашивает приёмник, весь ли файл тот принял
function careful(body: Uint8Array): [Answer, Disk] {
  const { sink, disk } = receive(body);
  if (sink.truncated) {
    disk.remove(sink.path);
    return [{ status: 413, body: JSON.stringify({ code: "FILE_TOO_LARGE", limit: LIMIT }) }, disk];
  }
  return [{ status: 200, body: JSON.stringify({ url: "/photos/" + sink.path }) }, disk];
}

const bodyOf = (size: number): Uint8Array =>
  buildMultipart([
    { name: "photoId", value: "A-2" },
    { name: "file", filename: "снимок.jpg", type: "image/jpeg", value: photoBytes(size) },
  ]);

const show = (label: string, [answer, disk]: [Answer, Disk]): void => {
  console.log(label, answer.status, answer.body);
  console.log("  на диске:", disk.list());
};

console.log("предел", LIMIT, "Б; снимок 4096 Б");
show("наивная ручка:", naive(bodyOf(4096)));
show("осторожная ручка:", careful(bodyOf(4096)));
console.log("предел", LIMIT, "Б; снимок 900 Б");
show("осторожная ручка:", careful(bodyOf(900)));

// apps/api/src/upload/upload.controller.ts автора, сокращено до приёма файла
@Post('photo')
@HttpCode(200)
async uploadPhoto(@Req() request: FastifyRequest): Promise<StoredFile> {
  let file: Awaited<ReturnType<FastifyRequest['file']>> | undefined;
  try {
    file = request.isMultipart() ? await request.file() : undefined;
  } catch {
    file = undefined;
  }
  if (!file) throw new BadRequestException('NO_FILE');
  if (!isAllowedImageMime(file.mimetype)) throw new BadRequestException('BAD_MIME');

  let buffer: Buffer;
  try {
    buffer = await file.toBuffer();
  } catch {
    // единственный способ узнать о превышении лимита @fastify/multipart
    // (5 МБ, main.ts): он обрывает поток именно здесь
    throw new PayloadTooLargeException('FILE_TOO_LARGE');
  }
  return this.storage.save(buffer, file.mimetype);
}

// Разборщик, диск и приёмник тела — на подложке; таблица с индексами — тоже
declare const BOUNDARY: string;
declare function buildMultipart(parts: { name: string; filename?: string; type?: string; value: string | Uint8Array }[]): Uint8Array;
declare function photoBytes(size: number): Uint8Array;
declare function chunksOf(bytes: Uint8Array, size: number): Uint8Array[];
type PartHeaders = { name: string; filename?: string; type?: string };
interface Sink {
  start(headers: PartHeaders): void;
  data(chunk: Uint8Array): void;
  end(): void;
}
declare class MultipartParser {
  constructor(boundary: string, sink: Sink);
  push(chunk: Uint8Array): void;
}
declare class Disk {
  remove(path: string): boolean;
  list(): string;
}
declare class UploadSink implements Sink {
  constructor(disk: Disk, limit: number, pathOf: (fields: Record<string, string>, headers: PartHeaders) => string);
  fields: Record<string, string>;
  path: string;
  size: number;
  truncated: boolean;
  start(headers: PartHeaders): void;
  data(chunk: Uint8Array): void;
  end(): void;
}
type Row = Record<string, unknown> & { id: number };
declare class DbError extends Error {
  code: string;
  constraint: string;
}
declare class Table {
  index(name: string, column: string, options?: { unique?: boolean }): Table;
  insert(values: Record<string, unknown>): Row;
  update(id: number, patch: Record<string, unknown>): Row | null;
  find(indexName: string, value: unknown): Row[];
  where(match: (row: Row) => boolean): Row[];
}

type Answer = { status: number; body: string };
const LIMIT = 8192;

// Сервер загрузки. Отличается он единственным: чем отпирает строку фото и как
// зовёт файл на диске
function createServer(keyOf: (userId: string, photoId: string) => string) {
  const photos = new Table().index("photos_pkey", "key", { unique: true });
  const disk = new Disk();

  const save = (userId: string, photoId: string, size: number, path: string): void => {
    try {
      photos.insert({ key: keyOf(userId, photoId), userId, photoId, size, path });
    } catch (error) {
      if (!(error instanceof DbError) || error.code !== "23505") throw error;
      // повтор загрузки — не новая строка: телефон прислал тот же photoId
      const saved = photos.find("photos_pkey", keyOf(userId, photoId))[0];
      photos.update(saved.id, { size, path });
    }
  };

  return {
    upload(userId: string, body: Uint8Array): Answer {
      // путь на диске зовётся тем же ключом, что строка: иначе файл перепишут
      // и при целой строке
      const sink = new UploadSink(disk, LIMIT, (fields) => keyOf(userId, fields.photoId) + ".jpg");
      const parser = new MultipartParser(BOUNDARY, sink);
      for (const chunk of chunksOf(body, 256)) parser.push(chunk);
      if (sink.truncated) {
        disk.remove(sink.path);
        return { status: 413, body: JSON.stringify({ code: "FILE_TOO_LARGE" }) };
      }
      save(userId, sink.fields.photoId, sink.size, sink.path);
      return { status: 200, body: JSON.stringify({ url: "/photos/" + sink.path }) };
    },
    show(userId: string, photoId: string): string {
      const found = photos.find("photos_pkey", keyOf(userId, photoId))[0];
      // чужое отвечает как несуществующее: 404, а не 403
      return found === undefined ? "404" : "200 " + found.path + " " + found.size + " Б · строка за " + found.userId;
    },
    disk,
  };
}

const bodyOf = (photoId: string, size: number): Uint8Array =>
  buildMultipart([
    { name: "photoId", value: photoId },
    { name: "file", filename: "снимок.jpg", type: "image/jpeg", value: photoBytes(size) },
  ]);

const KEYS: [string, (userId: string, photoId: string) => string][] = [
  ["ключ — один photo_id:", (userId, photoId) => photoId],
  ["ключ — пара (user_id, photo_id):", (userId, photoId) => userId + "/" + photoId],
];

for (const [label, keyOf] of KEYS) {
  const server = createServer(keyOf);
  console.log(label);
  console.log("  Аня грузит A-2 (3000 Б):", server.upload("аня", bodyOf("A-2", 3000)).body);
  console.log("  Боря грузит A-2 (700 Б):", server.upload("боря", bodyOf("A-2", 700)).body);
  console.log("  Аня просит A-2:", server.show("аня", "A-2"));
  console.log("  Боря просит A-2:", server.show("боря", "A-2"));
  console.log("  на диске:", server.disk.list());
}

// apps/api/src/upload/file-storage.ts автора, сокращено

/** Абстракция хранилища: в dev — локальная папка, в проде подменяется
 * S3-реализацией без изменения контроллера. */
export interface FileStorage {
  save(buffer: Buffer, mimetype: string): Promise<StoredFile>;
}

export const FILE_STORAGE = Symbol('FileStorage');

/** Расширение берём из MIME, а не из имени файла: имя приходит от клиента,
 * и «avatar.jpg.exe» сохранился бы как есть. Заодно это белый список типов. */
const EXT_BY_MIME: Record<string, string> = {
  'image/jpeg': 'jpg',
  'image/png': 'png',
  'image/webp': 'webp',
};

@Injectable()
export class LocalFileStorage implements FileStorage {
  private readonly dir = join(process.cwd(), 'uploads');

  async save(buffer: Buffer, mimetype: string): Promise<StoredFile> {
    await mkdir(this.dir, { recursive: true });
    const name = `${randomUUID()}.${EXT_BY_MIME[mimetype] ?? 'bin'}`;
    await writeFile(join(this.dir, name), buffer);
    return { url: `/uploads/${name}` };
  }
}

// apps/api/src/upload/upload.module.ts автора, провайдер хранилища
{
  provide: FILE_STORAGE,
  inject: [ConfigService],
  // дефолт — local, чтобы dev работал без S3-хранилища; в проде STORAGE_DRIVER=s3
  useFactory: (config: ConfigService): FileStorage =>
    config.get<string>('STORAGE_DRIVER') === 's3'
      ? new S3FileStorage(config)
      : new LocalFileStorage(),
}