@idevconn/create-icore 0.5.0 → 0.5.2

package/templates/libs/shared/src/__tests__/bootstrap.unit.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { bootstrapMicroservice } from '../bootstrap';
+
+interface FakeApp {
+  listen: () => Promise<void>;
+  close: () => Promise<void>;
+}
+
+function makeLogger() {
+  return { log: vi.fn(), warn: vi.fn(), error: vi.fn() };
+}
+
+const ORIG = { ...process.env };
+
+describe('bootstrapMicroservice', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    delete process.env['AUTH_TRANSPORT'];
+    delete process.env['NODE_ENV'];
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    Object.assign(process.env, ORIG);
+  });
+
+  it('redis in dev: retries with a banner instead of exiting, then binds when the broker appears', async () => {
+    process.env['AUTH_TRANSPORT'] = 'redis';
+    const logger = makeLogger();
+    const close = vi.fn().mockResolvedValue(undefined);
+    let attempts = 0;
+    const createApp = vi.fn(async (): Promise<FakeApp> => {
+      attempts += 1;
+      return {
+        // first attempt fails (broker down), second succeeds
+        listen:
+          attempts < 2 ? () => Promise.reject(new Error('ECONNREFUSED')) : () => Promise.resolve(),
+        close,
+      };
+    });
+
+    const done = bootstrapMicroservice('AUTH', createApp, logger);
+    // let the first attempt fail + the retry delay elapse
+    await vi.advanceTimersByTimeAsync(3000);
+    await done;
+
+    expect(createApp).toHaveBeenCalledTimes(2);
+    expect(close).toHaveBeenCalledTimes(1); // failed app cleaned up before retry
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.warn.mock.calls[0][0]).toContain('broker unreachable');
+    expect(logger.log).toHaveBeenCalledTimes(1); // "listening" on success
+  });
+
+  it('tcp: fails fast (process.exit) rather than retrying', async () => {
+    process.env['AUTH_TRANSPORT'] = 'tcp';
+    const logger = makeLogger();
+    const exit = vi.spyOn(process, 'exit').mockImplementation(((): never => {
+      throw new Error('__exit__');
+    }) as never);
+    const createApp = vi.fn(
+      async (): Promise<FakeApp> => ({
+        listen: () => Promise.reject(new Error('EADDRINUSE')),
+        close: () => Promise.resolve(),
+      }),
+    );
+
+    await expect(bootstrapMicroservice('AUTH', createApp, logger)).rejects.toThrow('__exit__');
+    expect(exit).toHaveBeenCalledWith(1);
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('production: fails fast even on a broker transport', async () => {
+    process.env['AUTH_TRANSPORT'] = 'redis';
+    process.env['NODE_ENV'] = 'production';
+    const logger = makeLogger();
+    const exit = vi.spyOn(process, 'exit').mockImplementation(((): never => {
+      throw new Error('__exit__');
+    }) as never);
+    const createApp = vi.fn(
+      async (): Promise<FakeApp> => ({
+        listen: () => Promise.reject(new Error('ECONNREFUSED')),
+        close: () => Promise.resolve(),
+      }),
+    );
+
+    await expect(bootstrapMicroservice('AUTH', createApp, logger)).rejects.toThrow('__exit__');
+    expect(exit).toHaveBeenCalledWith(1);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+});

package/templates/libs/shared/src/__tests__/transport.unit.test.ts

@@ -33,8 +33,12 @@ describe('buildTransport', () => {
     process.env.AUTH_REDIS_URL = 'redis://localhost:6379';
     const opts = buildTransport('AUTH');
     expect(opts.transport).toBe(Transport.REDIS);
-    const redis = opts.options as { url: string };
+    const redis = opts.options as { url: string; retryAttempts: number; retryDelay: number };
     expect(redis.url).toBe('redis://localhost:6379');
+    // Resilience: NestJS gives up (and app.listen() rejects) when retryAttempts
+    // is unset — an effectively-infinite retry keeps reconnecting instead.
+    expect(redis.retryAttempts).toBe(Number.POSITIVE_INFINITY);
+    expect(redis.retryDelay).toBeGreaterThan(0);
   });
 
   it('selects NATS when ${PREFIX}_TRANSPORT=nats', () => {
@@ -42,8 +46,16 @@ describe('buildTransport', () => {
     process.env.AUTH_NATS_URL = 'nats://localhost:4222,nats://localhost:4223';
     const opts = buildTransport('AUTH');
     expect(opts.transport).toBe(Transport.NATS);
-    const nats = opts.options as { servers: string[] };
+    const nats = opts.options as {
+      servers: string[];
+      reconnect: boolean;
+      maxReconnectAttempts: number;
+    };
     expect(nats.servers).toEqual(['nats://localhost:4222', 'nats://localhost:4223']);
+    // Resilience: reconnect forever once connected (the initial connect is left
+    // to reject so bootstrapMicroservice() can banner + retry).
+    expect(nats.reconnect).toBe(true);
+    expect(nats.maxReconnectAttempts).toBe(-1);
   });
 
   it('throws on unknown transport', () => {

package/templates/libs/shared/src/bootstrap.ts

@@ -0,0 +1,79 @@
+import { formatEnvBanner } from './env';
+
+interface MicroserviceLike {
+  listen: () => Promise<unknown>;
+  close: () => Promise<void>;
+}
+
+interface LoggerLike {
+  log: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string, trace?: unknown) => void;
+}
+
+const RETRY_DELAY_MS = 3000;
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Boots a microservice and binds its transport, surviving a broker that isn't
+ * up yet.
+ *
+ * NestJS `ServerRedis`/`ServerNats` REJECT `app.listen()` on the *initial*
+ * connect failure — the ioredis retryStrategy / NATS reconnect only governs
+ * re-connection after a first successful connect. So without this helper a MS
+ * would `process.exit(1)` whenever Redis/NATS is down on boot, even though the
+ * transport options ask for infinite retries.
+ *
+ * Behaviour (honours the "never crash on missing infra" rule):
+ *  - tcp transport, or NODE_ENV=production → fail fast: `process.exit(1)`.
+ *  - redis/nats in dev → log a boxed banner and retry `listen()` forever, so
+ *    the service idles until the broker appears, then binds automatically.
+ *
+ * `createApp` must construct a *fresh* app each call: a failed listen closes
+ * the transport's clients, so the next attempt needs a new instance.
+ */
+export async function bootstrapMicroservice(
+  prefix: string,
+  createApp: () => Promise<MicroserviceLike>,
+  logger: LoggerLike,
+): Promise<void> {
+  const transport = (process.env[`${prefix}_TRANSPORT`] ?? 'tcp').toLowerCase();
+  const isProd = process.env['NODE_ENV'] === 'production';
+  const failFast = transport === 'tcp' || isProd;
+
+  for (let attempt = 1; ; attempt++) {
+    let app: MicroserviceLike | undefined;
+    try {
+      app = await createApp();
+      await app.listen();
+      logger.log(`${prefix} microservice listening — transport=${transport}`);
+      return;
+    } catch (err) {
+      if (app) await app.close().catch(() => undefined);
+      const reason = err instanceof Error ? err.message : String(err);
+
+      if (failFast) {
+        logger.error(
+          `${prefix} microservice bootstrap failed`,
+          err instanceof Error ? err.stack : err,
+        );
+        process.exit(1);
+      }
+
+      logger.warn(
+        formatEnvBanner({
+          service: `${prefix} microservice`,
+          provider: transport,
+          missing: [],
+          envPath: `the service .env (${prefix}_${transport.toUpperCase()}_URL)`,
+          reason: `${reason} — retry ${attempt} in ${RETRY_DELAY_MS / 1000}s; idling until the ${transport} broker is reachable`,
+          headline: `⚠  ${prefix} microservice — ${transport} broker unreachable (idling, not crashing)`,
+        }),
+      );
+      await delay(RETRY_DELAY_MS);
+    }
+  }
+}

package/templates/libs/shared/src/index.ts

@@ -1,4 +1,5 @@
 export * from './env';
+export * from './bootstrap';
 export * from './abilities';
 export * from './jobs';
 export * from './strategies';

package/templates/libs/shared/src/strategies/__tests__/fake-auth.contract.unit.test.ts

@@ -1,5 +1,5 @@
 import { FakeAuthStrategy } from '../fakes/fake-auth';
-import { runAuthContract } from '../contract/auth-contract';
+import { runAuthContract } from './auth.contract.unit.test';
 
 runAuthContract('FakeAuthStrategy', () => new FakeAuthStrategy(), {
   getMagicLinkToken: (strategy, email) =>

package/templates/libs/shared/src/strategies/__tests__/fake-db.contract.unit.test.ts

@@ -1,4 +1,4 @@
 import { FakeDBStrategy } from '../fakes/fake-db';
-import { runDBContract } from '../contract/db-contract';
+import { runDBContract } from './db.contract.unit.test';
 
 runDBContract('FakeDBStrategy', () => new FakeDBStrategy());

package/templates/libs/shared/src/strategies/__tests__/fake-storage.contract.unit.test.ts

@@ -1,4 +1,4 @@
 import { FakeStorageStrategy } from '../fakes/fake-storage';
-import { runStorageContract } from '../contract/storage-contract';
+import { runStorageContract } from './storage.contract.unit.test';
 
 runStorageContract('FakeStorageStrategy', () => new FakeStorageStrategy());

package/templates/libs/shared/src/strategies/index.ts

@@ -1,7 +1,7 @@
 export * from './auth';
 export * from './storage';
 export * from './db';
-export * from './contract/auth-contract';
-export * from './contract/storage-contract';
-export * from './contract/db-contract';
 export * from './fakes';
+// NOTE: the strategy contract harness (runAuthContract / runStorageContract /
+// runDBContract) is intentionally NOT exported here — it is test-only code and
+// lives behind the '@icore/shared/testing' entry. See ../testing.ts.

package/templates/libs/shared/src/testing.ts

@@ -0,0 +1,14 @@
+// Test-only surface of @icore/shared.
+//
+// The strategy CONTRACT HARNESS lives here, NOT in the production `index.ts`:
+// it uses Vitest globals (describe/it/expect) and must never compile into the
+// shipped library. Import it from test files via '@icore/shared/testing'.
+//
+// The harness implementation sits under `strategies/__tests__/` so the prod
+// build (tsconfig.lib.json excludes `__tests__`) skips it entirely.
+export {
+  runAuthContract,
+  type AuthContractHelpers,
+} from './strategies/__tests__/auth.contract.unit.test';
+export { runStorageContract } from './strategies/__tests__/storage.contract.unit.test';
+export { runDBContract } from './strategies/__tests__/db.contract.unit.test';

package/templates/libs/shared/src/transport.ts

@@ -67,15 +67,37 @@ export function buildTransport(prefix: string): ClientOptions {
       // ioredis accepts a connection URL string; the NestJS RedisOptions type
       // exposes host/port fields but passes options directly to ioredis which
       // also accepts a url field at runtime.
+      //
+      // retryAttempts/retryDelay are mandatory for resilience: NestJS
+      // ServerRedis builds its ioredis retryStrategy from them, and when
+      // retryAttempts is unset it logs "retry attempts not specified", stops
+      // reconnecting, and `app.listen()` REJECTS → the MS process exits. With
+      // an effectively-infinite retry the initial connect stays pending and
+      // keeps reconnecting, so a not-yet-up Redis never crashes the service —
+      // it idles and attaches once Redis is reachable.
       return {
         transport: Transport.REDIS,
-        options: { url: required(`${prefix}_REDIS_URL`) },
+        options: {
+          url: required(`${prefix}_REDIS_URL`),
+          retryAttempts: Number.POSITIVE_INFINITY,
+          retryDelay: 2000,
+        },
       } as unknown as ClientOptions;
     case 'nats':
+      // reconnect/maxReconnectAttempts: -1 retries forever once connected, so a
+      // dropped broker re-attaches instead of giving up. The *initial* connect
+      // is intentionally allowed to reject when NATS is down on boot —
+      // bootstrapMicroservice() catches that, logs a banner, and retries, giving
+      // the same visible behaviour as the Redis transport above.
       return {
         transport: Transport.NATS,
-        options: { servers: required(`${prefix}_NATS_URL`).split(',') },
-      };
+        options: {
+          servers: required(`${prefix}_NATS_URL`).split(','),
+          reconnect: true,
+          maxReconnectAttempts: -1,
+          reconnectTimeWait: 2000,
+        },
+      } as unknown as ClientOptions;
     default:
       throw new Error(`Unknown transport: ${kind}`);
   }

package/templates/libs/shared/tsconfig.lib.json

@@ -3,7 +3,7 @@
   "compilerOptions": {
     "outDir": "../../dist/out-tsc",
     "declaration": true,
-    "types": ["node", "vitest/globals"]
+    "types": ["node"]
   },
   "include": ["src/**/*.ts"],
   "exclude": [
@@ -11,6 +11,8 @@
     "vite.config.mts",
     "vitest.config.ts",
     "vitest.config.mts",
+    "src/testing.ts",
+    "src/**/__tests__/**",
     "src/**/*.test.ts",
     "src/**/*.spec.ts",
     "src/**/*.test.tsx",

package/templates/libs/shared/vitest.config.mts

@@ -1,4 +1,4 @@
-import { defineConfig } from 'vitest/config';
+import { defineConfig, configDefaults } from 'vitest/config';
 import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
 import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
 
@@ -12,6 +12,16 @@ export default defineConfig(() => ({
     globals: true,
     environment: 'node',
     include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    // The strategy contract harness files only EXPORT reusable suites
+    // (runAuthContract / runStorageContract / runDBContract) — they hold no
+    // top-level tests, so Vitest must not try to run them directly. They follow
+    // the *.unit.test.ts naming so the prod build excludes them; the concrete
+    // `fake-*.contract.unit.test.ts` files (and the per-provider libs) invoke
+    // the harness.
+    exclude: [
+      ...configDefaults.exclude,
+      '**/strategies/__tests__/{auth,storage,db}.contract.unit.test.ts',
+    ],
     reporters: ['default'],
     coverage: {
       reportsDirectory: '../../coverage/libs/shared',

package/templates/libs/storage-strategies/cloudinary/src/lib/__tests__/cloudinary-storage.contract.unit.test.ts

@@ -1,4 +1,4 @@
-import { runStorageContract } from '@icore/shared';
+import { runStorageContract } from '@icore/shared/testing';
 import { CloudinaryStorageStrategy } from '../cloudinary-storage.strategy.js';
 import { createMockCloudinary } from '../testing/mock-cloudinary.js';
 

package/templates/libs/storage-strategies/firebase/src/lib/__tests__/firebase-storage.contract.unit.test.ts

@@ -1,4 +1,4 @@
-import { runStorageContract } from '@icore/shared';
+import { runStorageContract } from '@icore/shared/testing';
 import { FirebaseStorageStrategy } from '../firebase-storage.strategy.js';
 import { createMockFirebaseBucket } from '../testing/mock-firebase-storage.js';
 

package/templates/libs/storage-strategies/supabase/src/lib/__tests__/supabase-storage.contract.unit.test.ts

@@ -1,4 +1,4 @@
-import { runStorageContract } from '@icore/shared';
+import { runStorageContract } from '@icore/shared/testing';
 import { SupabaseStorageStrategy } from '../supabase-storage.strategy';
 import { createMockSupabaseStorageClient } from '../testing/mock-supabase-storage';
 

package/templates/tsconfig.base.json

@@ -14,6 +14,7 @@
     "paths": {
       "@icore/shared": ["./libs/shared/src/index.ts"],
       "@icore/shared/client": ["./libs/shared/src/client.ts"],
+      "@icore/shared/testing": ["./libs/shared/src/testing.ts"],
       "@icore/auth-supabase": ["./libs/auth-strategies/supabase/src/index.ts"],
       "@icore/auth-client": ["./libs/auth-client/src/index.ts"],
       "@icore/package.json": ["./package.json"],
@@ -29,7 +30,8 @@
       "@icore/payment-client": ["./libs/payment-client/src/index.ts"],
       "@icore/notes-client": ["./libs/notes-client/src/index.ts"],
       "@icore/jobs-client": ["./libs/jobs-client/src/index.ts"],
-      "@icore/vite-plugins": ["./libs/vite-plugins/src/index.d.mts"]
+      "@icore/vite-plugins": ["./libs/vite-plugins/src/index.d.mts"],
+      "@icore/firebase-admin": ["./libs/firebase-admin/src/index.ts"]
     }
   },
   "exclude": ["node_modules", "dist", ".nx"]