@abgov/nx-adsp 13.11.1 → 13.12.1

package/README.md

@@ -265,7 +265,7 @@ have a tenant yet? That picker also offers a **+ Create a new tenant** choice
 `tenant-service-admin`, and (unless `tenant-service-admin`) that doesn't already own a tenant (one
 per admin email). Picking it prompts for a name and waits for the new realm to finish provisioning
 before continuing the login as that tenant. Requires `@abgov/adsp-cli` ^1.4.0+ (this plugin pins
-^1.5.2 or later).
+^1.6.0 or later).
 
 ## Agent consultation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abgov/nx-adsp",
-  "version": "13.11.1",
+  "version": "13.12.1",
   "license": "Apache-2.0",
   "main": "src/index.js",
   "description": "Government of Alberta - Nx plugin for ADSP apps.",

package/src/generators/express-service/express-service.spec.ts

@@ -192,6 +192,13 @@ describe('Express Service Generator', () => {
     const database = host.read('apps/test/src/database.ts').toString();
     expect(database).toContain('drizzle-orm/node-postgres');
     expect(database).toContain('closeDatabase');
+    expect(database).toContain('isDatabaseReady');
+
+    // Readiness (DB-checked) is wired up separately from liveness — a DB
+    // outage should hold traffic, not restart a pod that can't fix it.
+    const mainTs = host.read('apps/test/src/main.ts').toString();
+    expect(mainTs).toContain('isDatabaseReady');
+    expect(mainTs).toContain("app.get('/health/ready'");
 
     // webpack emits a second bundle (migrate.js) for the deploy init container.
     const webpackConfig = host.read('apps/test/webpack.config.js').toString();
@@ -233,6 +240,11 @@ describe('Express Service Generator', () => {
 
     const database = host.read('apps/test/src/database.ts').toString();
     expect(database).toContain('mongoose');
+    expect(database).toContain('isDatabaseReady');
+
+    const mainTs = host.read('apps/test/src/main.ts').toString();
+    expect(mainTs).toContain('isDatabaseReady');
+    expect(mainTs).toContain("app.get('/health/ready'");
 
     const config = readProjectConfiguration(host, 'test');
     expect(config.targets['dev-db']).toBeTruthy();
@@ -249,6 +261,12 @@ describe('Express Service Generator', () => {
     expect(host.exists('apps/test/src/database.ts')).toBeFalsy();
     expect(host.exists('apps/test/scripts/dev-db.sh')).toBeFalsy();
 
+    // No database to check readiness against — don't emit a route that
+    // would always report ready regardless of anything real.
+    const mainTs = host.read('apps/test/src/main.ts').toString();
+    expect(mainTs).not.toContain('/health/ready');
+    expect(mainTs).not.toContain('isDatabaseReady');
+
     const config = readProjectConfiguration(host, 'test');
     expect(config.targets['dev-db']).toBeFalsy();
     expect(

package/src/generators/express-service/files/AGENTS.md__tmpl__

@@ -68,6 +68,17 @@ need project-scoped MCP enabled. The server runs via `npx` and needs no credenti
 | `src/database.ts` | Mongoose connection helpers — `connectDatabase()` and `disconnectDatabase()` |
 <% } %>
 
+## Health and readiness checks
+
+`/health` and (<% if (database !== 'none') { %>already, since this service has a database<% } else { %>if this service later gains a database or another required dependency<% } %>) `/health/ready` are two different questions, mapped to the two different OpenShift probes for a reason — conflating them into one endpoint means an outage in a downstream dependency gets treated as "restart this pod," which does not fix the outage and just adds a restart loop on top of it:
+
+- **`/health` — liveness: is the process itself up.** Stays dependency-free on purpose. Don't add a check here for anything this service depends on but doesn't own.
+<% if (database !== 'none') { %>
+- **`/health/ready` — readiness: can this pod actually serve requests right now.** Already checks the database (`isDatabaseReady()` in `src/database.ts`) — a real round-trip query, not just a pool-state flag. **Extend this handler, not `/health`, for any other resource this service can't function without** — another required downstream API, a message broker, a required ADSP capability beyond what `healthCheck()` already covers — following the same reasoning: a dependency being down should hold traffic (503, readiness), not trigger a pod restart (liveness) that can't fix a problem outside this pod.
+<% } else { %>
+- If this service later gains a database or another hard dependency, add a `/health/ready` route that checks it (see `@abgov/nx-adsp:express-service --database postgres|mongo` for the shipped pattern) and point the deployment's `readinessProbe` at it instead of `/health` — don't check dependencies from the liveness route.
+<% } %>
+
 ## SDK capabilities
 
 `initializeService()` returns `capabilities`:

package/src/generators/express-service/files/src/main.ts__tmpl__

@@ -7,9 +7,9 @@ import helmet from 'helmet';
 import passport from 'passport';
 import { Strategy as AnonymousStrategy } from 'passport-anonymous';
 <% if (database === 'postgres') { %>
-import { closeDatabase } from './database';
+import { closeDatabase, isDatabaseReady } from './database';
 <% } else if (database === 'mongo') { %>
-import { connectDatabase, disconnectDatabase } from './database';
+import { connectDatabase, disconnectDatabase, isDatabaseReady } from './database';
 <% } %>
 import { environment } from './environment';
 import { exampleEventDefinition } from './events';
@@ -54,10 +54,34 @@ async function initializeApp() {
   passport.use('tenant', tenantStrategy);
   app.use(passport.initialize());
 
+  // Liveness — is the process itself up. Deliberately stays dependency-free
+  // (platform reachability, not this app's own resources) so an outage in a
+  // downstream dependency doesn't get treated as "restart this pod," which
+  // wouldn't fix the outage and would just cause a needless restart loop.
   app.get('/health', async (_req, res) => {
     const platform = await healthCheck();
     res.json({ ...platform });
   });
+<% if (database !== 'none') { %>
+  // Readiness — can this pod actually serve requests right now. Checks the
+  // database because this service can't do anything useful without it; 503
+  // tells the platform to hold traffic rather than route it somewhere that
+  // will 500. Extend this handler (not /health above) for any other resource
+  // this service can't function without — another required downstream API,
+  // a message broker, etc. — following the same "hold traffic, don't
+  // restart" reasoning; see AGENTS.md's "Health and readiness checks".
+  app.get('/health/ready', async (_req, res) => {
+    try {
+      await isDatabaseReady();
+      res.json({ ready: true });
+    } catch (err) {
+      res.status(503).json({
+        ready: false,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  });
+<% } %>
 
   // Generated once from the routers' registry.registerPath() calls (see
   // routes/example.ts) — every router imported above has already registered
@@ -85,6 +109,9 @@ async function initializeApp() {
       _links: {
         self: { href: new URL(req.originalUrl, rootUrl).href },
         health: { href: new URL('/health', rootUrl).href },
+<% if (database !== 'none') { %>
+        ready: { href: new URL('/health/ready', rootUrl).href },
+<% } %>
         api: { href: new URL('/<%= projectName %>/v1', rootUrl).href },
         docs: { href: new URL('/swagger/docs/v1', rootUrl).href },
       },

package/src/generators/express-service/files-mongo/src/database.ts__tmpl__

@@ -9,3 +9,13 @@ export async function connectDatabase(): Promise<void> {
 export async function disconnectDatabase(): Promise<void> {
   await mongoose.disconnect();
 }
+
+// A real ping, not just `readyState === 1` — the connection can report
+// "connected" while actually stale. Used by /health/ready, not by `main.ts`
+// directly.
+export async function isDatabaseReady(): Promise<void> {
+  if (!mongoose.connection.db) {
+    throw new Error('Database connection not established.');
+  }
+  await mongoose.connection.db.admin().ping();
+}

package/src/generators/express-service/files-postgres/src/database.ts__tmpl__

@@ -1,3 +1,4 @@
+import { sql } from 'drizzle-orm';
 import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
@@ -12,3 +13,10 @@ const pool = new Pool({ connectionString: environment.DATABASE_URL });
 export const db = drizzle(pool, { schema });
 
 export const closeDatabase = (): Promise<void> => pool.end();
+
+// A trivial round-trip query, not just a pool-state check — proves the
+// database is actually reachable and answering, the same reason `pg_isready`
+// exists. Used by /health/ready, not by `main.ts` directly.
+export const isDatabaseReady = async (): Promise<void> => {
+  await db.execute(sql`SELECT 1`);
+};