@hed-hog/core 0.0.390 → 0.0.394

package/src/file/file.service.ts

@@ -31,9 +31,12 @@ import {
   OnModuleInit
 } from '@nestjs/common';
 import { JwtService } from '@nestjs/jwt';
+import type { Request } from 'express';
 import { createWriteStream, promises as fs } from 'fs';
-import { basename, dirname, extname } from 'path';
+import { tmpdir } from 'os';
+import { basename, dirname, extname, join } from 'path';
 import { pipeline } from 'stream/promises';
+import { v4 } from 'uuid';
 import {
   buildStorageConfigFromIntegration,
   resolveFileProviderSlug,
@@ -41,8 +44,14 @@ import {
 } from '../integration-profile/integration-profile.utils';
 import { SettingService } from '../setting/setting.service';
 import { DeleteDTO } from './dto/delete.dto';
-import { ImageOptimizationService } from './image-optimization.service';
-import { AbstractProvider } from './provider/abstract.provider';
+import {
+  ImageOptimizationService,
+  ImageVariantFormat,
+} from './image-optimization.service';
+import {
+  AbstractProvider,
+  supportsServerSideCopy,
+} from './provider/abstract.provider';
 import { ProviderFactory } from './provider/provider.factory';
 
 type ResolvedProvider = {
@@ -63,6 +72,13 @@ const PROVIDER_CACHE_TTL_MS = Math.max(
   Number(process.env.FILE_PROVIDER_CACHE_TTL_MS ?? 30_000),
 );
 
+/** Raw `?w=`/`?f=`/`?q=` query values for the public image endpoint. */
+export type ImageVariantRequest = {
+  width?: number | string;
+  format?: string;
+  quality?: number | string;
+};
+
 @Injectable()
 export class FileService implements OnModuleInit {
   private readonly logger = new Logger(FileService.name);
@@ -467,6 +483,50 @@ export class FileService implements OnModuleInit {
     };
   }
 
+  /**
+   * Renderiza um cartão social 1200x630 (JPEG) a partir de arquivos do acervo.
+   *
+   * Devolve `null` quando não há arquivo utilizável — quem chama deve responder
+   * 404 e deixar o consumidor cair na imagem padrão da marca, nunca 500: do
+   * outro lado costuma haver um robô de link preview.
+   */
+  async renderShareCard(options: {
+    backgroundFileId?: number | null;
+    overlayFileId?: number | null;
+    background?: string | null;
+  }): Promise<{ buffer: Buffer; contentType: string } | null> {
+    const load = async (fileId?: number | null): Promise<Buffer | null> => {
+      if (!fileId) return null;
+      try {
+        const { buffer } = await this.getBuffer(fileId);
+        return buffer;
+      } catch {
+        return null;
+      }
+    };
+
+    const [background, overlay] = await Promise.all([
+      load(options.backgroundFileId),
+      load(options.overlayFileId),
+    ]);
+
+    if (!background && !overlay) {
+      return null;
+    }
+
+    const buffer = await this.imageOptimizationService.composeShareCard(
+      background,
+      overlay,
+      { background: options.background },
+    );
+
+    if (!buffer) {
+      return null;
+    }
+
+    return { buffer, contentType: 'image/jpeg' };
+  }
+
   async getLocalFile(fileId: number, res: any){
     const { buffer, file } = await this.getBuffer(fileId);
     res.set({
@@ -483,7 +543,12 @@ export class FileService implements OnModuleInit {
     // Escape hatch para chamadores INTERNOS que já validaram por conta própria —
     // o mesmo par de flags que `uploadFromPath` sempre teve. O FileController não
     // repassa este argumento, então não há como acioná-lo por HTTP.
-    options?: { skipMimeValidation?: boolean; skipSizeValidation?: boolean },
+    // `isPrivate` tira o arquivo das rotas que servem por id sem autenticação.
+    options?: {
+      skipMimeValidation?: boolean;
+      skipSizeValidation?: boolean;
+      isPrivate?: boolean;
+    },
   ) {
 
     if (!fileBuffer) {
@@ -544,6 +609,7 @@ export class FileService implements OnModuleInit {
         location: destination,
         mimetype_id: await this.getMimeType(optimized.mimetype),
         size: optimized.buffer.length,
+        is_private: options?.isPrivate ?? false,
       },
     });
 
@@ -561,6 +627,10 @@ export class FileService implements OnModuleInit {
       encoding?: string;
       skipMimeValidation?: boolean;
       skipSizeValidation?: boolean;
+      // Tira o arquivo das rotas que servem por id sem autenticação.
+      isPrivate?: boolean;
+      // Mesmo par maxWidth/maxHeight que `upload` aceita — só tem efeito em image/*.
+      resize?: { maxWidth?: number; maxHeight?: number };
     },
   ) {
     if (!filePath) {
@@ -616,6 +686,7 @@ export class FileService implements OnModuleInit {
           location: destination,
           mimetype_id: await this.getMimeType(mimetype),
           size,
+          is_private: metadata?.isPrivate ?? false,
         },
       });
     }
@@ -626,6 +697,10 @@ export class FileService implements OnModuleInit {
       rawBuffer,
       mimetype,
       originalname,
+      {
+        maxWidth: metadata?.resize?.maxWidth,
+        maxHeight: metadata?.resize?.maxHeight,
+      },
     );
 
     const url = await provider.upload(destination, {
@@ -648,6 +723,7 @@ export class FileService implements OnModuleInit {
         location: destination,
         mimetype_id: await this.getMimeType(optimized.mimetype),
         size: optimized.buffer.length,
+        is_private: metadata?.isPrivate ?? false,
       },
     });
 
@@ -804,10 +880,125 @@ export class FileService implements OnModuleInit {
     return file;
   }
 
+  /**
+   * Creates an independent copy of a stored file: new bytes in storage + a new `file` row.
+   *
+   * Unlike sharing a `file_id`, the result survives the original being deleted — which is what
+   * "duplicate files" means when copying course content between courses.
+   *
+   * `filename` and `destination` default to the source's, so a caller that only wants
+   * independent bytes gets them without thinking about paths. Passing `destination` matters for
+   * artifacts addressed by their location (HLS manifests and segments).
+   *
+   * The bytes are copied server-side when the active provider supports it; otherwise — and when
+   * the provider-side copy fails, e.g. an object above S3's 5GB CopyObject cap — they are
+   * streamed through a temp file, never buffered in RAM. Mime/size validation is skipped: the
+   * source already passed it at upload time.
+   */
+  async duplicate(
+    fileId: number,
+    options?: { destination?: string; filename?: string },
+  ) {
+    const source = await this.prismaService.file.findUnique({
+      where: { id: fileId },
+      include: { file_mimetype: true },
+    });
+
+    if (!source) {
+      throw new NotFoundException(`File not found: ${fileId}`);
+    }
+
+    const destination = options?.destination ?? source.location;
+    const filename = options?.filename ?? source.filename;
+    const sourcePath = this.resolveProviderPath(source);
+    const provider = await this.getProvider();
+
+    let storedFilename: string | null = null;
+
+    if (supportsServerSideCopy(provider)) {
+      try {
+        storedFilename = await provider.copy(sourcePath, destination, filename);
+      } catch (error) {
+        this.logger.warn(
+          `Server-side copy failed for file ${fileId}, falling back to streaming: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+
+    if (storedFilename === null) {
+      const tempPath = join(tmpdir(), `hedhog-file-copy-${v4()}`);
+      try {
+        await this.downloadToPath(fileId, tempPath);
+        storedFilename = await provider.uploadFromPath(destination, tempPath, {
+          filename,
+          mimetype: source.file_mimetype?.name,
+        });
+      } finally {
+        await fs.unlink(tempPath).catch(() => undefined);
+      }
+    }
+
+    return this.prismaService.file.create({
+      data: {
+        filename,
+        path: storedFilename,
+        provider_id: this.providerId,
+        location: destination,
+        mimetype_id: source.mimetype_id,
+        size: source.size ?? 0,
+      },
+    });
+  }
+
   async readStream(filepath: string) {
     return (await this.getProvider()).readStream(filepath);
   }
 
+  /**
+   * Confere se os bytes de um `file` estão mesmo no storage, devolvendo o tamanho
+   * relatado pelo provider ao lado do tamanho declarado no banco.
+   *
+   * Existe para quem precisa **provar** que a cópia sobreviveu antes de apagar o
+   * original em outro lugar: o registro em banco sozinho não é prova, porque é
+   * gravado depois do upload e nada reconcilia os dois se o insert falhar no meio
+   * — o blob fica órfão ou a linha aponta para o vazio, e ninguém percebe até
+   * alguém tentar ler.
+   *
+   * Não lança quando o objeto está ausente: devolve `storedSize: null`, para o
+   * chamador decidir o que fazer com a divergência.
+   */
+  async statStoredFile(
+    fileId: number,
+  ): Promise<{ storedSize: number | null; declaredSize: number }> {
+    if (!fileId) {
+      throw new BadRequestException(`No file ID provided`);
+    }
+
+    const file = await this.prismaService.file.findUnique({
+      where: { id: fileId },
+    });
+
+    if (!file) {
+      throw new NotFoundException(`File not found: ${fileId}`);
+    }
+
+    const provider = await this.getProvider();
+
+    try {
+      const metadata = await provider.metaData(this.resolveProviderPath(file));
+      return {
+        storedSize: this.getFileSizeFromMetadata(metadata) ?? null,
+        declaredSize: Number(file.size ?? 0),
+      };
+    } catch {
+      // Qualquer falha de leitura de metadado — ausente, sem permissão, provider
+      // fora do ar — é tratada como "não deu para provar", nunca como sucesso.
+      return { storedSize: null, declaredSize: Number(file.size ?? 0) };
+    }
+  }
+
   private getFileSizeFromMetadata(metadata: any): number | undefined {
     if (!metadata) {
       return undefined;
@@ -910,13 +1101,25 @@ export class FileService implements OnModuleInit {
    * Resolves the file record and its storage metadata (mimetype + size) without
    * opening a read stream — so callers can answer a conditional 304 cheaply.
    */
+  /**
+   * Metadados para servir um arquivo POR ID.
+   *
+   * Só os dois handlers anônimos passam por aqui (`serveFileById` e
+   * `serveImageById`), e é por isso que a checagem de `is_private` mora neste
+   * ponto e não em cada um: id de arquivo é sequencial, então servir por id é uma
+   * porta enumerável. O caminho por token (`download`) não passa por aqui, então
+   * um arquivo privado continua acessível ao admin via
+   * `PUT /file/open/:id` -> token -> `GET /file/open/:token`.
+   */
   private async resolveFileMeta(locale: string, id: number) {
     const file = await this.prismaService.file.findFirst({
       where: { id },
       include: { file_mimetype: true },
     });
 
-    if (!file) {
+    // Privado responde igual a inexistente: confirmar que o id existe já
+    // entregaria metade do que a enumeração procura.
+    if (!file || file.is_private) {
       throw new NotFoundException(
         getLocaleText('file.download.not_found', locale, `Not found: ${id}`),
       );
@@ -1010,16 +1213,82 @@ export class FileService implements OnModuleInit {
     return mimetype ?? 'application/octet-stream';
   }
 
+  /**
+   * Widths this endpoint is willing to render. An allowlist is required, not a
+   * range check: the endpoint is `@Public()`, and an arbitrary width means
+   * arbitrary CPU and an unbounded number of cache entries per file.
+   */
+  private async getAllowedImageWidths(): Promise<number[]> {
+    const DEFAULT_WIDTHS = [64, 128, 320, 400, 480, 640, 896, 1200];
+    const settings = await this.settingService.getSettingValues(
+      'image-resize-allowed-widths',
+    );
+    try {
+      const parsed = JSON.parse(settings['image-resize-allowed-widths'] ?? '');
+      const widths = (Array.isArray(parsed) ? parsed : [])
+        .map((w: unknown) => Math.round(Number(w)))
+        .filter((w: number) => Number.isFinite(w) && w > 0);
+      return widths.length ? widths : DEFAULT_WIDTHS;
+    } catch {
+      return DEFAULT_WIDTHS;
+    }
+  }
+
+  /**
+   * Resolves the requested variant against the allowlist. Anything unknown or
+   * out of the list collapses to "no variant", which serves the original bytes
+   * instead of failing — a stale `?w=` in cached HTML must not 500.
+   */
+  private async resolveImageVariant(variant?: ImageVariantRequest) {
+    const width = Math.round(Number(variant?.width) || 0);
+    if (width <= 0) return null;
+
+    const allowed = await this.getAllowedImageWidths();
+    if (!allowed.includes(width)) return null;
+
+    const format = ['webp', 'jpeg', 'png', 'avif'].includes(
+      String(variant?.format),
+    )
+      ? (String(variant?.format) as ImageVariantFormat)
+      : undefined;
+
+    const rawQuality = Math.round(Number(variant?.quality) || 0);
+    const quality =
+      rawQuality >= 50 && rawQuality <= 95 ? rawQuality : 80;
+
+    return { width, format, quality };
+  }
+
+  /** Absolute path of the on-disk cache entry for a rendered variant. */
+  private imageVariantCachePath(
+    id: number,
+    size: number | undefined,
+    width: number,
+    format: string,
+    quality: number,
+  ) {
+    return join(
+      tmpdir(),
+      'hedhog-image-variants',
+      `${id}-${size ?? 0}-w${width}-${format}-q${quality}`,
+    );
+  }
+
   /**
    * Serves an image by id with strong, immutable HTTP caching. The content of a
    * given fileId never changes (a new upload yields a new id), so the ETag is
    * derived from id+size instead of hashing the buffer, keeping it streaming.
+   *
+   * With a `variant` (`?w=`), the bytes are resized before being sent and the
+   * ETag carries the variant parameters — otherwise a conditional request for
+   * one width would get a 304 while holding the bytes of another.
    */
   async serveImageById(
     locale: string,
     id: number,
     ifNoneMatch: string | undefined,
     res: any,
+    variant?: ImageVariantRequest,
   ) {
     const { provider, providerPath, size, mimetype, filename } =
       await this.resolveFileMeta(locale, id);
@@ -1041,26 +1310,122 @@ export class FileService implements OnModuleInit {
       );
     }
 
-    const etag = `"img-${id}-${size ?? 0}"`;
+    const resolved = await this.resolveImageVariant(variant);
+    const variantSuffix = resolved
+      ? `-w${resolved.width}-${resolved.format ?? 'auto'}-q${resolved.quality}`
+      : '';
+    const etag = `"img-${id}-${size ?? 0}${variantSuffix}"`;
     if (ifNoneMatch && ifNoneMatch === etag) {
       res.status(304).end();
       return;
     }
 
     const ttl = await this.getCacheTtl('image-cache-ttl-seconds', 2592000);
-    this.setInlineHeaders(
-      res,
-      filename,
-      contentType,
-      size,
-      `public, max-age=${ttl}, immutable`,
-      etag,
-    );
+    const cacheControl = `public, max-age=${ttl}, immutable`;
+
+    if (resolved) {
+      const rendered = await this.renderImageVariant(
+        provider,
+        providerPath,
+        contentType,
+        id,
+        size,
+        resolved,
+      );
+      // A null render (unsupported format, sharp failure) falls through to the
+      // original bytes below rather than erroring the request.
+      if (rendered) {
+        const ext = rendered.mimetype.replace('image/', '');
+        this.setInlineHeaders(
+          res,
+          `${basename(filename, extname(filename))}.${ext === 'jpeg' ? 'jpg' : ext}`,
+          rendered.mimetype,
+          rendered.buffer.length,
+          cacheControl,
+          etag,
+        );
+        res.end(rendered.buffer);
+        return;
+      }
+    }
+
+    this.setInlineHeaders(res, filename, contentType, size, cacheControl, etag);
 
     const stream = await provider.readStream(providerPath);
     stream.pipe(res);
   }
 
+  /**
+   * Produces (and memoizes on disk) a resized variant of a stored image.
+   * The cache key includes the file size, so re-uploading under the same id —
+   * which the storage layer does not normally do — cannot serve stale bytes.
+   */
+  private async renderImageVariant(
+    provider: any,
+    providerPath: string,
+    contentType: string,
+    id: number,
+    size: number | undefined,
+    variant: { width: number; format?: ImageVariantFormat; quality: number },
+  ): Promise<{ buffer: Buffer; mimetype: string } | null> {
+    const format =
+      variant.format ??
+      (contentType === 'image/png'
+        ? 'png'
+        : contentType === 'image/webp'
+          ? 'webp'
+          : contentType === 'image/avif'
+            ? 'avif'
+            : 'jpeg');
+    const cachePath = this.imageVariantCachePath(
+      id,
+      size,
+      variant.width,
+      format,
+      variant.quality,
+    );
+
+    try {
+      const cached = await fs.readFile(cachePath);
+      return { buffer: cached, mimetype: `image/${format}` };
+    } catch {
+      // Cache miss is the normal path on a cold pod; fall through and render.
+    }
+
+    try {
+      const stream = await provider.readStream(providerPath);
+      const chunks: Buffer[] = [];
+      for await (const chunk of stream) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      }
+      const original = Buffer.concat(chunks);
+
+      const rendered = await this.imageOptimizationService.resizeBuffer(
+        original,
+        contentType,
+        { width: variant.width, format: variant.format, quality: variant.quality },
+      );
+      if (!rendered) return null;
+
+      try {
+        await fs.mkdir(dirname(cachePath), { recursive: true });
+        await fs.writeFile(cachePath, rendered.buffer);
+      } catch (err) {
+        // A read-only or full tmpdir must not break serving the image.
+        this.logger.warn(
+          `Could not cache image variant ${cachePath}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      return { buffer: rendered.buffer, mimetype: rendered.mimetype };
+    } catch (err) {
+      this.logger.warn(
+        `Could not render image variant for file ${id}: ${err instanceof Error ? err.message : String(err)}. Serving the original.`,
+      );
+      return null;
+    }
+  }
+
   /**
    * Serves any file by id with configurable HTTP caching (not immutable, shorter
    * TTL than images). Used by the generic open endpoint's numeric-id branch.
@@ -1615,4 +1980,34 @@ export class FileService implements OnModuleInit {
       },
     );
   }
+
+  /**
+   * Base pública para URLs de arquivo devolvidas ao navegador.
+   *
+   * Não dá para derivar do `Host` da requisição: apps que falam com a API por
+   * proxy interno (o class, via rewrite `/api` do Next) fazem o Nest enxergar o
+   * Service do cluster, e a URL sai como `http://hub-api:3100/...` — inútil no
+   * navegador. O setting `api-url` é a URL pública canônica da API no repo; o
+   * `Host` fica só como fallback para ambientes sem o setting configurado.
+   */
+  async resolvePublicBaseUrl(req: Request): Promise<string> {
+    let configured = '';
+
+    try {
+      const settings = await this.settingService.getSettingValues([
+        'api-url',
+        'url',
+      ]);
+      const value = settings?.['api-url'] || settings?.['url'];
+      configured = typeof value === 'string' ? value.trim() : '';
+    } catch {
+      configured = '';
+    }
+
+    if (/^https?:\/\/.+/i.test(configured)) {
+      return configured.replace(/\/+$/, '');
+    }
+
+    return `${req.protocol}://${req.get('host')}`;
+  }
 }

package/src/file/image-optimization.service.spec.ts

@@ -7,6 +7,7 @@ jest.mock('sharp', () => {
     webp: jest.fn(),
     jpeg: jest.fn(),
     png: jest.fn(),
+    avif: jest.fn(),
     toBuffer: jest.fn(),
   };
   const fn: any = jest.fn(() => instance);
@@ -46,6 +47,7 @@ describe('ImageOptimizationService', () => {
     inst.webp.mockReset().mockReturnValue(inst);
     inst.jpeg.mockReset().mockReturnValue(inst);
     inst.png.mockReset().mockReturnValue(inst);
+    inst.avif.mockReset().mockReturnValue(inst);
     inst.toBuffer.mockReset();
   });
 
@@ -280,4 +282,94 @@ describe('ImageOptimizationService', () => {
       expect(mockSharp.__instance.jpeg).toHaveBeenCalledWith({ quality: 80 });
     });
   });
+
+  describe('resizeBuffer', () => {
+    it('redimensiona sem ampliar e converte para o formato pedido', async () => {
+      const { service } = makeService();
+      mockSharp.__instance.webp.mockReturnValue(mockSharp.__instance);
+      mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
+
+      const result = await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+        width: 640,
+        format: 'webp',
+        quality: 82,
+      });
+
+      expect(mockSharp.__instance.resize).toHaveBeenCalledWith({
+        width: 640,
+        fit: 'inside',
+        withoutEnlargement: true,
+      });
+      expect(mockSharp.__instance.webp).toHaveBeenCalledWith({ quality: 82 });
+      expect(result).toEqual({
+        buffer: Buffer.from('out'),
+        mimetype: 'image/webp',
+        originalname: 'image.webp',
+      });
+    });
+
+    it('mantém o formato de origem quando nenhum é pedido', async () => {
+      const { service } = makeService();
+      mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
+
+      const result = await service.resizeBuffer(Buffer.from('img'), 'image/png', {
+        width: 320,
+      });
+
+      expect(mockSharp.__instance.png).toHaveBeenCalled();
+      expect(result?.mimetype).toBe('image/png');
+    });
+
+    it('não redimensiona SVG nem GIF animado', async () => {
+      const { service } = makeService();
+
+      expect(
+        await service.resizeBuffer(Buffer.from('x'), 'image/svg+xml', { width: 640 }),
+      ).toBeNull();
+      expect(
+        await service.resizeBuffer(Buffer.from('x'), 'image/gif', { width: 640 }),
+      ).toBeNull();
+      expect(mockSharp).not.toHaveBeenCalled();
+    });
+
+    it('retorna null para largura inválida', async () => {
+      const { service } = makeService();
+
+      expect(
+        await service.resizeBuffer(Buffer.from('x'), 'image/jpeg', { width: 0 }),
+      ).toBeNull();
+      expect(
+        await service.resizeBuffer(Buffer.from('x'), 'image/jpeg', {
+          width: -10,
+        }),
+      ).toBeNull();
+    });
+
+    it('retorna null quando o sharp lança, para o caller servir o original', async () => {
+      const { service } = makeService();
+      const warnSpy = jest
+        .spyOn((service as any).logger, 'warn')
+        .mockImplementation(() => undefined);
+      mockSharp.__instance.toBuffer.mockRejectedValue(new Error('sharp boom'));
+
+      const result = await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+        width: 640,
+      });
+
+      expect(result).toBeNull();
+      expect(warnSpy).toHaveBeenCalled();
+    });
+
+    it('faz clamp da quality fora da faixa', async () => {
+      const { service } = makeService();
+      mockSharp.__instance.toBuffer.mockResolvedValue(Buffer.from('out'));
+
+      await service.resizeBuffer(Buffer.from('img'), 'image/jpeg', {
+        width: 640,
+        quality: 0,
+      });
+
+      expect(mockSharp.__instance.jpeg).toHaveBeenCalledWith({ quality: 80 });
+    });
+  });
 });