feat(example): wire dependency-checking /health into todo-api-cloudflare

Mirrors the new health endpoint design in the example:

- examples/todo-api-cloudflare/api/src/db/ping.ts (D1: SELECT 1 via
  c.env.DB.prepare('SELECT 1').first())
- examples/todo-api-cloudflare/api/src/routes/health.ts (same handler
  shape as the Workers template, but typed for the example's D1 binding)
- src/index.ts: drop inline /health handler, mount healthRoutes
- wrangler.toml [vars] and .dev.vars.example: add APP_VERSION and
  HEALTH_DB_TIMEOUT_MS
- tests/unit/health.test.ts: full mocked coverage matching the template

Also refactors pingDatabase in both the Workers template and the example
to take the binding directly (Hyperdrive | undefined / D1Database |
undefined) instead of the whole Hono Context — the Context<Bindings>
variance caused a typecheck error when the route's wider Bindings
included APP_VERSION/HEALTH_DB_TIMEOUT_MS. Decoupling db/ping.ts from
Hono's type also makes it easier to reuse outside HTTP handlers.

Example tests: 19/19 passing (7 health + 12 todos integration).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Paul Mulligan

examples/todo-api-cloudflare/api/.dev.vars.example

@@ -3,3 +3,5 @@
 #   cp .dev.vars.example .dev.vars
 
 ENVIRONMENT=development
+APP_VERSION=0.0.1
+HEALTH_DB_TIMEOUT_MS=2000

examples/todo-api-cloudflare/api/src/db/ping.ts

@@ -0,0 +1,9 @@
+export async function pingDatabase(db: D1Database | undefined): Promise<'connected' | 'disconnected'> {
+  if (!db) return 'disconnected';
+  try {
+    await db.prepare('SELECT 1').first();
+    return 'connected';
+  } catch {
+    return 'disconnected';
+  }
+}

examples/todo-api-cloudflare/api/src/index.ts

@@ -4,13 +4,16 @@ import { etag } from 'hono/etag';
 import { logger } from 'hono/logger';
 import { requestId } from 'hono/request-id';
 import { secureHeaders } from 'hono/secure-headers';
+import { healthRoutes } from './routes/health';
 import { todosRoutes } from './routes/todos';
 // Note: Response compression is handled automatically by Cloudflare's edge network.
 // No compress() middleware is needed for Workers deployments.
 
 interface Bindings {
   DB: D1Database;
   ENVIRONMENT: string;
+  APP_VERSION: string;
+  HEALTH_DB_TIMEOUT_MS: string;
 }
 
 const app = new Hono<{ Bindings: Bindings }>();
@@ -22,16 +25,8 @@ app.use('*', etag());
 app.use('*', secureHeaders());
 app.use('*', requestId());
 
-// --- Health check ---
-app.get('/health', (c) => {
-  return c.json({
-    status: 'ok',
-    requestId: c.get('requestId'),
-    timestamp: new Date().toISOString(),
-  });
-});
-
 // --- Routes ---
+app.route('/health', healthRoutes);
 app.route('/todos', todosRoutes);
 
 // --- Root ---

examples/todo-api-cloudflare/api/src/routes/health.ts

@@ -0,0 +1,35 @@
+import { Hono } from 'hono';
+import { pingDatabase } from '../db/ping';
+
+const startTime = Date.now();
+
+interface Bindings {
+  DB: D1Database;
+  APP_VERSION: string;
+  HEALTH_DB_TIMEOUT_MS: string;
+}
+
+export const healthRoutes = new Hono<{ Bindings: Bindings }>().get('/', async (c) => {
+  const timeoutMs = Number(c.env.HEALTH_DB_TIMEOUT_MS) || 2000;
+  const timeout = new Promise<'disconnected'>((resolve) =>
+    setTimeout(() => resolve('disconnected'), timeoutMs),
+  );
+
+  let database: 'connected' | 'disconnected';
+  try {
+    database = await Promise.race([pingDatabase(c.env.DB), timeout]);
+  } catch {
+    database = 'disconnected';
+  }
+
+  const status = database === 'connected' ? 'healthy' : 'unhealthy';
+  const body = {
+    status,
+    version: c.env.APP_VERSION ?? 'unknown',
+    uptime: Math.floor((Date.now() - startTime) / 1000),
+    timestamp: new Date().toISOString(),
+    requestId: c.get('requestId'),
+    checks: { database },
+  };
+  return c.json(body, status === 'healthy' ? 200 : 503);
+});

examples/todo-api-cloudflare/api/tests/unit/health.test.ts

@@ -1,24 +1,103 @@
-import { describe, it, expect } from 'vitest';
-import app from '../../src/index';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { Hono } from 'hono';
+import { requestId } from 'hono/request-id';
+import { pingDatabase } from '../../src/db/ping';
+import { healthRoutes } from '../../src/routes/health';
+
+vi.mock('../../src/db/ping', () => ({
+  pingDatabase: vi.fn(),
+}));
+
+interface HealthBody {
+  status: 'healthy' | 'unhealthy';
+  version: string;
+  uptime: number;
+  timestamp: string;
+  requestId: string;
+  checks: { database: 'connected' | 'disconnected' };
+}
+
+type TestEnv = {
+  APP_VERSION: string;
+  HEALTH_DB_TIMEOUT_MS: string;
+  DB: D1Database | undefined;
+};
+
+const env: TestEnv = {
+  APP_VERSION: '0.0.1',
+  HEALTH_DB_TIMEOUT_MS: '2000',
+  DB: undefined,
+};
+
+const makeApp = (): Hono<{ Bindings: TestEnv }> => {
+  const app = new Hono<{ Bindings: TestEnv }>();
+  app.use('*', requestId());
+  app.route('/health', healthRoutes);
+  return app;
+};
+
+const mockedPing = vi.mocked(pingDatabase);
 
 describe('Health endpoint', () => {
-  it('should return 200 with ok status', async () => {
-    const res = await app.request('/health');
+  beforeEach(() => {
+    mockedPing.mockReset();
+  });
+
+  it('returns 200 + healthy when DB is connected', async () => {
+    mockedPing.mockResolvedValue('connected');
+    const res = await makeApp().request('/health', {}, env);
     expect(res.status).toBe(200);
-    const body = (await res.json()) as { status: string };
-    expect(body.status).toBe('ok');
+    const body = (await res.json()) as HealthBody;
+    expect(body.status).toBe('healthy');
+    expect(body.checks.database).toBe('connected');
   });
 
-  it('should include a requestId in the response body', async () => {
-    const res = await app.request('/health');
-    const body = (await res.json()) as { requestId: string };
-    expect(body.requestId).toBeDefined();
-    expect(typeof body.requestId).toBe('string');
-    expect(body.requestId.length).toBeGreaterThan(0);
+  it('returns version from APP_VERSION binding', async () => {
+    mockedPing.mockResolvedValue('connected');
+    const res = await makeApp().request('/health', {}, env);
+    const body = (await res.json()) as HealthBody;
+    expect(body.version).toBe('0.0.1');
   });
 
-  it('should include X-Request-Id response header', async () => {
-    const res = await app.request('/health');
+  it('returns numeric uptime >= 0', async () => {
+    mockedPing.mockResolvedValue('connected');
+    const res = await makeApp().request('/health', {}, env);
+    const body = (await res.json()) as HealthBody;
+    expect(typeof body.uptime).toBe('number');
+    expect(body.uptime).toBeGreaterThanOrEqual(0);
+  });
+
+  it('returns 503 + unhealthy when DB is disconnected', async () => {
+    mockedPing.mockResolvedValue('disconnected');
+    const res = await makeApp().request('/health', {}, env);
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as HealthBody;
+    expect(body.status).toBe('unhealthy');
+    expect(body.checks.database).toBe('disconnected');
+  });
+
+  it('returns 503 when ping exceeds timeout', async () => {
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+    mockedPing.mockImplementation(() => new Promise(() => {}));
+    const reqPromise = makeApp().request('/health', {}, env);
+    await vi.advanceTimersByTimeAsync(2001);
+    const res = await reqPromise;
+    expect(res.status).toBe(503);
+    vi.useRealTimers();
+  });
+
+  it('returns 503 when ping throws (never 500)', async () => {
+    mockedPing.mockRejectedValue(new Error('boom'));
+    const res = await makeApp().request('/health', {}, env);
+    expect(res.status).toBe(503);
+  });
+
+  it('preserves requestId in body and X-Request-Id header', async () => {
+    mockedPing.mockResolvedValue('connected');
+    const res = await makeApp().request('/health', {}, env);
+    const body = (await res.json()) as HealthBody;
+    expect(typeof body.requestId).toBe('string');
+    expect(body.requestId.length).toBeGreaterThan(0);
     expect(res.headers.get('X-Request-Id')).not.toBeNull();
   });
 });

examples/todo-api-cloudflare/api/wrangler.toml

@@ -17,3 +17,5 @@ database_id = "<YOUR_D1_DATABASE_ID>"
 
 [vars]
 ENVIRONMENT = "development"
+APP_VERSION = "0.0.1"
+HEALTH_DB_TIMEOUT_MS = "2000"