@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/templates/backend/jobs/scheduler.ts

@@ -1,9 +1,20 @@
-#!/usr/bin/env node
-import { setInterval } from 'node:timers';
+#!/usr/bin/env bun
+import { clearInterval, clearTimeout, setInterval, setTimeout } from 'node:timers';
 
 import { loadJobs } from './runtime.js';
 
 const args = process.argv.slice(2);
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+type ScheduledJobHandle =
+  | {
+      kind: 'timer';
+      [Symbol.dispose](): void;
+    }
+  | {
+      kind: 'reboot';
+      done: Promise<void>;
+    };
 
 async function main() {
   if (args.includes('--help') || args.includes('-h')) {
@@ -17,8 +28,9 @@ async function main() {
     return;
   }
 
-  if (args.includes('--list')) {
-    listJobs(jobs);
+  const asJson = args.includes('--json');
+  if (args.includes('--list') || asJson) {
+    listJobs(jobs, { asJson });
     return;
   }
 
@@ -47,39 +59,88 @@ async function main() {
 async function startWatch(jobs: Awaited<ReturnType<typeof loadJobs>>, jobName?: string) {
   const filtered = jobName ? jobs.filter((job) => job.name === jobName) : jobs;
   if (filtered.length === 0) {
-    console.error(jobName ? `[jobs] job '${jobName}' not found` : '[jobs] no jobs available to watch');
+    console.error(
+      jobName ? `[jobs] job '${jobName}' not found` : '[jobs] no jobs available to watch',
+    );
     process.exitCode = 1;
     return;
   }
 
-  const timers = filtered.map((job) => scheduleJob(job));
-  if (timers.every((timer) => timer === undefined)) {
-    console.warn('[jobs] no jobs have schedules compatible with the built-in watcher. Use an external scheduler.');
+  const scheduled = filtered.map((job) => scheduleJob(job));
+  const timers = scheduled.filter(
+    (timer): timer is Extract<ScheduledJobHandle, { kind: 'timer' }> => timer?.kind === 'timer',
+  );
+  const rebootRuns = scheduled.filter(
+    (timer): timer is Extract<ScheduledJobHandle, { kind: 'reboot' }> => timer?.kind === 'reboot',
+  );
+  const hasActiveWatch = timers.length > 0;
+  if (!hasActiveWatch) {
+    if (rebootRuns.length > 0) {
+      await Promise.all(rebootRuns.map((run) => run.done));
+      console.info('[jobs] completed @reboot jobs and exiting.');
+      return;
+    }
+    console.warn(
+      '[jobs] no jobs have schedules compatible with the built-in watcher. Use --json to export job metadata for an external scheduler.',
+    );
     return;
   }
 
   console.info('[jobs] watching jobs:', filtered.map((job) => job.name).join(', '));
+  registerShutdown(timers);
   process.stdin.resume();
 }
 
-function scheduleJob(job: Awaited<ReturnType<typeof loadJobs>>[number]) {
-  const intervalMs = toInterval(job.schedule);
-  if (intervalMs === null) {
+function scheduleJob(
+  job: Awaited<ReturnType<typeof loadJobs>>[number],
+): ScheduledJobHandle | undefined {
+  const schedule = normalizeSchedule(job.schedule);
+  if (!schedule) {
     console.info(
-      `[jobs] schedule '${job.schedule ?? 'unspecified'}' is not supported by the built-in watcher. Run manually or use an external scheduler.`
+      `[jobs] unsupported schedule '${job.schedule ?? 'unspecified'}'. Run manually or use --json with an external scheduler.`,
     );
     return undefined;
   }
 
-  if (intervalMs === 0) {
-    void runJob(job);
-    return undefined;
+  const runScheduledJob = createNonOverlappingRunner(job);
+
+  if (schedule.kind === 'reboot') {
+    return { kind: 'reboot', done: runScheduledJob() };
+  }
+
+  if (schedule.kind === 'rate') {
+    void runScheduledJob();
+    const timer = setInterval(() => {
+      void runScheduledJob();
+    }, schedule.intervalMs);
+    return {
+      kind: 'timer' as const,
+      [Symbol.dispose]() {
+        clearInterval(timer);
+      },
+    };
   }
 
-  void runJob(job);
-  return setInterval(() => {
-    void runJob(job);
-  }, intervalMs);
+  return scheduleCronJob(job, schedule.expression, runScheduledJob);
+}
+
+function createNonOverlappingRunner(job: Awaited<ReturnType<typeof loadJobs>>[number]) {
+  let running = false;
+  return async () => {
+    if (running) {
+      console.warn(
+        `[jobs] skipping ${job.name}; previous run is still active (overlap policy: skip)`,
+      );
+      return;
+    }
+
+    running = true;
+    try {
+      await runJob(job);
+    } finally {
+      running = false;
+    }
+  };
 }
 
 async function runNamedJob(jobs: Awaited<ReturnType<typeof loadJobs>>, jobName: string) {
@@ -97,21 +158,36 @@ async function runJob(job: Awaited<ReturnType<typeof loadJobs>>[number]) {
   console.info(`[jobs] running ${job.name} (schedule: ${job.schedule ?? 'manual'})`);
   try {
     await job.run();
-    console.info(`[jobs] ${job.name} completed in ${(Date.now() - startedAt.getTime()).toFixed(0)}ms`);
+    console.info(
+      `[jobs] ${job.name} completed in ${(Date.now() - startedAt.getTime()).toFixed(0)}ms`,
+    );
   } catch (error) {
     console.error(`[jobs] ${job.name} failed: ${(error as Error).message}`);
     process.exitCode = 1;
   }
 }
 
-function listJobs(jobs: Awaited<ReturnType<typeof loadJobs>>) {
+function listJobs(jobs: Awaited<ReturnType<typeof loadJobs>>, options: { asJson?: boolean } = {}) {
+  if (options.asJson) {
+    console.info(
+      JSON.stringify(
+        jobs.map(({ run: _run, ...job }) => job),
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
   for (const job of jobs) {
-    console.info(`- ${job.name}${job.schedule ? ` (${job.schedule})` : ''}${job.description ? ` — ${job.description}` : ''}`);
+    console.info(
+      `- ${job.name}${job.schedule ? ` (${job.schedule})` : ''}${job.description ? ` — ${job.description}` : ''}`,
+    );
   }
 }
 
 function parseOption(flag: string): string | undefined {
-  const index = args.findIndex((arg) => arg === flag);
+  const index = args.indexOf(flag);
   if (index !== -1 && args[index + 1] && !args[index + 1].startsWith('-')) {
     return args[index + 1];
   }
@@ -123,52 +199,138 @@ function parseOption(flag: string): string | undefined {
   return undefined;
 }
 
-function toInterval(schedule: string | undefined): number | null {
+function normalizeSchedule(
+  schedule: string | undefined,
+):
+  | { kind: 'cron'; expression: string }
+  | { kind: 'rate'; intervalMs: number }
+  | { kind: 'reboot' }
+  | undefined {
   if (!schedule) {
-    return null;
+    return undefined;
   }
   const trimmed = schedule.trim().toLowerCase();
-  if (!trimmed) return null;
+  if (!trimmed) return undefined;
 
   if (trimmed.startsWith('@')) {
-    switch (trimmed.slice(1)) {
-      case 'hourly':
-        return 60 * 60 * 1000;
-      case 'daily':
-      case 'midnight':
-        return 24 * 60 * 60 * 1000;
-      case 'weekly':
-        return 7 * 24 * 60 * 60 * 1000;
-      case 'reboot':
-        return 0;
-      default:
-        return null;
+    if (trimmed === '@reboot') {
+      return { kind: 'reboot' };
     }
+    return isSupportedCronExpression(trimmed) ? { kind: 'cron', expression: trimmed } : undefined;
   }
 
   const rateMatch = /^rate\((\d+)\s+(second|seconds|minute|minutes|hour|hours)\)$/.exec(trimmed);
   if (rateMatch) {
     const value = Number(rateMatch[1]);
     const unit = rateMatch[2];
-    const multiplier =
-      unit.startsWith('second') ? 1000 : unit.startsWith('minute') ? 60 * 1000 : unit.startsWith('hour') ? 60 * 60 * 1000 : 0;
-    return value > 0 && multiplier > 0 ? value * multiplier : null;
+    const multiplier = unit.startsWith('second')
+      ? 1000
+      : unit.startsWith('minute')
+        ? 60 * 1000
+        : unit.startsWith('hour')
+          ? 60 * 60 * 1000
+          : 0;
+    if (value > 0 && multiplier > 0) {
+      return { kind: 'rate', intervalMs: value * multiplier };
+    }
+    return undefined;
+  }
+
+  return isSupportedCronExpression(trimmed) ? { kind: 'cron', expression: trimmed } : undefined;
+}
+
+function isSupportedCronExpression(expression: string): boolean {
+  try {
+    return Bun.cron.parse(expression) !== null;
+  } catch {
+    return false;
   }
+}
+
+function scheduleCronJob(
+  job: Awaited<ReturnType<typeof loadJobs>>[number],
+  expression: string,
+  runScheduledJob: () => Promise<void>,
+) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let stopped = false;
+
+  const queueNext = (relativeTo?: Date) => {
+    if (stopped) {
+      return;
+    }
+
+    const nextRun = Bun.cron.parse(expression, relativeTo);
+    if (!nextRun) {
+      console.warn(
+        `[jobs] schedule '${expression}' does not produce a future run time. Stopping local watch for ${job.name}.`,
+      );
+      return;
+    }
+    scheduleTimeout(nextRun, async () => {
+      await runScheduledJob();
+      queueNext(nextRun);
+    });
+  };
+
+  const scheduleTimeout = (nextRun: Date, callback: () => Promise<void>) => {
+    const remainingMs = nextRun.getTime() - Date.now();
+    const delayMs = Math.max(0, Math.min(remainingMs, MAX_TIMEOUT_MS));
+    timer = setTimeout(() => {
+      if (stopped) {
+        return;
+      }
+      if (remainingMs > MAX_TIMEOUT_MS && nextRun.getTime() > Date.now()) {
+        scheduleTimeout(nextRun, callback);
+        return;
+      }
+      void callback();
+    }, delayMs);
+  };
+
+  queueNext();
+
+  return {
+    kind: 'timer' as const,
+    [Symbol.dispose]() {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+    },
+  };
+}
+
+function registerShutdown(timers: readonly Extract<ScheduledJobHandle, { kind: 'timer' }>[]) {
+  let stopped = false;
+  const stop = (signal: NodeJS.Signals) => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    for (const timer of timers) {
+      timer[Symbol.dispose]();
+    }
+    process.stdin.pause();
+    console.info(`[jobs] received ${signal}; stopped ${timers.length} scheduled job timer(s).`);
+  };
 
-  return null;
+  process.once('SIGINT', () => stop('SIGINT'));
+  process.once('SIGTERM', () => stop('SIGTERM'));
 }
 
 function printHelp() {
   console.info(`Usage:
-  node build/backend/jobs/scheduler.js [--list]
-  node build/backend/jobs/scheduler.js --job <name>
-  node build/backend/jobs/scheduler.js --watch [--job <name>]
+  bun src/backend/jobs/scheduler.ts [--list]
+  bun build/backend/jobs/scheduler.js --job <name>
+  bun build/backend/jobs/scheduler.js --watch [--job <name>]
 
 Options:
   --list            Show registered jobs and exit
+  --json            Print registered job metadata as JSON for external schedulers
   --job <name>      Run a specific job immediately (or watch a single job)
   --all             Run all jobs once (default when no options are provided)
-  --watch           Run supported jobs on an interval (supports @hourly/@daily/@weekly/@reboot and rate(...) syntax)
+  --watch           Watch jobs locally (supports cron expressions, cron nicknames, @reboot, and rate(...) syntax)
   --help            Display this message
 `);
 }

package/templates/backend/module.ts

@@ -2,19 +2,35 @@
 // When this file is present, the server scaffold loads build/backend/module.js,
 // announces the manifest, and mounts every route definition automatically.
 
+import {
+  groupFormIssuesByField,
+  prepareFormState,
+  processFormSubmission,
+  type FormIssue,
+  type FormValues,
+} from '@webstir-io/webstir-backend/runtime/forms';
+
 interface RouteHandlerResult {
   status?: number;
   headers?: Record<string, string>;
   body?: unknown;
+  redirect?: {
+    location: string;
+  };
   errors?: { code: string; message: string; details?: unknown }[];
 }
 
-type RouteHandler = (ctx: RouteContext) => Promise<RouteHandlerResult> | RouteHandlerResult;
-
 interface RouteContext {
   params: Record<string, string>;
   query: Record<string, string>;
   body: unknown;
+  session: Record<string, unknown> | null;
+  flash: readonly {
+    key: string;
+    level: 'info' | 'success' | 'warning' | 'error';
+    createdAt: string;
+  }[];
+  db: Record<string, unknown>;
   auth?: {
     userId?: string;
     email?: string;
@@ -35,42 +51,168 @@ interface RouteContext {
   now: () => Date;
 }
 
+type RequestHook = {
+  id: string;
+  handler:
+    | ((ctx: RouteContext) => Promise<RouteHandlerResult | undefined>)
+    | ((ctx: RouteContext) => RouteHandlerResult | undefined);
+};
+
+const accountSettingsPageDefinition = {
+  name: 'accountSettingsPage',
+  method: 'GET',
+  path: '/account/settings',
+  interaction: 'navigation',
+  session: { mode: 'optional' },
+  flash: { consume: ['settings-saved'] },
+  summary: 'Account settings form',
+  description:
+    'Demonstrates HTML-first form rendering with CSRF, redirect-after-post, and inline validation.',
+} as const;
+
+const updateAccountSettingsDefinition = {
+  name: 'accountSettingsUpdate',
+  method: 'POST',
+  path: '/account/settings',
+  interaction: 'mutation',
+  form: {
+    contentType: 'application/x-www-form-urlencoded',
+    csrf: true,
+    session: { write: true },
+    flash: {
+      publish: [{ key: 'settings-saved', level: 'success', when: 'success' }],
+    },
+  },
+  summary: 'Update account settings',
+  description: 'Demonstrates auth-aware mutations and redirect-after-post ergonomics.',
+} as const;
+
 const routes = [
   {
     definition: {
       name: 'helloRoute',
       method: 'GET',
       path: '/hello/:name',
+      requestHooks: [{ id: 'audit-hello' }],
       summary: 'Simple hello route',
-      description: 'Demonstrates manifest wiring + request context metadata.'
+      description: 'Demonstrates manifest wiring + request context metadata.',
     },
     handler: async (ctx: RouteContext) => {
       if (!ctx.auth) {
         return {
           status: 401,
-          errors: [{ code: 'auth', message: 'Sign-in required to access /hello' }]
+          errors: [{ code: 'auth', message: 'Sign-in required to access /hello' }],
         };
       }
       const name = ctx.params.name ?? 'world';
-      ctx.logger.info('hello route invoked', { name, requestId: ctx.requestId, userId: ctx.auth.userId });
+      ctx.logger.info('hello route invoked', {
+        name,
+        requestId: ctx.requestId,
+        userId: ctx.auth.userId,
+      });
       return {
         status: 200,
         body: {
           message: `Hello ${name}`,
           greetedAt: ctx.now().toISOString(),
-          user: ctx.auth.userId ?? 'anonymous'
-        }
+          user: ctx.auth.userId ?? 'anonymous',
+        },
       };
-    }
-  }
+    },
+  },
+  {
+    definition: accountSettingsPageDefinition,
+    handler: async (ctx: RouteContext) => {
+      const form = prepareFormState({
+        session: ctx.session,
+        formId: 'account-settings',
+        route: updateAccountSettingsDefinition,
+        now: ctx.now,
+      });
+      ctx.session = form.session;
+
+      return {
+        status: 200,
+        body: renderAccountSettingsPage({
+          csrfToken: form.csrfToken ?? '',
+          issues: form.issues,
+          values: form.values,
+          flash: ctx.flash,
+          currentEmail:
+            getFormValue(form.values, 'email') ??
+            getSessionProfileEmail(ctx.session) ??
+            ctx.auth?.email ??
+            'guest@example.com',
+        }),
+      };
+    },
+  },
+  {
+    definition: updateAccountSettingsDefinition,
+    handler: async (ctx: RouteContext) => {
+      const submission = processFormSubmission({
+        session: ctx.session,
+        body: ctx.body,
+        auth: ctx.auth,
+        formId: 'account-settings',
+        route: updateAccountSettingsDefinition,
+        redirectTo: accountSettingsPageDefinition.path,
+        requireAuth: {
+          redirectTo: accountSettingsPageDefinition.path,
+          message: 'Sign-in required to update account settings.',
+        },
+        validate(values) {
+          const email = getFormValue(values, 'email')?.trim() ?? '';
+          const issues: FormIssue[] = [];
+          if (email.length === 0) {
+            issues.push({ field: 'email', message: 'Email is required.' });
+          } else if (!email.includes('@')) {
+            issues.push({ field: 'email', message: 'Enter a valid email address.' });
+          }
+          return issues;
+        },
+        now: ctx.now,
+      });
+      const nextSession = submission.session ?? {};
+      ctx.session = nextSession;
+      if (!submission.ok) {
+        return submission.result;
+      }
+
+      nextSession.profile = {
+        email: getFormValue(submission.values, 'email')?.trim() ?? 'guest@example.com',
+      };
+
+      return {
+        status: 303,
+        redirect: {
+          location: accountSettingsPageDefinition.path,
+        },
+      };
+    },
+  },
+];
+
+const requestHooks: RequestHook[] = [
+  {
+    id: 'audit-hello',
+    handler: async (ctx) => {
+      ctx.db.lastHelloRequestId = ctx.requestId;
+      ctx.logger.info('hello route request received', {
+        requestId: ctx.requestId,
+        session: ctx.session,
+      });
+      return undefined;
+    },
+  },
 ];
 
 const jobs = [
   {
     name: 'nightly',
     schedule: '0 0 * * *',
-    description: 'Example nightly maintenance job metadata surfaced in the manifest.'
-  }
+    description: 'Example nightly maintenance job metadata surfaced in the manifest.',
+  },
 ];
 
 export const module = {
@@ -80,8 +222,80 @@ export const module = {
     version: '0.1.0',
     kind: 'backend',
     capabilities: ['http', 'auth', 'db'],
+    requestHooks: [
+      {
+        id: 'audit-hello',
+        phase: 'beforeHandler',
+        order: 10,
+      },
+    ],
     routes: routes.map((route) => route.definition),
-    jobs
+    jobs,
   },
-  routes
+  routes,
+  requestHooks,
 };
+
+function renderAccountSettingsPage(options: {
+  csrfToken: string;
+  issues: readonly FormIssue[];
+  values: FormValues;
+  flash: readonly {
+    key: string;
+    level: 'info' | 'success' | 'warning' | 'error';
+    createdAt: string;
+  }[];
+  currentEmail: string;
+}): string {
+  const grouped = groupFormIssuesByField(options.issues);
+  const email = escapeHtml(options.currentEmail);
+  const inlineErrors = grouped.fields.email?.join(' ') ?? '';
+  const flash = options.flash.map((message) => `${message.key}:${message.level}`).join(', ');
+  const formErrors = grouped.form.join(' ');
+
+  return [
+    '<main>',
+    '  <h1>Account Settings</h1>',
+    `  <p data-flash="${escapeHtml(flash)}" data-form-errors="${escapeHtml(formErrors)}">Signed in as ${email}</p>`,
+    '  <form method="post" action="/account/settings">',
+    `    <input type="hidden" name="_csrf" value="${escapeHtml(options.csrfToken)}" />`,
+    '    <label>',
+    '      Email',
+    `      <input name="email" type="email" value="${email}" />`,
+    '    </label>',
+    `    <p data-field="email">${escapeHtml(inlineErrors)}</p>`,
+    '    <button type="submit">Save Settings</button>',
+    '  </form>',
+    '</main>',
+  ].join('\n');
+}
+
+function getFormValue(values: FormValues, key: string): string | undefined {
+  const raw = values[key];
+  if (typeof raw === 'string') {
+    return raw;
+  }
+  if (Array.isArray(raw) && typeof raw[0] === 'string') {
+    return raw[0];
+  }
+  return undefined;
+}
+
+function getSessionProfileEmail(session: Record<string, unknown> | null): string | undefined {
+  const profile = session?.profile;
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+    return undefined;
+  }
+  return typeof (profile as { email?: unknown }).email === 'string'
+    ? (profile as { email: string }).email
+    : undefined;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}

package/templates/backend/observability/logger.ts

@@ -1,4 +1,3 @@
-import type http from 'node:http';
 import pino, { stdTimeFunctions, type Logger } from 'pino';
 
 import type { AppEnv } from '../env.js';
@@ -8,17 +7,8 @@ export function createBaseLogger(env: AppEnv): Logger {
     level: env.logging.level,
     base: {
       service: env.logging.serviceName,
-      environment: env.NODE_ENV
+      environment: env.NODE_ENV,
     },
-    timestamp: stdTimeFunctions.isoTime
-  });
-}
-
-export function createRequestLogger(baseLogger: Logger, options: { requestId: string; req: http.IncomingMessage; route?: string }): Logger {
-  return baseLogger.child({
-    requestId: options.requestId,
-    method: options.req.method ?? 'GET',
-    path: options.req.url ?? '/',
-    route: options.route
+    timestamp: stdTimeFunctions.isoTime,
   });
 }

package/templates/backend/observability/metrics.ts

@@ -30,7 +30,7 @@ export function createMetricsTracker(config: MetricsConfig): MetricsTracker {
       },
       snapshot() {
         return undefined;
-      }
+      },
     };
   }
 
@@ -53,9 +53,12 @@ export function createMetricsTracker(config: MetricsConfig): MetricsTracker {
     },
     snapshot() {
       const counts = Object.fromEntries(
-        [...byStatus.entries()].map(([status, count]) => [String(status), count])
+        [...byStatus.entries()].map(([status, count]) => [String(status), count]),
       );
-      const averageDurationMs = durations.length > 0 ? durations.reduce((sum, value) => sum + value, 0) / durations.length : 0;
+      const averageDurationMs =
+        durations.length > 0
+          ? durations.reduce((sum, value) => sum + value, 0) / durations.length
+          : 0;
       const p95DurationMs = durations.length > 0 ? percentile(durations, 0.95) : 0;
       return {
         enabled: true,
@@ -64,9 +67,9 @@ export function createMetricsTracker(config: MetricsConfig): MetricsTracker {
         averageDurationMs,
         p95DurationMs,
         byStatus: counts,
-        windowSize: config.windowSize
+        windowSize: config.windowSize,
       };
-    }
+    },
   };
 }