@lenne.tech/nest-server 11.32.3 → 11.33.0

package/src/core/common/helpers/graceful-shutdown.helper.ts

@@ -0,0 +1,116 @@
+import { INestApplication, Logger } from '@nestjs/common';
+
+import { ConfigService } from '../services/config.service';
+
+/** Signals an orchestrator uses to ask a container to stop */
+const SHUTDOWN_SIGNALS: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];
+
+/**
+ * A delay this long is almost certainly a typo (seconds written as milliseconds, or the other way
+ * round). Orchestrators SIGKILL after their grace period anyway — typically 10-30s — so a longer
+ * wait cannot be honored, it only guarantees the ungraceful ending it was meant to avoid.
+ */
+const MAX_SHUTDOWN_DELAY_MS = 60_000;
+
+/**
+ * Above this, the delay is very likely longer than what actually gets to run.
+ *
+ * The cap above catches typos; it does NOT describe the real ceiling, and the gap between the two
+ * is where this silently breaks. Three separate limits sit BELOW the 60s cap:
+ * Docker/Compose `stop_grace_period` defaults to 10s, Kubernetes `terminationGracePeriodSeconds`
+ * to 30s, and this framework's own `installProcessDiagnostics()` arms a 30s watchdog that calls
+ * `exit(1)`. A delay of, say, 45s passes the cap without a word and is then force-killed mid-wait:
+ * no drain, and not one `onModuleDestroy` / `onApplicationShutdown` hook runs — precisely the
+ * ending the delay exists to prevent. Warning here means the dangerous band is no longer silent.
+ *
+ * The delay is only part of the budget: whatever `app.close()` needs to drain comes after it.
+ */
+const SHUTDOWN_DELAY_ADVISORY_MS = 10_000;
+
+/**
+ * Install signal handling that keeps the app healthy for `IServerOptions.shutdownDelayMs`
+ * before shutting it down, then closes it cleanly.
+ *
+ * **Why this is not a NestJS lifecycle hook.** The obvious place looks like
+ * `beforeApplicationShutdown`, but Nest's `close()` runs
+ * `onModuleDestroy` → `beforeApplicationShutdown` → dispose (close the HTTP server) →
+ * `onApplicationShutdown`. A delay in that hook therefore waits AFTER every module has been
+ * destroyed while the socket is still accepting — so the instance keeps taking traffic with its
+ * services already torn down. That is worse than not waiting at all, which is why the wait has to
+ * happen before `close()` is entered, i.e. in the signal handler.
+ *
+ * **What the delay is for.** An orchestrator sends SIGTERM and deregisters the instance from the
+ * load balancer at the same moment, but deregistration propagates asynchronously — for a beat,
+ * requests still arrive. Staying fully healthy through that beat is what lets them be answered
+ * instead of dropped.
+ *
+ * Without a configured delay this is exactly `app.enableShutdownHooks()`, which is what the
+ * framework did before.
+ *
+ * @param app the Nest application to shut down
+ * @returns the same app, so it can be chained
+ */
+export function installGracefulShutdown<T extends INestApplication>(app: T): T {
+  const logger = new Logger('GracefulShutdown');
+  const configured = ConfigService.getFastButReadOnly<number | undefined>('shutdownDelayMs');
+  const delayMs = typeof configured === 'number' && configured > 0 ? configured : 0;
+
+  if (!delayMs) {
+    // Nest's own handling: close immediately on a signal, running every lifecycle hook.
+    app.enableShutdownHooks();
+    return app;
+  }
+
+  if (delayMs > MAX_SHUTDOWN_DELAY_MS) {
+    logger.warn(
+      `shutdownDelayMs is ${delayMs}ms, which exceeds the ${MAX_SHUTDOWN_DELAY_MS}ms cap and is longer than a typical ` +
+        `orchestrator grace period — capping it, since a longer wait only ends in SIGKILL.`,
+    );
+  } else if (delayMs > SHUTDOWN_DELAY_ADVISORY_MS) {
+    logger.warn(
+      `shutdownDelayMs is ${delayMs}ms. Keep it well below your orchestrator's grace period AND leave room for the ` +
+        'drain that follows it — Docker/Compose stop_grace_period defaults to 10s, Kubernetes ' +
+        'terminationGracePeriodSeconds to 30s, and installProcessDiagnostics() force-exits after 30s. Exceeding any ' +
+        'of them means the process is killed mid-wait and no shutdown hook runs at all.',
+    );
+  }
+  const effectiveDelayMs = Math.min(delayMs, MAX_SHUTDOWN_DELAY_MS);
+
+  // Deliberately NOT enableShutdownHooks(): Nest would install its own listener for the same
+  // signals and close the app immediately, in parallel with the wait below.
+  let shuttingDown = false;
+  // Hoisted out of the handler so a second signal can CANCEL the pending wait. Left inside, the
+  // timer stayed armed and fired after the impatient close had already run, calling app.close()
+  // a second time and re-running every onApplicationShutdown hook against a closed app.
+  let timer: NodeJS.Timeout | undefined;
+
+  const handle = (signal: NodeJS.Signals): void => {
+    if (shuttingDown) {
+      // A second signal means someone is impatient. Stop waiting and close now.
+      logger.warn(`${signal} received again — closing immediately`);
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      void app.close();
+      return;
+    }
+    shuttingDown = true;
+    logger.log(`${signal} received — staying healthy for ${effectiveDelayMs}ms so the load balancer can deregister`);
+
+    timer = setTimeout(() => {
+      app
+        .close()
+        .then(() => logger.log('Shutdown complete'))
+        .catch((error) => logger.error(`Shutdown failed: ${error instanceof Error ? error.message : 'Unknown error'}`));
+    }, effectiveDelayMs);
+    // The listening server keeps the loop alive on its own; this timer must not be what holds it.
+    timer.unref?.();
+  };
+
+  for (const signal of SHUTDOWN_SIGNALS) {
+    process.on(signal, handle);
+  }
+
+  return app;
+}

package/src/core/common/helpers/project-name.helper.ts

@@ -0,0 +1,71 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Cached slug for the current process — package.json is read at most once.
+ *
+ * `undefined` means "not read yet"; a string (including the fallback) means "read".
+ */
+let cachedProjectSlug: string | undefined;
+
+/** Used when package.json is unreadable or carries no usable name */
+const FALLBACK_SLUG = 'nest-server';
+
+/**
+ * The project's package name, reduced to a form that is safe as a key namespace.
+ *
+ * This exists so framework-managed keys in SHARED infrastructure (Redis today) are namespaced per
+ * application instead of per framework. A constant default is fine until two applications point at
+ * one Redis — a normal staging setup — at which point identically-named cron jobs, rate-limit
+ * counters and diagnostic buffers of different applications land on the same keys. That failure is
+ * silent: one app's scheduler consumes the other's jobs, and the job simply never runs where it was
+ * defined.
+ *
+ * Deliberately NOT the display name from `getProjectAppName()` in the better-auth config: that one
+ * is Title Case with an environment suffix ("My App (Local)"), which is right for a 2FA issuer and
+ * wrong for a key prefix.
+ *
+ * @returns lower-case slug, scope stripped (`@acme/api` → `acme-api`), or `nest-server` as fallback
+ */
+export function getProjectSlug(): string {
+  if (cachedProjectSlug !== undefined) {
+    return cachedProjectSlug;
+  }
+
+  cachedProjectSlug = FALLBACK_SLUG;
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf-8'));
+    if (raw?.name && typeof raw.name === 'string') {
+      const slug = slugify(raw.name);
+      if (slug) {
+        cachedProjectSlug = slug;
+      }
+    }
+  } catch {
+    // Unreadable package.json is not worth failing a boot over — the fallback keeps the previous
+    // behavior, which is exactly what a consumer without a readable manifest had before.
+  }
+
+  return cachedProjectSlug;
+}
+
+/** Reset the cache — tests only, so a fixture can vary the detected name */
+export function resetProjectSlugCache(): void {
+  cachedProjectSlug = undefined;
+}
+
+/**
+ * Reduce a package name to a key-safe slug.
+ *
+ * Colons are stripped rather than replaced because the framework uses `:` as its own key separator —
+ * a name containing one would otherwise invent a namespace level.
+ */
+function slugify(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/^@/, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}

package/src/core/common/interfaces/cron-job-config.interface.ts

@@ -23,6 +23,22 @@ export interface CronJobConfig<OC extends CronOnCompleteCommand | null = null, C
    */
   disabled?: boolean;
 
+  /**
+   * Whether the job is deduplicated across replicas in multi-replica deployments.
+   *
+   * When enabled, only ONE replica executes each tick: via BullMQ job schedulers when
+   * Redis is configured, otherwise via a MongoDB lease per tick. The lease is BEST EFFORT —
+   * an unreachable lease store runs the tick everywhere rather than stopping all scheduled
+   * work, because a silent fleet-wide outage of every cron job is the worse failure.
+   *
+   * Set to `false` for jobs that must deliberately run on EVERY replica (e.g. refreshing a
+   * process-local cache), or to `true` to deduplicate via the MongoDB lease in a
+   * multi-replica deployment that runs without Redis.
+   *
+   * @default true when `redis` is configured, otherwise false (unchanged single-replica behavior)
+   */
+  distributed?: boolean;
+
   /**
    * A function that will fire when the job is complete, when it is stopped.
    */