create-forgeon 0.3.5 → 0.3.7

package/templates/module-presets/files-quotas/packages/files-quotas/src/files-quotas.service.ts

@@ -0,0 +1,118 @@
+import { ConflictException, Injectable } from '@nestjs/common';
+import { FilesService } from '@forgeon/files';
+import { FilesQuotasConfigService } from './files-quotas-config.service';
+import type { FilesQuotaCheckInput, FilesQuotaCheckResult } from './files-quotas.types';
+
+@Injectable()
+export class FilesQuotasService {
+  constructor(
+    private readonly filesService: FilesService,
+    private readonly configService: FilesQuotasConfigService,
+  ) {}
+
+  get enabled(): boolean {
+    return this.configService.enabled;
+  }
+
+  get limits() {
+    return {
+      maxFilesPerOwner: this.configService.maxFilesPerOwner,
+      maxBytesPerOwner: this.configService.maxBytesPerOwner,
+    };
+  }
+
+  async evaluateUpload(input: FilesQuotaCheckInput): Promise<FilesQuotaCheckResult> {
+    const limits = this.limits;
+    const emptyUsage = {
+      filesCount: 0,
+      totalBytes: 0,
+    };
+    const baseResult = {
+      limits,
+      current: emptyUsage,
+      next: {
+        filesCount: emptyUsage.filesCount + 1,
+        totalBytes: emptyUsage.totalBytes + input.fileSize,
+      },
+    };
+
+    if (!this.enabled) {
+      return {
+        allowed: true,
+        reason: 'disabled',
+        ...baseResult,
+      };
+    }
+
+    if (!input.ownerId) {
+      return {
+        allowed: true,
+        reason: 'owner-missing',
+        ...baseResult,
+      };
+    }
+
+    const usage = await this.filesService.getOwnerUsage(input.ownerType, input.ownerId);
+    const next = {
+      filesCount: usage.filesCount + 1,
+      totalBytes: usage.totalBytes + input.fileSize,
+    };
+
+    if (next.filesCount > limits.maxFilesPerOwner) {
+      return {
+        allowed: false,
+        reason: 'max-files',
+        limits,
+        current: usage,
+        next,
+      };
+    }
+    if (next.totalBytes > limits.maxBytesPerOwner) {
+      return {
+        allowed: false,
+        reason: 'max-bytes',
+        limits,
+        current: usage,
+        next,
+      };
+    }
+
+    return {
+      allowed: true,
+      reason: 'ok',
+      limits,
+      current: usage,
+      next,
+    };
+  }
+
+  async assertUploadAllowed(input: FilesQuotaCheckInput): Promise<void> {
+    const result = await this.evaluateUpload(input);
+    if (result.allowed) {
+      return;
+    }
+
+    throw new ConflictException({
+      message: 'File quota exceeded for owner',
+      details: {
+        reason: result.reason,
+        limits: result.limits,
+        current: result.current,
+        next: result.next,
+      },
+    });
+  }
+
+  async getProbeStatus(input: FilesQuotaCheckInput): Promise<{
+    status: 'ok';
+    feature: 'files-quotas';
+    result: FilesQuotaCheckResult;
+  }> {
+    const result = await this.evaluateUpload(input);
+    return {
+      status: 'ok',
+      feature: 'files-quotas',
+      result,
+    };
+  }
+}

package/templates/module-presets/files-quotas/packages/files-quotas/src/files-quotas.types.ts

@@ -0,0 +1,22 @@
+export type FilesQuotaCheckInput = {
+  ownerType: string;
+  ownerId: string | null;
+  fileSize: number;
+};
+
+export type FilesQuotaCheckResult = {
+  allowed: boolean;
+  reason: 'ok' | 'disabled' | 'owner-missing' | 'max-files' | 'max-bytes';
+  limits: {
+    maxFilesPerOwner: number;
+    maxBytesPerOwner: number;
+  };
+  current: {
+    filesCount: number;
+    totalBytes: number;
+  };
+  next: {
+    filesCount: number;
+    totalBytes: number;
+  };
+};

package/templates/module-presets/files-quotas/packages/files-quotas/src/forgeon-files-quotas.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { ForgeonFilesModule } from '@forgeon/files';
+import { FilesQuotasConfigModule } from './files-quotas-config.module';
+import { FilesQuotasService } from './files-quotas.service';
+
+@Module({
+  imports: [ForgeonFilesModule, FilesQuotasConfigModule],
+  providers: [FilesQuotasService],
+  exports: [FilesQuotasConfigModule, FilesQuotasService],
+})
+export class ForgeonFilesQuotasModule {}

package/templates/module-presets/files-quotas/packages/files-quotas/src/index.ts

@@ -0,0 +1,7 @@
+export * from './files-quotas-config.loader';
+export * from './files-quotas-config.module';
+export * from './files-quotas-config.service';
+export * from './files-quotas-env.schema';
+export * from './files-quotas.service';
+export * from './files-quotas.types';
+export * from './forgeon-files-quotas.module';

package/templates/module-presets/files-quotas/packages/files-quotas/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/module-presets/files-s3/packages/files-s3/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@forgeon/files-s3",
+  "version": "0.1.0",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.922.0",
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}

package/templates/module-presets/files-s3/packages/files-s3/src/files-s3-config.loader.ts

@@ -0,0 +1,57 @@
+import { registerAs } from '@nestjs/config';
+import { parseFilesS3Env } from './files-s3-env.schema';
+
+export type FilesS3ProviderPreset = 'minio' | 'r2' | 'aws' | 'custom';
+
+export type FilesS3ConfigValue = {
+  providerPreset: FilesS3ProviderPreset;
+  bucket: string;
+  region: string;
+  endpoint?: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  forcePathStyle: boolean;
+  maxAttempts: number;
+};
+
+const providerDefaults: Record<
+  FilesS3ProviderPreset,
+  {
+    region: string;
+    endpoint?: string;
+    forcePathStyle: boolean;
+  }
+> = {
+  minio: {
+    region: 'auto',
+    endpoint: 'http://localhost:9000',
+    forcePathStyle: true,
+  },
+  r2: {
+    region: 'auto',
+    forcePathStyle: false,
+  },
+  aws: {
+    region: 'eu-central-1',
+    forcePathStyle: false,
+  },
+  custom: {
+    region: 'eu-central-1',
+    forcePathStyle: false,
+  },
+};
+
+export const filesS3Config = registerAs('filesS3', (): FilesS3ConfigValue => {
+  const env = parseFilesS3Env(process.env);
+  const presetDefaults = providerDefaults[env.FILES_S3_PROVIDER_PRESET];
+  return {
+    providerPreset: env.FILES_S3_PROVIDER_PRESET,
+    bucket: env.FILES_S3_BUCKET,
+    region: env.FILES_S3_REGION ?? presetDefaults.region,
+    endpoint: env.FILES_S3_ENDPOINT ?? presetDefaults.endpoint,
+    accessKeyId: env.FILES_S3_ACCESS_KEY_ID,
+    secretAccessKey: env.FILES_S3_SECRET_ACCESS_KEY,
+    forcePathStyle: env.FILES_S3_FORCE_PATH_STYLE ?? presetDefaults.forcePathStyle,
+    maxAttempts: env.FILES_S3_MAX_ATTEMPTS,
+  };
+});

package/templates/module-presets/files-s3/packages/files-s3/src/files-s3-config.module.ts

@@ -0,0 +1,12 @@
+import { Global, Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { filesS3Config } from './files-s3-config.loader';
+import { FilesS3ConfigService } from './files-s3-config.service';
+
+@Global()
+@Module({
+  imports: [ConfigModule.forFeature(filesS3Config)],
+  providers: [FilesS3ConfigService],
+  exports: [FilesS3ConfigService],
+})
+export class FilesS3ConfigModule {}

package/templates/module-presets/files-s3/packages/files-s3/src/files-s3-config.service.ts

@@ -0,0 +1,44 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { FilesS3ConfigValue } from './files-s3-config.loader';
+
+@Injectable()
+export class FilesS3ConfigService {
+  constructor(private readonly configService: ConfigService) {}
+
+  get bucket(): string {
+    return this.configService.getOrThrow<FilesS3ConfigValue['bucket']>('filesS3.bucket');
+  }
+
+  get providerPreset(): FilesS3ConfigValue['providerPreset'] {
+    return this.configService.getOrThrow<FilesS3ConfigValue['providerPreset']>('filesS3.providerPreset');
+  }
+
+  get region(): string {
+    return this.configService.getOrThrow<FilesS3ConfigValue['region']>('filesS3.region');
+  }
+
+  get endpoint(): string | undefined {
+    return this.configService.get<FilesS3ConfigValue['endpoint']>('filesS3.endpoint');
+  }
+
+  get accessKeyId(): string {
+    return this.configService.getOrThrow<FilesS3ConfigValue['accessKeyId']>('filesS3.accessKeyId');
+  }
+
+  get secretAccessKey(): string {
+    return this.configService.getOrThrow<FilesS3ConfigValue['secretAccessKey']>(
+      'filesS3.secretAccessKey',
+    );
+  }
+
+  get forcePathStyle(): boolean {
+    return this.configService.getOrThrow<FilesS3ConfigValue['forcePathStyle']>(
+      'filesS3.forcePathStyle',
+    );
+  }
+
+  get maxAttempts(): number {
+    return this.configService.getOrThrow<FilesS3ConfigValue['maxAttempts']>('filesS3.maxAttempts');
+  }
+}

package/templates/module-presets/files-s3/packages/files-s3/src/files-s3-env.schema.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+const s3ProviderPresetSchema = z.enum(['minio', 'r2', 'aws', 'custom']);
+
+function normalizeOptionalString() {
+  return z.string().optional().transform((value) => {
+    if (value === undefined) {
+      return undefined;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+  });
+}
+
+function parseIntFromEnv(defaultValue: number, minValue: number) {
+  return z
+    .string()
+    .optional()
+    .default(String(defaultValue))
+    .transform((value) => Number.parseInt(value, 10))
+    .refine((value) => Number.isInteger(value), 'must be an integer')
+    .refine((value) => value >= minValue, `must be >= ${minValue}`);
+}
+
+const filesS3EnvSchema = z.object({
+  FILES_S3_PROVIDER_PRESET: s3ProviderPresetSchema.optional().default('minio'),
+  FILES_S3_BUCKET: z.string().optional().default('forgeon-files'),
+  FILES_S3_REGION: normalizeOptionalString(),
+  FILES_S3_ENDPOINT: normalizeOptionalString(),
+  FILES_S3_ACCESS_KEY_ID: z.string().optional().default('forgeon'),
+  FILES_S3_SECRET_ACCESS_KEY: z.string().optional().default('forgeon-secret'),
+  FILES_S3_FORCE_PATH_STYLE: z.string().optional().transform((value) => {
+    if (value === undefined) {
+      return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized.length === 0) {
+      return undefined;
+    }
+    return normalized !== 'false';
+  }),
+  FILES_S3_MAX_ATTEMPTS: parseIntFromEnv(3, 1),
+});
+
+export type FilesS3EnvSchema = z.infer<typeof filesS3EnvSchema>;
+
+export function parseFilesS3Env(input: Record<string, string | undefined>): FilesS3EnvSchema {
+  return filesS3EnvSchema.parse(input);
+}
+
+export const filesS3EnvSchemaZod = filesS3EnvSchema;

package/templates/module-presets/files-s3/packages/files-s3/src/index.ts

@@ -0,0 +1,4 @@
+export * from './files-s3-config.loader';
+export * from './files-s3-config.module';
+export * from './files-s3-config.service';
+export * from './files-s3-env.schema';

package/templates/module-presets/files-s3/packages/files-s3/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/module-presets/queue/packages/queue/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@forgeon/queue",
+  "version": "0.1.0",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.2",
+    "bullmq": "^5.61.0",
+    "rxjs": "^7.8.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}

package/templates/module-presets/queue/packages/queue/src/forgeon-queue.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { QueueConfigModule } from './queue-config.module';
+import { QueueService } from './queue.service';
+
+@Module({
+  imports: [QueueConfigModule],
+  providers: [QueueService],
+  exports: [QueueConfigModule, QueueService],
+})
+export class ForgeonQueueModule {}

package/templates/module-presets/queue/packages/queue/src/index.ts

@@ -0,0 +1,6 @@
+export * from './forgeon-queue.module';
+export * from './queue-config.loader';
+export * from './queue-config.module';
+export * from './queue-config.service';
+export * from './queue-env.schema';
+export * from './queue.service';

package/templates/module-presets/queue/packages/queue/src/queue-config.loader.ts

@@ -0,0 +1,24 @@
+import { registerAs } from '@nestjs/config';
+import { parseQueueEnv } from './queue-env.schema';
+
+export const QUEUE_CONFIG_NAMESPACE = 'queue';
+
+export interface QueueConfigValues {
+  enabled: boolean;
+  redisUrl: string;
+  prefix: string;
+  defaultAttempts: number;
+  defaultBackoffMs: number;
+}
+
+export const queueConfig = registerAs(QUEUE_CONFIG_NAMESPACE, (): QueueConfigValues => {
+  const env = parseQueueEnv(process.env);
+
+  return {
+    enabled: env.QUEUE_ENABLED,
+    redisUrl: env.QUEUE_REDIS_URL,
+    prefix: env.QUEUE_PREFIX,
+    defaultAttempts: env.QUEUE_DEFAULT_ATTEMPTS,
+    defaultBackoffMs: env.QUEUE_DEFAULT_BACKOFF_MS,
+  };
+});

package/templates/module-presets/queue/packages/queue/src/queue-config.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { QueueConfigService } from './queue-config.service';
+
+@Module({
+  imports: [ConfigModule],
+  providers: [QueueConfigService],
+  exports: [QueueConfigService],
+})
+export class QueueConfigModule {}

package/templates/module-presets/queue/packages/queue/src/queue-config.service.ts

@@ -0,0 +1,69 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { ConnectionOptions } from 'bullmq';
+import { QUEUE_CONFIG_NAMESPACE, QueueConfigValues } from './queue-config.loader';
+
+@Injectable()
+export class QueueConfigService {
+  constructor(private readonly configService: ConfigService) {}
+
+  get enabled(): QueueConfigValues['enabled'] {
+    return this.configService.getOrThrow<QueueConfigValues['enabled']>(
+      `${QUEUE_CONFIG_NAMESPACE}.enabled`,
+    );
+  }
+
+  get redisUrl(): QueueConfigValues['redisUrl'] {
+    return this.configService.getOrThrow<QueueConfigValues['redisUrl']>(
+      `${QUEUE_CONFIG_NAMESPACE}.redisUrl`,
+    );
+  }
+
+  get prefix(): QueueConfigValues['prefix'] {
+    return this.configService.getOrThrow<QueueConfigValues['prefix']>(
+      `${QUEUE_CONFIG_NAMESPACE}.prefix`,
+    );
+  }
+
+  get defaultAttempts(): QueueConfigValues['defaultAttempts'] {
+    return this.configService.getOrThrow<QueueConfigValues['defaultAttempts']>(
+      `${QUEUE_CONFIG_NAMESPACE}.defaultAttempts`,
+    );
+  }
+
+  get defaultBackoffMs(): QueueConfigValues['defaultBackoffMs'] {
+    return this.configService.getOrThrow<QueueConfigValues['defaultBackoffMs']>(
+      `${QUEUE_CONFIG_NAMESPACE}.defaultBackoffMs`,
+    );
+  }
+
+  get connectionOptions(): ConnectionOptions {
+    const parsedUrl = new URL(this.redisUrl);
+    const options: ConnectionOptions = {
+      host: parsedUrl.hostname,
+      port: parsedUrl.port ? Number(parsedUrl.port) : 6379,
+    };
+
+    if (parsedUrl.username) {
+      (options as { username?: string }).username = decodeURIComponent(parsedUrl.username);
+    }
+
+    if (parsedUrl.password) {
+      (options as { password?: string }).password = decodeURIComponent(parsedUrl.password);
+    }
+
+    const dbPath = parsedUrl.pathname.replace(/^\//, '');
+    if (dbPath.length > 0) {
+      const dbValue = Number(dbPath);
+      if (Number.isInteger(dbValue) && dbValue >= 0) {
+        (options as { db?: number }).db = dbValue;
+      }
+    }
+
+    if (parsedUrl.protocol === 'rediss:') {
+      (options as { tls?: Record<string, never> }).tls = {};
+    }
+
+    return options;
+  }
+}

package/templates/module-presets/queue/packages/queue/src/queue-env.schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+export const queueEnvSchema = z
+  .object({
+    QUEUE_ENABLED: z.coerce.boolean().default(true),
+    QUEUE_REDIS_URL: z.string().trim().min(1).default('redis://localhost:6379'),
+    QUEUE_PREFIX: z.string().trim().min(1).default('forgeon'),
+    QUEUE_DEFAULT_ATTEMPTS: z.coerce.number().int().positive().default(3),
+    QUEUE_DEFAULT_BACKOFF_MS: z.coerce.number().int().nonnegative().default(1000),
+  })
+  .passthrough();
+
+export type QueueEnv = z.infer<typeof queueEnvSchema>;
+
+export function parseQueueEnv(input: Record<string, unknown>): QueueEnv {
+  return queueEnvSchema.parse(input);
+}

package/templates/module-presets/queue/packages/queue/src/queue.service.ts

@@ -0,0 +1,88 @@
+import { Injectable, OnModuleDestroy } from '@nestjs/common';
+import type { JobsOptions } from 'bullmq';
+import { Queue } from 'bullmq';
+import { QueueConfigService } from './queue-config.service';
+
+export const FORGEON_DEFAULT_QUEUE = 'forgeon.default';
+
+@Injectable()
+export class QueueService implements OnModuleDestroy {
+  private queue: Queue | null = null;
+
+  constructor(private readonly queueConfig: QueueConfigService) {}
+
+  async enqueue(
+    name: string,
+    data: Record<string, unknown>,
+    options: JobsOptions = {},
+  ): Promise<{ queued: boolean; id: string | null }> {
+    if (!this.queueConfig.enabled) {
+      return { queued: false, id: null };
+    }
+
+    const job = await this.getQueue().add(name, data, {
+      attempts: this.queueConfig.defaultAttempts,
+      backoff: {
+        type: 'fixed',
+        delay: this.queueConfig.defaultBackoffMs,
+      },
+      ...options,
+    });
+
+    return {
+      queued: true,
+      id: job.id == null ? null : String(job.id),
+    };
+  }
+
+  async getProbeStatus(): Promise<Record<string, unknown>> {
+    if (!this.queueConfig.enabled) {
+      return {
+        status: 'ok',
+        feature: 'queue',
+        enabled: false,
+      };
+    }
+
+    try {
+      const queue = this.getQueue();
+      const client = await queue.client;
+      const ping = await client.ping();
+      return {
+        status: 'ok',
+        feature: 'queue',
+        enabled: true,
+        queueName: FORGEON_DEFAULT_QUEUE,
+        prefix: this.queueConfig.prefix,
+        redis: ping,
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        feature: 'queue',
+        enabled: true,
+        queueName: FORGEON_DEFAULT_QUEUE,
+        message: error instanceof Error ? error.message : 'Queue probe failed',
+      };
+    }
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (!this.queue) {
+      return;
+    }
+
+    await this.queue.close();
+    this.queue = null;
+  }
+
+  private getQueue(): Queue {
+    if (!this.queue) {
+      this.queue = new Queue(FORGEON_DEFAULT_QUEUE, {
+        prefix: this.queueConfig.prefix,
+        connection: this.queueConfig.connectionOptions,
+      });
+    }
+    return this.queue;
+  }
+}

package/templates/module-presets/queue/packages/queue/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/module-fragments/queue/90_status_planned.md

@@ -1,3 +0,0 @@
-## Current State
-
-This module is registered but not implemented yet.