@postxl/generators 1.15.0 → 1.16.0

package/dist/backend-upload/template/src/upload.service.ts

@@ -0,0 +1,333 @@
+import { DispatcherService } from '@actions/dispatcher.service'
+import { BadRequestException, Injectable, NotFoundException, PayloadTooLargeException } from '@nestjs/common'
+import { S3Service } from '@s3/s3.service'
+import type { FileId, User } from '@types'
+import { ViewService } from '@view/view.service'
+
+import type { MultipartFile } from '@fastify/multipart'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { Readable } from 'node:stream'
+
+import { UploadConfig } from './upload.config'
+import {
+  DEFAULT_MAX_SIZE_BYTES,
+  type StoredUploadRecord,
+  type UploadGuardOptions,
+  type UploadedFileDataPayload,
+  type UploadStorageMode,
+} from './upload.types'
+
+type FileTypeRule = {
+  extensions: string[]
+  mimeTypes: string[]
+  mimePrefixes: string[]
+}
+
+const FILE_TYPE_RULES: Record<string, FileTypeRule> = {
+  image: {
+    extensions: ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'],
+    mimeTypes: [],
+    mimePrefixes: ['image/'],
+  },
+  excel: {
+    extensions: ['.xlsx', '.xls'],
+    mimeTypes: [
+      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      'application/vnd.ms-excel',
+      'application/octet-stream',
+    ],
+    mimePrefixes: [],
+  },
+  json: {
+    extensions: ['.json'],
+    mimeTypes: ['application/json', 'text/json'],
+    mimePrefixes: [],
+  },
+  csv: {
+    extensions: ['.csv'],
+    mimeTypes: ['text/csv', 'application/csv', 'application/vnd.ms-excel'],
+    mimePrefixes: [],
+  },
+  pdf: {
+    extensions: ['.pdf'],
+    mimeTypes: ['application/pdf'],
+    mimePrefixes: [],
+  },
+  text: {
+    extensions: ['.txt', '.md'],
+    mimeTypes: ['text/plain', 'text/markdown'],
+    mimePrefixes: ['text/'],
+  },
+}
+
+@Injectable()
+export class UploadService {
+  private readonly inMemoryFiles = new Map<FileId, Buffer>()
+
+  constructor(
+    private readonly uploadConfig: UploadConfig,
+    private readonly dispatcherService: DispatcherService,
+    private readonly viewService: ViewService,
+    private readonly s3Service: S3Service,
+  ) {}
+
+  public async processUpload({
+    multipartFile,
+    user,
+    options,
+  }: {
+    multipartFile: MultipartFile
+    user: User
+    options?: UploadGuardOptions
+  }): Promise<UploadedFileDataPayload> {
+    const maxBytes = options?.maxFileSizeBytes ?? this.uploadConfig.values.maxSizeBytes ?? DEFAULT_MAX_SIZE_BYTES
+    const filename = multipartFile.filename || 'upload.bin'
+    const mimetype = multipartFile.mimetype || 'application/octet-stream'
+    const extension = path.extname(filename).toLowerCase()
+
+    this.validateConstraints({ extension, mimetype, options })
+
+    const buffer = await this.toBufferWithLimit(multipartFile.file, maxBytes)
+    if (buffer.length === 0) {
+      throw new BadRequestException('Uploaded file is empty')
+    }
+
+    const storageMode = this.resolveStorageMode(options)
+    const createdFile = await this.dispatcherService.dispatch({
+      action: {
+        scope: 'file',
+        type: 'create',
+        payload: {
+          name: filename,
+          mimetype,
+          size: buffer.length,
+          url: '',
+        },
+      },
+      user,
+    })
+
+    try {
+      const stored = await this.storeUpload({ fileId: createdFile.id, filename, extension, buffer, storageMode })
+
+      const updatedFile = await this.dispatcherService.dispatch({
+        action: {
+          scope: 'file',
+          type: 'update',
+          payload: {
+            id: createdFile.id,
+            name: filename,
+            mimetype,
+            size: buffer.length,
+            url: stored.location,
+          },
+        },
+        user,
+      })
+
+      return {
+        file: updatedFile,
+        buffer,
+        filename,
+        mimetype,
+        size: buffer.length,
+        fields: multipartFile.fields,
+      }
+    } catch (error) {
+      await this.deleteFailedUploadRecord({ fileId: createdFile.id, user })
+      throw error
+    }
+  }
+
+  public async getStoredFileBuffer({ fileId, user }: { fileId: FileId; user: User }): Promise<Buffer> {
+    const file = await this.viewService.files.get({ id: fileId, user })
+    if (!file) {
+      throw new NotFoundException(`File ${fileId} not found`)
+    }
+
+    return this.readStoredFile({ fileId, location: file.url })
+  }
+
+  public async getStoredFileRecord({ fileId, user }: { fileId: FileId; user: User }) {
+    const file = await this.viewService.files.get({ id: fileId, user })
+    if (!file) {
+      throw new NotFoundException(`File ${fileId} not found`)
+    }
+
+    return file
+  }
+
+  public async getBufferFromFileRecord({ fileId, location }: { fileId: FileId; location: string }): Promise<Buffer> {
+    return this.readStoredFile({ fileId, location })
+  }
+
+  public getRootUser(): User {
+    return this.viewService.users.data.rootUser
+  }
+
+  private resolveStorageMode(options?: UploadGuardOptions): UploadStorageMode {
+    if (this.uploadConfig.values.dryRun) {
+      return 'none'
+    }
+
+    return options?.storageMode ?? this.uploadConfig.values.storage
+  }
+
+  private async storeUpload({
+    fileId,
+    filename,
+    extension,
+    buffer,
+    storageMode,
+  }: {
+    fileId: FileId
+    filename: string
+    extension: string
+    buffer: Buffer
+    storageMode: UploadStorageMode
+  }): Promise<StoredUploadRecord> {
+    if (storageMode === 'none') {
+      this.inMemoryFiles.set(fileId, buffer)
+      return {
+        fileId,
+        location: `memory://${fileId}`,
+        storageMode,
+      }
+    }
+
+    if (storageMode === 'local') {
+      const sanitizedName = filename.replaceAll(/[^A-Za-z0-9._-]/g, '_')
+      const storageDir = path.resolve(this.uploadConfig.values.localDirectory)
+      const targetPath = path.join(storageDir, `${fileId}-${sanitizedName}`)
+
+      await mkdir(storageDir, { recursive: true })
+      await writeFile(targetPath, buffer)
+
+      return {
+        fileId,
+        location: `file://${targetPath}`,
+        storageMode,
+      }
+    }
+
+    const key = await this.s3Service.send(
+      Readable.from(buffer),
+      String(fileId),
+      extension ? extension.slice(1) : undefined,
+    )
+
+    return {
+      fileId,
+      location: `s3://${key}`,
+      storageMode,
+    }
+  }
+
+  private async readStoredFile({ fileId, location }: { fileId: FileId; location: string }): Promise<Buffer> {
+    if (location.startsWith('memory://')) {
+      const cached = this.inMemoryFiles.get(fileId)
+      if (!cached) {
+        throw new NotFoundException(`No in-memory binary found for ${fileId}`)
+      }
+      return cached
+    }
+
+    if (location.startsWith('file://')) {
+      const filePath = location.slice('file://'.length)
+      return readFile(filePath)
+    }
+
+    if (location.startsWith('s3://')) {
+      const key = location.slice('s3://'.length)
+      const body = await this.s3Service.getFile(key)
+      if (!body) {
+        throw new NotFoundException(`Stored object ${key} not found in S3`)
+      }
+      return Buffer.from(body)
+    }
+
+    throw new BadRequestException(`Unsupported upload location format: ${location}`)
+  }
+
+  private validateConstraints({
+    extension,
+    mimetype,
+    options,
+  }: {
+    extension: string
+    mimetype: string
+    options?: UploadGuardOptions
+  }): void {
+    if (options?.allowedMimeTypes && options.allowedMimeTypes.length > 0) {
+      if (!options.allowedMimeTypes.includes(mimetype)) {
+        throw new BadRequestException(`Unsupported mimetype: ${mimetype}`)
+      }
+    }
+
+    if (options?.allowedFileExtensions && options.allowedFileExtensions.length > 0) {
+      const allowedExtensions = options.allowedFileExtensions.map((ext) => ext.toLowerCase())
+      if (!allowedExtensions.includes(extension)) {
+        throw new BadRequestException(`Unsupported file extension: ${extension || '(none)'}`)
+      }
+    }
+
+    if (options?.allowedFileTypes && options.allowedFileTypes.length > 0) {
+      const allowed = options.allowedFileTypes.some((type) => {
+        const rule = FILE_TYPE_RULES[type]
+        return (
+          rule.extensions.includes(extension) ||
+          rule.mimeTypes.includes(mimetype) ||
+          rule.mimePrefixes.some((prefix) => mimetype.startsWith(prefix))
+        )
+      })
+
+      if (!allowed) {
+        throw new BadRequestException(
+          `File type is not allowed for mimetype ${mimetype} and extension ${extension || '(none)'}`,
+        )
+      }
+    }
+  }
+
+  private async toBufferWithLimit(stream: AsyncIterable<unknown>, maxBytes: number): Promise<Buffer> {
+    const chunks: Buffer[] = []
+    let size = 0
+
+    for await (const chunk of stream) {
+      const buffer = toBuffer(chunk)
+      size += buffer.length
+      if (size > maxBytes) {
+        throw new PayloadTooLargeException(`Uploaded file exceeds ${Math.floor(maxBytes / (1024 * 1024))} MB limit`)
+      }
+      chunks.push(buffer)
+    }
+
+    return Buffer.concat(chunks)
+  }
+
+  private async deleteFailedUploadRecord({ fileId, user }: { fileId: FileId; user: User }): Promise<void> {
+    try {
+      await this.dispatcherService.dispatch({
+        action: {
+          scope: 'file',
+          type: 'delete',
+          payload: fileId,
+        },
+        user,
+      })
+    } catch {
+      // Best-effort rollback to avoid orphan file records when storage fails.
+    }
+  }
+}
+
+function toBuffer(chunk: unknown): Buffer {
+  if (Buffer.isBuffer(chunk)) {
+    return chunk
+  }
+  if (chunk instanceof Uint8Array) {
+    return Buffer.from(chunk)
+  }
+  return Buffer.from(String(chunk))
+}

package/dist/backend-upload/template/src/upload.types.ts

@@ -0,0 +1,37 @@
+import type { MultipartFile } from '@fastify/multipart'
+import type { FastifyRequestWithViewer } from '@authentication/auth.guard'
+
+import type { FileId, FileViewModel } from '@types'
+
+export const DEFAULT_MAX_SIZE_BYTES = 30 * 1024 * 1024
+
+export type UploadStorageMode = 'none' | 'local' | 's3'
+
+export type UploadAllowedFileType = 'image' | 'excel' | 'json' | 'csv' | 'pdf' | 'text'
+
+export type UploadGuardOptions = {
+  maxFileSizeBytes?: number
+  allowedMimeTypes?: string[]
+  allowedFileExtensions?: string[]
+  allowedFileTypes?: UploadAllowedFileType[]
+  storageMode?: UploadStorageMode
+}
+
+export type UploadedFileDataPayload = {
+  file: FileViewModel
+  buffer: Buffer
+  filename: string
+  mimetype: string
+  size: number
+  fields: MultipartFile['fields']
+}
+
+export type UploadRequest = FastifyRequestWithViewer & {
+  uploadedFileData?: UploadedFileDataPayload
+}
+
+export type StoredUploadRecord = {
+  fileId: FileId
+  location: string
+  storageMode: UploadStorageMode
+}

package/dist/backend-upload/template/src/uploaded-file.decorator.ts

@@ -0,0 +1,12 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common'
+
+import type { UploadRequest } from './upload.types'
+
+export const UploadedFileData = createParamDecorator((_data: unknown, ctx: ExecutionContext) => {
+  const req = ctx.switchToHttp().getRequest<UploadRequest>()
+  if (!req.uploadedFileData) {
+    throw new Error('Decorator @UploadedFileData must be used with @UploadGuard')
+  }
+
+  return req.uploadedFileData
+})

package/dist/backend-upload/template/tsconfig.lib.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "../../dist/libs/upload"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}

package/dist/backend-upload/upload.generator.d.ts

@@ -0,0 +1,16 @@
+import * as Generator from '@postxl/generator';
+import { WithActions } from '../backend-actions';
+import { WithBackend } from '../backend-core';
+import { WithView } from '../backend-view';
+import { WithTypes } from '../types';
+type ContextRequirements = WithTypes<WithActions<WithView<WithBackend<Generator.Context>>>>;
+export type ContextResult = WithUpload<ContextRequirements>;
+export type WithUpload<Context> = Generator.ExtendContext<Context, {
+    upload: UploadContext;
+}>;
+type UploadContext = {
+    module: Generator.ImportableClass;
+};
+export declare const generatorId: string & import("zod").$brand<"PXL.GeneratorInterfaceId">;
+export declare const generator: Generator.GeneratorInterface;
+export {};

package/dist/backend-upload/upload.generator.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generator = exports.generatorId = void 0;
+const path = __importStar(require("node:path"));
+const Generator = __importStar(require("@postxl/generator"));
+const generator_1 = require("@postxl/generator");
+const backend_actions_1 = require("../backend-actions");
+const backend_core_1 = require("../backend-core");
+const backend_s3_1 = require("../backend-s3");
+const backend_view_1 = require("../backend-view");
+const types_1 = require("../types");
+exports.generatorId = Generator.toGeneratorInterfaceId('backend-upload');
+exports.generator = {
+    id: exports.generatorId,
+    requires: [
+        backend_core_1.backendGeneratorId,
+        backend_actions_1.backendActionsGeneratorId,
+        backend_view_1.backendViewGeneratorId,
+        backend_s3_1.backendS3GeneratorId,
+        types_1.typesGeneratorId,
+    ],
+    register: (context) => {
+        const module = {
+            name: Generator.toClassName('UploadModule'),
+            location: Generator.toBackendModuleLocation('@upload/upload.module'),
+        };
+        const uploadModule = {
+            name: Generator.toBackendModuleName('upload'),
+            moduleClass: module,
+            apiModuleRegistration: {
+                code: (0, generator_1.ts)('UploadModule.forRoot(config.upload)'),
+            },
+            envConfig: {
+                dotEnvExample: `
+          # Upload storage mode: none | local | s3
+          UPLOAD_STORAGE=none
+          # Path for local uploads if UPLOAD_STORAGE=local
+          UPLOAD_LOCAL_DIRECTORY="./tmp/uploads"
+          # If true, upload binaries are not persisted to local disk/S3
+          UPLOAD_DRY_RUN=true
+          # Default max upload size in bytes (30 MB)
+          UPLOAD_MAX_SIZE_BYTES=31457280`,
+                decoder: (0, generator_1.ts)(`
+          UPLOAD_STORAGE: z.enum(['none', 'local', 's3']).optional().default('none'),
+          UPLOAD_LOCAL_DIRECTORY: z.string().optional().default('./tmp/uploads'),
+          UPLOAD_DRY_RUN: zEnvBoolean.optional().default(true),
+          UPLOAD_MAX_SIZE_BYTES: z.coerce.number().int().positive().optional().default(30 * 1024 * 1024),
+        `),
+                transformer: (0, generator_1.ts)(`
+          upload: {
+            storage: val.UPLOAD_STORAGE,
+            localDirectory: val.UPLOAD_LOCAL_DIRECTORY,
+            dryRun: val.UPLOAD_DRY_RUN,
+            maxSizeBytes: val.UPLOAD_MAX_SIZE_BYTES,
+          }`),
+            },
+        };
+        context.backend.modules.push(uploadModule);
+        context.backend.packageJson.dependencies.push({ packageName: '@fastify/multipart', version: '9.2.1' });
+        return {
+            ...context,
+            upload: { module },
+        };
+    },
+    generate: async (context) => {
+        const vfs = new Generator.VirtualFileSystem();
+        await vfs.loadFolder({
+            diskPath: path.resolve(__dirname, './template'),
+        });
+        context.vfs.insertFromVfs({ targetPath: '/backend/libs/upload', vfs });
+        return context;
+    },
+};
+//# sourceMappingURL=upload.generator.js.map

package/dist/backend-upload/upload.generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.generator.js","sourceRoot":"","sources":["../../src/backend-upload/upload.generator.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAiC;AAEjC,6DAA8C;AAC9C,iDAAsC;AAEtC,wDAA2E;AAC3E,kDAA+E;AAC/E,8CAAoD;AACpD,kDAAkE;AAClE,oCAAsD;AAUzC,QAAA,WAAW,GAAG,SAAS,CAAC,sBAAsB,CAAC,gBAAgB,CAAC,CAAA;AAEhE,QAAA,SAAS,GAAiC;IACrD,EAAE,EAAE,mBAAW;IACf,QAAQ,EAAE;QACR,iCAAkB;QAClB,2CAAyB;QACzB,qCAAsB;QACtB,iCAAoB;QACpB,wBAAgB;KACjB;IAED,QAAQ,EAAE,CAAsC,OAAgB,EAAiB,EAAE;QACjF,MAAM,MAAM,GAA8B;YACxC,IAAI,EAAE,SAAS,CAAC,WAAW,CAAC,cAAc,CAAC;YAC3C,QAAQ,EAAE,SAAS,CAAC,uBAAuB,CAAC,uBAAuB,CAAC;SACrE,CAAA;QAED,MAAM,YAAY,GAAiB;YACjC,IAAI,EAAE,SAAS,CAAC,mBAAmB,CAAC,QAAQ,CAAC;YAC7C,WAAW,EAAE,MAAM;YACnB,qBAAqB,EAAE;gBACrB,IAAI,EAAE,IAAA,cAAE,EAAC,qCAAqC,CAAC;aAChD;YACD,SAAS,EAAE;gBACT,aAAa,EAAE;;;;;;;;yCAQkB;gBACjC,OAAO,EAAE,IAAA,cAAE,EAAC;;;;;SAKX,CAAC;gBACF,WAAW,EAAE,IAAA,cAAE,EAAC;;;;;;YAMZ,CAAC;aACN;SACF,CAAA;QAED,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;QAC1C,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,oBAAoB,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAA;QAEtG,OAAO;YACL,GAAG,OAAO;YACV,MAAM,EAAE,EAAE,MAAM,EAAE;SACnB,CAAA;IACH,CAAC;IAED,QAAQ,EAAE,KAAK,EAAiC,OAAgB,EAAoB,EAAE;QACpF,MAAM,GAAG,GAAG,IAAI,SAAS,CAAC,iBAAiB,EAAE,CAAA;QAE7C,MAAM,GAAG,CAAC,UAAU,CAAC;YACnB,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC;SAChD,CAAC,CAAA;QAEF,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,UAAU,EAAE,sBAAsB,EAAE,GAAG,EAAE,CAAC,CAAA;QACtE,OAAO,OAAO,CAAA;IAChB,CAAC;CACF,CAAA"}