@hed-hog/core 0.0.387 → 0.0.390

package/src/realtime/realtime.service.ts

@@ -0,0 +1,187 @@
+import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { createClient, type RedisClientType } from 'redis';
+import type { Server } from 'socket.io';
+
+type EmitTarget =
+  | { type: 'user'; target: string }
+  | { type: 'channel'; target: string }
+  | { type: 'broadcast' };
+
+interface RealtimeMessage {
+  target: EmitTarget;
+  event: string;
+  payload: unknown;
+  originInstanceId: string;
+}
+
+/**
+ * Generic real-time messaging layer usable by ANY module. Wraps the Socket.IO
+ * server (bound by {@link RealtimeGateway}) and fans emits out across API
+ * instances via Redis pub/sub — mirroring the settings-sync pattern — so a
+ * message emitted on one pod reaches clients connected to another. Without
+ * `REDIS_URL` it degrades to single-instance (local emit still works).
+ *
+ * Rooms: `user:{id}` (auto-joined on connect) and `channel:{name}` (joined via
+ * the gateway's `subscribe` message). Other modules just inject this service and
+ * call {@link emitToUser} / {@link emitToChannel} / {@link broadcast}.
+ */
+@Injectable()
+export class RealtimeService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(RealtimeService.name);
+  private readonly instanceId = randomUUID();
+  private readonly redisUrl = String(process.env.REDIS_URL || '').trim();
+  private readonly channel = 'core:realtime:emit';
+
+  private server: Server | null = null;
+  private redisPublisher: RedisClientType | null = null;
+  private redisSubscriber: RedisClientType | null = null;
+
+  /** Local (this-instance) socket count per user id, for presence/liveness. */
+  private readonly localConnections = new Map<number, number>();
+
+  async onModuleInit() {
+    await this.initRedis();
+  }
+
+  async onModuleDestroy() {
+    await Promise.allSettled([
+      this.safeClose(this.redisSubscriber),
+      this.safeClose(this.redisPublisher),
+    ]);
+  }
+
+  /** Called by the gateway once Socket.IO is initialized. */
+  setServer(server: Server) {
+    this.server = server;
+  }
+
+  private userRoom(userId: string | number) {
+    return `user:${userId}`;
+  }
+  private channelRoom(name: string) {
+    return `channel:${name}`;
+  }
+
+  /** Emits an event to every socket of a given user (all their tabs/devices). */
+  emitToUser(userId: string | number, event: string, payload: unknown) {
+    this.dispatch({ target: { type: 'user', target: String(userId) }, event, payload });
+  }
+
+  /** Emits an event to everyone subscribed to a named channel. */
+  emitToChannel(channel: string, event: string, payload: unknown) {
+    this.dispatch({ target: { type: 'channel', target: channel }, event, payload });
+  }
+
+  /** Emits an event to every connected client. */
+  broadcast(event: string, payload: unknown) {
+    this.dispatch({ target: { type: 'broadcast' }, event, payload });
+  }
+
+  private dispatch(msg: Omit<RealtimeMessage, 'originInstanceId'>) {
+    this.emitLocal(msg);
+    this.publish(msg);
+  }
+
+  private emitLocal(msg: Omit<RealtimeMessage, 'originInstanceId'>) {
+    if (!this.server) return;
+    const { target, event, payload } = msg;
+    if (target.type === 'user') {
+      this.server.to(this.userRoom(target.target)).emit(event, payload);
+    } else if (target.type === 'channel') {
+      this.server.to(this.channelRoom(target.target)).emit(event, payload);
+    } else {
+      this.server.emit(event, payload);
+    }
+  }
+
+  private publish(msg: Omit<RealtimeMessage, 'originInstanceId'>) {
+    if (!this.redisPublisher) return;
+    const full: RealtimeMessage = { ...msg, originInstanceId: this.instanceId };
+    this.redisPublisher
+      .publish(this.channel, JSON.stringify(full))
+      .catch((error) =>
+        this.logger.warn(
+          `Realtime publish failed: ${error instanceof Error ? error.message : 'unknown'}`,
+        ),
+      );
+  }
+
+  private handleRedisMessage(raw: string) {
+    let msg: RealtimeMessage;
+    try {
+      msg = JSON.parse(raw) as RealtimeMessage;
+    } catch {
+      return;
+    }
+    // Skip our own messages — they were already emitted locally.
+    if (!msg || msg.originInstanceId === this.instanceId) return;
+    this.emitLocal(msg);
+  }
+
+  // ── Connection tracking (called by the gateway) ────────────────────────────
+
+  /** Records a new local socket for a user; returns the new local count. */
+  trackConnect(userId: number): number {
+    const next = (this.localConnections.get(userId) ?? 0) + 1;
+    this.localConnections.set(userId, next);
+    return next;
+  }
+
+  /** Drops a local socket for a user; returns the remaining local count. */
+  trackDisconnect(userId: number): number {
+    const next = Math.max(0, (this.localConnections.get(userId) ?? 0) - 1);
+    if (next === 0) this.localConnections.delete(userId);
+    else this.localConnections.set(userId, next);
+    return next;
+  }
+
+  /** Whether the user has at least one socket on THIS instance. */
+  isLocallyConnected(userId: number): boolean {
+    return (this.localConnections.get(userId) ?? 0) > 0;
+  }
+
+  /** All user ids with at least one socket on this instance. */
+  getLocallyConnectedUserIds(): number[] {
+    return [...this.localConnections.keys()];
+  }
+
+  // ── Redis wiring (mirrors setting.service) ─────────────────────────────────
+
+  private async initRedis() {
+    if (!this.redisUrl) {
+      this.logger.log('Realtime Redis fan-out disabled (REDIS_URL not set); single-instance only.');
+      return;
+    }
+    try {
+      const opts = {
+        url: this.redisUrl,
+        socket: { reconnectStrategy: (retries: number) => Math.min(retries * 250, 5000) },
+      };
+      this.redisPublisher = createClient(opts);
+      this.redisSubscriber = createClient(opts);
+      this.redisPublisher.on('error', (e) => this.logger.warn(`Realtime Redis publisher error: ${e?.message ?? e}`));
+      this.redisSubscriber.on('error', (e) => this.logger.warn(`Realtime Redis subscriber error: ${e?.message ?? e}`));
+      await this.redisPublisher.connect();
+      await this.redisSubscriber.connect();
+      await this.redisSubscriber.subscribe(this.channel, (msg) => this.handleRedisMessage(msg));
+      this.logger.log(`Realtime Redis fan-out enabled on channel ${this.channel}`);
+    } catch (error) {
+      this.logger.warn(
+        `Failed to init realtime Redis fan-out: ${error instanceof Error ? error.message : 'unknown'}`,
+      );
+      await Promise.allSettled([this.safeClose(this.redisSubscriber), this.safeClose(this.redisPublisher)]);
+      this.redisPublisher = null;
+      this.redisSubscriber = null;
+    }
+  }
+
+  private async safeClose(client: RedisClientType | null) {
+    if (!client) return;
+    try {
+      if (client.isOpen) await client.quit();
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/src/redis/redis-pubsub.ts

@@ -0,0 +1,179 @@
+import { Logger } from '@nestjs/common';
+import { createClient, type RedisClientType } from 'redis';
+
+export type RedisPubSub = {
+  /** `false` means no Redis: publishing is a no-op and this process runs single-instance. */
+  readonly enabled: boolean;
+  publish(payload: unknown): Promise<void>;
+  close(): Promise<void>;
+};
+
+export type CreateRedisPubSubOptions = {
+  channel: string;
+  logger: Logger;
+  /** Used in log lines, e.g. `ai instruction` -> "Redis ai instruction sync enabled...". */
+  label: string;
+  onMessage: (raw: string) => void | Promise<void>;
+  /** Defaults to `REDIS_URL`, read at call time so tests can set it before init. */
+  url?: string;
+  errorLogCooldownMs?: number;
+};
+
+const DEFAULT_ERROR_LOG_COOLDOWN_MS = 30000;
+
+/**
+ * A connection failure must never take the client's data path down with it, so
+ * every error path here degrades to `INERT` and lets the caller keep serving
+ * from its local cache.
+ */
+const INERT: RedisPubSub = {
+  enabled: false,
+  async publish() {
+    // no-op
+  },
+  async close() {
+    // no-op
+  },
+};
+
+/**
+ * `createClient` rejects with an `AggregateError` whose own `message` is empty,
+ * so logging it directly yields "Redis error: " with nothing after it.
+ */
+function extractRedisErrorMessage(error: unknown): string {
+  if (error instanceof AggregateError && error.errors?.length) {
+    return error.errors
+      .map((e) => (e instanceof Error ? e.message || e.toString() : String(e)))
+      .join('; ');
+  }
+  if (error instanceof Error) {
+    return error.message || error.toString();
+  }
+  return String(error);
+}
+
+async function safeClose(client: RedisClientType | null) {
+  if (!client || !client.isOpen) {
+    return;
+  }
+
+  try {
+    await client.quit();
+  } catch {
+    try {
+      client.disconnect();
+    } catch {
+      // ignore shutdown errors
+    }
+  }
+}
+
+/**
+ * Publisher/subscriber pair on a single channel, mirroring the settings-sync
+ * pattern. Never throws: without a URL — or if the connection fails — it returns
+ * an inert handle and logs once.
+ *
+ * A dedicated subscriber connection is required: node-redis v4 puts a client in
+ * subscriber mode, where it can no longer issue regular commands.
+ */
+export async function createRedisPubSub(
+  options: CreateRedisPubSubOptions,
+): Promise<RedisPubSub> {
+  const { channel, logger, label, onMessage } = options;
+  const url = String(options.url ?? process.env.REDIS_URL ?? '').trim();
+
+  if (!url) {
+    logger.log(`Redis ${label} sync disabled because REDIS_URL is not configured.`);
+    return INERT;
+  }
+
+  const cooldownMs = Math.max(
+    1000,
+    Number(options.errorLogCooldownMs || DEFAULT_ERROR_LOG_COOLDOWN_MS),
+  );
+  // A Redis outage fires `error` on every reconnect attempt; unthrottled that
+  // buries every other log line in the pod.
+  const lastErrorLogAt: Record<'subscriber' | 'publisher', number> = {
+    subscriber: 0,
+    publisher: 0,
+  };
+
+  const logClientError = (kind: 'subscriber' | 'publisher', error: unknown) => {
+    const now = Date.now();
+    if (now - lastErrorLogAt[kind] < cooldownMs) {
+      return;
+    }
+    lastErrorLogAt[kind] = now;
+    logger.warn(`Redis ${label} ${kind} error: ${extractRedisErrorMessage(error)}`);
+  };
+
+  let subscriber: RedisClientType | null = null;
+  let publisher: RedisClientType | null = null;
+
+  try {
+    const clientOptions = {
+      url,
+      socket: {
+        reconnectStrategy: (retries: number) => Math.min(retries * 250, 5000),
+      },
+    };
+
+    subscriber = createClient(clientOptions) as RedisClientType;
+    publisher = createClient(clientOptions) as RedisClientType;
+
+    // Registered before `connect` so a failure during the handshake is handled
+    // rather than thrown as an unhandled 'error' event.
+    subscriber.on('error', (error) => logClientError('subscriber', error));
+    publisher.on('error', (error) => logClientError('publisher', error));
+
+    await subscriber.connect();
+    await publisher.connect();
+    await subscriber.subscribe(channel, async (message) => {
+      try {
+        await onMessage(message);
+      } catch (error) {
+        logger.warn(
+          `Failed to handle Redis ${label} message: ${extractRedisErrorMessage(error)}`,
+        );
+      }
+    });
+
+    logger.log(`Redis ${label} sync enabled on channel ${channel}`);
+  } catch (error) {
+    logger.warn(
+      `Failed to initialize Redis ${label} sync: ${extractRedisErrorMessage(error)}`,
+    );
+
+    await Promise.allSettled([safeClose(subscriber), safeClose(publisher)]);
+
+    return INERT;
+  }
+
+  const activePublisher = publisher;
+  const activeSubscriber = subscriber;
+  let closed = false;
+
+  return {
+    enabled: true,
+    async publish(payload: unknown) {
+      if (closed || !activePublisher.isOpen) {
+        return;
+      }
+
+      try {
+        await activePublisher.publish(channel, JSON.stringify(payload));
+      } catch (error) {
+        logger.warn(
+          `Failed to publish Redis ${label} message: ${extractRedisErrorMessage(error)}`,
+        );
+      }
+    },
+    async close() {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      await Promise.allSettled([safeClose(activeSubscriber), safeClose(activePublisher)]);
+    },
+  };
+}

package/src/setting/dto/create.dto.ts

@@ -1,5 +1,13 @@
+import { SettingComponentEnum } from '@hed-hog/api-types';
 import { IsBoolean, IsIn, IsInt, IsOptional, IsString, Length, ValidationArguments } from 'class-validator';
 
+/**
+ * Derived from the enum instead of a literal list: the previous hardcoded list
+ * had drifted and was rejecting `input-duration`, `input-bytes` and
+ * `entity-picker`, which already existed in the database.
+ */
+const SETTING_COMPONENTS = Object.values(SettingComponentEnum);
+
 export class CreateDTO {
   @IsString({ message: (args: ValidationArguments) => `${args.property} must be a string` })
   @Length(0, 255, { message: (args: ValidationArguments) => `${args.property} must be at most 255 characters long` })
@@ -11,10 +19,13 @@ export class CreateDTO {
   })
   type: string;
 
+  // Kept in sync with the `component` enum in
+  // libraries/core/hedhog/table/setting.yaml and SettingComponentEnum.
   @IsOptional()
   @IsString({ message: (args: ValidationArguments) => `${args.property} must be a string` })
-  @IsIn(['input-text', 'input-number', 'input-secret', 'input-file', 'input-tags', 'combobox', 'radio', 'color-picker', 'switch', 'checkbox'], { 
-    message: (args: ValidationArguments) => `${args.property} must be one of: input-text, input-number, input-secret, input-file, input-tags, combobox, radio, color-picker, switch, checkbox` 
+  @IsIn(SETTING_COMPONENTS, {
+    message: (args: ValidationArguments) =>
+      `${args.property} must be one of: ${SETTING_COMPONENTS.join(', ')}`,
   })
   component: string;
 

package/src/setting/setting.service.spec.ts

@@ -236,6 +236,62 @@ describe('SettingService', () => {
     });
   });
 
+  describe('ensureCacheVersionFresh', () => {
+    // Rajadas de leitura (ex.: lote de uploads de segmentos HLS) chegavam juntas antes de
+    // `lastSettingsVersionCheckAt` avançar e cada uma abria sua própria dupla de queries,
+    // ocupando o pool de conexões inteiro durante a conversão de vídeo.
+    it('deduplica checagens simultâneas em uma única ida ao banco', async () => {
+      const { service, deps } = makeService();
+      let resolveQuery: (rows: unknown[]) => void = () => {};
+      const pendingQuery = new Promise<unknown[]>((resolve) => {
+        resolveQuery = resolve;
+      });
+      deps.prisma.$queryRawUnsafe.mockReturnValue(pendingQuery);
+
+      const checks = Promise.all(
+        Array.from({ length: 5 }, () => (service as any).ensureCacheVersionFresh()),
+      );
+      resolveQuery([{ version: 1 }]);
+      await checks;
+
+      expect(deps.prisma.$queryRawUnsafe).toHaveBeenCalledTimes(1);
+    });
+
+    it('garante a linha de estado uma vez só, não a cada checagem', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.$queryRawUnsafe.mockResolvedValue([{ version: 1 }]);
+      jest.useFakeTimers();
+
+      await (service as any).ensureCacheVersionFresh();
+      jest.advanceTimersByTime(60_000);
+      await (service as any).ensureCacheVersionFresh();
+
+      expect(deps.prisma.$queryRawUnsafe).toHaveBeenCalledTimes(2);
+      expect(deps.prisma.$executeRawUnsafe).toHaveBeenCalledTimes(1);
+    });
+
+    it('limpa o cache quando a versão do banco avança', async () => {
+      const { service, deps } = makeService();
+      service.setCache({ flag: true });
+      deps.prisma.$queryRawUnsafe.mockResolvedValue([{ version: 9 }]);
+
+      await (service as any).ensureCacheVersionFresh();
+
+      expect((service as any).cachedSettings).toEqual({});
+      expect((service as any).localSettingsVersion).toBe(9);
+    });
+
+    it('libera o dedup mesmo quando a checagem falha', async () => {
+      const { service, deps } = makeService();
+      deps.prisma.$queryRawUnsafe.mockRejectedValueOnce(new Error('too many clients'));
+
+      await expect((service as any).ensureCacheVersionFresh()).rejects.toThrow(
+        'too many clients',
+      );
+      expect((service as any).settingsVersionCheckInFlight).toBeNull();
+    });
+  });
+
   describe('getEffectiveSettings', () => {
     it('coage overrides do usuário conforme tipo global', async () => {
       const { service } = makeService();

package/src/setting/setting.service.ts

@@ -51,6 +51,8 @@ export class SettingService implements OnModuleInit, OnModuleDestroy {
   );
   private localSettingsVersion = 0;
   private lastSettingsVersionCheckAt = 0;
+  private settingsVersionCheckInFlight: Promise<void> | null = null;
+  private settingsVersionStateEnsured = false;
   private redisPublisher: RedisClientType | null = null;
   private redisSubscriber: RedisClientType | null = null;
   private readonly redisErrorLogCooldownMs = Math.max(
@@ -208,11 +210,18 @@ export class SettingService implements OnModuleInit, OnModuleDestroy {
   }
 
   private async ensureSettingsVersionState() {
+    // A linha é criada uma vez e nunca some; repetir o INSERT a cada checagem de versão
+    // dobrava as queries de um caminho que roda a cada 5s em todo processo.
+    if (this.settingsVersionStateEnsured) {
+      return;
+    }
+
     await this.prismaService.$executeRawUnsafe(`
       INSERT INTO "setting_runtime_state" ("scope", "version", "updated_at")
       VALUES ('global', 0, NOW())
       ON CONFLICT ("scope") DO NOTHING
     `);
+    this.settingsVersionStateEnsured = true;
   }
 
   private parseVersionValue(value: unknown): number {
@@ -272,8 +281,23 @@ export class SettingService implements OnModuleInit, OnModuleDestroy {
       return;
     }
 
+    // `lastSettingsVersionCheckAt` só avança depois do await, então uma rajada de leituras
+    // paralelas (ex.: lote de uploads de segmentos HLS) disparava a mesma dupla de queries
+    // uma vez por chamada e ocupava o pool inteiro. Todas passam a esperar a mesma checagem.
+    if (this.settingsVersionCheckInFlight) {
+      return this.settingsVersionCheckInFlight;
+    }
+
+    this.settingsVersionCheckInFlight = this.runSettingsVersionCheck(now).finally(() => {
+      this.settingsVersionCheckInFlight = null;
+    });
+
+    return this.settingsVersionCheckInFlight;
+  }
+
+  private async runSettingsVersionCheck(startedAt: number) {
     const currentVersion = await this.getSettingsVersionFromDatabase();
-    this.lastSettingsVersionCheckAt = now;
+    this.lastSettingsVersionCheckAt = startedAt;
 
     if (currentVersion > this.localSettingsVersion) {
       this.localSettingsVersion = currentVersion;
@@ -471,12 +495,15 @@ export class SettingService implements OnModuleInit, OnModuleDestroy {
       'password-min-numbers',
       'password-min-uppercase',
       'password-min-length',
+      'password-max-age-days',
+      'password-block-leaked',
       'mfa-email-code-length',
       'mcp-enabled',
       'date-format',
       'time-format',
       'timezone',
       'menu-width',
+      'pagination-page-sizes',
       'maintenance-mode-enabled',
       'providers',
       'oauth-facebook-enabled',
@@ -489,6 +516,7 @@ export class SettingService implements OnModuleInit, OnModuleDestroy {
       'disable-authentication-with-email-and-password',
       'contact-allow-company-registration',
       'operations.comment-edit-window',
+      'vaults.auto-lock-seconds',
       'lms-video-conversion-enabled',
       'lms-video-frame-capture-interval-seconds',
       'lms-error-modal-enabled',

package/src/user/dto/create-with-email-and-password.dto.ts

@@ -1,5 +1,5 @@
 import { getLocaleText } from '@hed-hog/api-locale';
-import { IsString } from 'class-validator';
+import { IsOptional, IsString } from 'class-validator';
 import { IsEmailWithSettings } from '../../validators/is-email-with-settings.validator';
 import { IsStrongPasswordWithSettings } from '../../validators/is-strong-password-with-settings.validator';
 
@@ -18,4 +18,9 @@ export class CreateWithEmailAndPasswordDTO {
 
   @IsString({ message: (args) => getLocaleText('validation.nameRequired', args.value) })
   name: string;
+
+  /** Chave do app de origem (ex.: "class"), usada para resolver o nome de marca no e-mail de confirmacao. */
+  @IsOptional()
+  @IsString()
+  app?: string;
 }

package/src/user/dto/query-user-mail-list.dto.ts

@@ -0,0 +1,10 @@
+import { PaginationDTO } from '@hed-hog/api-pagination';
+import { Transform } from 'class-transformer';
+import { IsIn, IsOptional } from 'class-validator';
+
+export class QueryUserMailListDTO extends PaginationDTO {
+  @IsOptional()
+  @Transform(({ value }) => String(value ?? '').trim().toLowerCase())
+  @IsIn(['all', 'received', 'read', 'error'])
+  status?: 'all' | 'received' | 'read' | 'error';
+}

package/src/user/user-credential.util.ts

@@ -0,0 +1,35 @@
+/**
+ * Regra única de "reset de senha pendente": credencial de senha ativa
+ * (não revogada) marcada com requires_reset.
+ */
+export const PENDING_PASSWORD_RESET_WHERE = {
+  some: {
+    type: 'password',
+    requires_reset: true,
+    revoked_at: null,
+  },
+} as const;
+
+export function hasPendingPasswordReset(user: any): boolean {
+  return Boolean(
+    user?.user_credential?.some(
+      (credential) =>
+        credential?.type === 'password' &&
+        credential?.requires_reset === true &&
+        !credential?.revoked_at,
+    ),
+  );
+}
+
+/**
+ * Usuários criados/autenticados apenas via provedor externo (ex: Microsoft
+ * Entra ID) nunca têm uma credencial de senha ativa — não faz sentido
+ * oferecer o fluxo de "esqueci a senha" para eles.
+ */
+export function hasPasswordCredential(user: any): boolean {
+  return Boolean(
+    user?.user_credential?.some(
+      (credential) => credential?.type === 'password' && !credential?.revoked_at,
+    ),
+  );
+}

package/src/user/user.controller.ts

@@ -12,6 +12,7 @@ import {
   ParseIntPipe,
   Patch,
   Post,
+  Query,
   Req,
   Res,
   UploadedFile,
@@ -22,6 +23,7 @@ import { FileInterceptor } from '@nestjs/platform-express';
 import { Request } from 'express';
 import { DeleteDTO } from '../dto/delete.dto';
 import { CreateWithEmailAndPasswordDTO } from './dto/create-with-email-and-password.dto';
+import { QueryUserMailListDTO } from './dto/query-user-mail-list.dto';
 import { ResetPasswordDTO } from './dto/reset-password.dto';
 import { UpdateDTO } from './dto/update.dto';
 import { UserService } from './user.service';
@@ -35,8 +37,8 @@ export class UserController {
   ) { }
 
   @Get()
-  async list(@Pagination() paginationParams) {
-    return this.userService.list(paginationParams);
+  async list(@Pagination() paginationParams, @Query('filter') filter?: string) {
+    return this.userService.list(paginationParams, filter);
   }
 
   @Get(':userId')
@@ -154,6 +156,19 @@ export class UserController {
     return this.userService.listUserChangeLogs(locale, userId, paginationParams);
   }
 
+  @Get(':userId/mail')
+  async listMails(
+    @Param('userId', ParseIntPipe) userId: number,
+    @Pagination() paginationParams,
+    @Query() query: QueryUserMailListDTO,
+    @Locale() locale: string,
+  ) {
+    return this.userService.listUserMails(locale, userId, {
+      ...paginationParams,
+      status: query.status,
+    });
+  }
+
   @Post(':userId/role/:roleId')
   async assignRoleToUser(
     @Param('userId', ParseIntPipe) userId: number,