@dunx/create-app 0.4.0 → 0.6.0

package/templates/features/guards/reports.service.ts

@@ -0,0 +1,22 @@
+import { HttpError, HttpStatusCode } from '@dunx/http';
+
+export class ReportsService {
+  readonly #rows = ['q1 revenue'];
+
+  titles(): readonly string[] {
+    return this.#rows;
+  }
+
+  add(title: string): readonly string[] {
+    this.#rows.push(title);
+    return this.#rows;
+  }
+
+  rename(id: number, title: string): readonly string[] {
+    if (id < 1 || id > this.#rows.length) {
+      throw new HttpError(HttpStatusCode.NOT_FOUND, `No report ${id}`);
+    }
+    this.#rows[id - 1] = title;
+    return this.#rows;
+  }
+}

package/templates/features/health/health.controller.ts

@@ -0,0 +1,65 @@
+import { Controller, Get, Public } from '@dunx/http';
+import { Storage } from '@dunx/infra/files';
+import { Sessions } from '../cache/sessions.service.js';
+import { AppConfigService } from '../config.js';
+import { Ledger } from '../database/ledger.service.js';
+
+export interface AreaStatus {
+  readonly name: string;
+  readonly state: 'live' | 'degraded';
+  readonly detail: string;
+}
+
+/**
+ * What is actually working right now. Redis is the only area that can be down
+ * without stopping the app, so it is the only one that ever reports `degraded` -
+ * everything else is in-process and either booted or the app did not.
+ */
+@Controller('health')
+export class HealthController {
+  constructor(
+    private readonly config: AppConfigService,
+    private readonly ledger: Ledger,
+    private readonly storage: Storage,
+    private readonly sessions: Sessions,
+  ) {}
+
+  @Public()
+  @Get('/', {})
+  async status(): Promise<{
+    ok: boolean;
+    app: string;
+    areas: readonly AreaStatus[];
+  }> {
+    const areas = await this.areas();
+    return {
+      ok: true,
+      app: this.config.get('appName'),
+      areas,
+    };
+  }
+
+  async areas(): Promise<readonly AreaStatus[]> {
+    const cache = await this.sessions.status();
+    return [
+      {
+        name: '@dunx/infra/db',
+        state: 'live',
+        detail: `${this.ledger.rows()} ledger rows, balance ${this.ledger.balance()}`,
+      },
+      {
+        name: '@dunx/infra/files',
+        state: 'live',
+        detail: `${this.storage.constructor.name} ready`,
+      },
+      { name: '@dunx/infra/images', state: 'live', detail: 'Bun.Image ready' },
+      {
+        name: '@dunx/infra/redis',
+        state: cache.reachable ? 'live' : 'degraded',
+        detail: cache.reachable
+          ? `reachable at ${cache.url}`
+          : (cache.note ?? `unreachable at ${cache.url}`),
+      },
+    ];
+  }
+}

package/templates/features/health/health.module.ts

@@ -0,0 +1,5 @@
+import { Module } from '@dunx/core';
+import { HealthController } from './health.controller.js';
+
+@Module({ controllers: [HealthController] })
+export class HealthModule {}

package/templates/features/http/http.demo.ts

@@ -0,0 +1,115 @@
+import { Logger } from '@dunx/core';
+import type { HttpApp } from '@dunx/http';
+import { AppConfigService } from '../config.js';
+import { RequestLog } from './request-log.js';
+
+const CORS_HEADERS = [
+  'access-control-allow-origin',
+  'access-control-allow-methods',
+  'access-control-allow-headers',
+  'access-control-allow-credentials',
+  'access-control-max-age',
+] as const;
+
+const describeCors = (response: Response): string =>
+  CORS_HEADERS.map(
+    (header) =>
+      `${header.slice('access-control-'.length)}=${response.headers.get(header) ?? '-'}`,
+  ).join(' ');
+
+const preflight = (url: string, origin: string): Promise<Response> =>
+  fetch(new URL('api/notes', url), {
+    method: 'OPTIONS',
+    headers: {
+      origin,
+      'access-control-request-method': 'POST',
+      'access-control-request-headers': 'content-type',
+    },
+  });
+
+const postNote = (url: string, text: unknown): Promise<Response> =>
+  fetch(new URL('api/notes', url), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ text }),
+  });
+
+const whoami = async (url: string, forwarded: boolean): Promise<string> => {
+  const response = await fetch(new URL('api/notes/whoami', url), {
+    headers: forwarded ? { 'x-forwarded-for': '203.0.113.7, 10.0.0.1' } : {},
+  });
+  const { ip } = (await response.json()) as { ip: string | undefined };
+  return ip ?? '(none)';
+};
+
+export class HttpDemo {
+  constructor(
+    private readonly log: RequestLog,
+    private readonly config: AppConfigService,
+    private readonly logger: Logger,
+  ) {}
+
+  async demonstrate(app: HttpApp, url: string): Promise<void> {
+    const { logger } = this;
+    const origin = this.config.get('corsOrigin');
+
+    const prefixed = await fetch(new URL('api/notes', url));
+    logger.info(
+      `setGlobalPrefix("api"): GET /api/notes -> ${prefixed.status} ` +
+        `${JSON.stringify(await prefixed.json())}`,
+    );
+    const unprefixed = await fetch(new URL('notes', url));
+    logger.info(
+      `GET /notes -> ${unprefixed.status} (the unprefixed path is gone)`,
+    );
+
+    const created = await postNote(url, 'ship it');
+    logger.info(
+      `use(RequestLoggerMiddleware): POST /api/notes -> ${created.status}, ` +
+        `x-handled-by: ${created.headers.get('x-handled-by')}`,
+    );
+    logger.info(`RequestLog -> ${JSON.stringify(this.log.entries.slice(-2))}`);
+
+    const rejected = await postNote(url, 7);
+    logger.info(
+      `POST /api/notes {"text":7} -> ${rejected.status} ` +
+        `${JSON.stringify(await rejected.json())}`,
+    );
+
+    // Bun.serve answers a method miss with 404, so a preflight can never be
+    // inferred - enableCors mounts an explicit OPTIONS per path.
+    const allowed = await preflight(url, origin);
+    logger.info(
+      `enableCors: OPTIONS from ${origin} -> ${allowed.status} ${describeCors(allowed)}`,
+    );
+    // A denied origin gets no CORS headers at all, which is what makes a browser
+    // block the response.
+    const denied = await preflight(url, 'https://evil.test');
+    logger.info(
+      `OPTIONS from https://evil.test -> ${denied.status} ${describeCors(denied)}`,
+    );
+
+    logger.info(
+      `set("trust proxy", true): X-Forwarded-For sent -> ${await whoami(url, true)}`,
+    );
+    logger.info(`no header -> ${await whoami(url, false)}`);
+
+    // The route table and the middleware chain fold into one closure per route at
+    // listen(), so a late call could only ever be a silent no-op.
+    try {
+      app.setGlobalPrefix('too-late');
+    } catch (error) {
+      logger.info(
+        `setGlobalPrefix() after listen() threw: ${(error as Error).message}`,
+      );
+    }
+  }
+
+  /** The other half of `set('trust proxy')`, which needs its own app to observe. */
+  async proxyOff(url: string): Promise<void> {
+    this.logger.info(
+      `set("trust proxy", false): X-Forwarded-For sent -> ${await whoami(url, true)} ` +
+        '(the socket address; the header is ignored)',
+    );
+  }
+}

package/templates/features/http/http.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@dunx/core';
+import { HttpDemo } from './http.demo.js';
+import { RequestLog, RequestLoggerMiddleware } from './request-log.js';
+
+// `use()` resolves middleware from the container, and every class self-binds - so
+// declaring them here is for the reader, not for the resolver.
+@Module({
+  providers: [RequestLog, RequestLoggerMiddleware, HttpDemo],
+})
+export class HttpModule {}

package/templates/features/http/request-log.ts

@@ -0,0 +1,37 @@
+import type { BunRequest } from 'bun';
+import type { Middleware, Next, RouteContext } from '@dunx/http';
+
+/** The observable side effect: whatever the middleware saw is readable after. */
+export class RequestLog {
+  readonly entries: string[] = [];
+}
+
+/**
+ * A class with `handle(req, ctx, next)`, resolved from the container - which is
+ * what lets it inject. Chains are folded into one closure per route at boot, and
+ * `ctx` is the route it was folded into: names, method, path, and its metadata.
+ *
+ * **This does not log.** `@dunx/http` already installs
+ * `RequestLoggingMiddleware` by default - one structured entry per request,
+ * with `requestId` propagated through `RequestContext` - so an app writing its
+ * own would be logging everything twice. What is left here is the part a
+ * framework cannot supply: an app-specific side effect, kept because the tour
+ * asserts on it and because it is the smallest possible example of the seam.
+ */
+export class RequestLoggerMiddleware implements Middleware {
+  constructor(private readonly log: RequestLog) {}
+
+  async handle(
+    req: BunRequest,
+    ctx: RouteContext,
+    next: Next,
+  ): Promise<Response> {
+    const response = await next();
+    this.log.entries.push(
+      `${req.method} ${new URL(req.url).pathname} -> ${response.status} ` +
+        `(${ctx.controller}.${ctx.handler})`,
+    );
+    response.headers.set('x-handled-by', 'request-logger');
+    return response;
+  }
+}

package/templates/features/jobs/jobs.controller.ts

@@ -0,0 +1,102 @@
+import {
+  Controller,
+  Get,
+  HttpError,
+  HttpStatusCode,
+  Post,
+  type Input,
+} from '@dunx/http';
+import { EncodableFormat } from '@dunx/infra/images';
+import { isConnectionError } from '@dunx/infra/redis';
+import { JobPublisher } from '@dunx/infra/queue';
+import { z } from 'zod';
+import { THUMBNAIL_QUEUE, type RenderResult } from './thumbnail.jobs.js';
+
+const Enqueue = z
+  .object({
+    width: z.coerce.number().int().min(1).max(1024).default(128),
+    format: z.enum(EncodableFormat).default(EncodableFormat.WEBP),
+  })
+  .meta({ id: 'EnqueueRender', title: 'A thumbnail to render off the request' })
+  .strict();
+
+const enqueue = { body: Enqueue } as const;
+const oneJob = { params: z.object({ id: z.string().min(1) }) } as const;
+
+/**
+ * The publish side. Nothing here consumes: `QueueModule.forRoot` binds
+ * `JobPublisher` and no worker, so this process enqueues and returns immediately.
+ * Run `bun run worker` to consume.
+ */
+@Controller('jobs')
+export class JobsController {
+  constructor(private readonly publisher: JobPublisher) {}
+
+  @Post('/thumbnails', enqueue)
+  async enqueue(
+    input: Input<typeof enqueue>,
+  ): Promise<{ id: string; queue: string; state: string }> {
+    const job = await this.degrades(() =>
+      this.publisher.publish(THUMBNAIL_QUEUE, 'render', input.body),
+    );
+
+    return {
+      id: job.id ?? '(unassigned)',
+      queue: THUMBNAIL_QUEUE,
+      // `waiting` until a worker takes it - which is the observable point of a
+      // queue, so it is in the response rather than hidden.
+      state: await job.getState(),
+    };
+  }
+
+  /**
+   * Poll a job. `returnvalue` is whatever the handler returned, so this is how the
+   * web process reads a result computed in another process.
+   */
+  @Get('/thumbnails/:id', oneJob)
+  async status(input: Input<typeof oneJob>): Promise<{
+    id: string;
+    state: string;
+    result: RenderResult | null;
+    failedReason: string | null;
+  }> {
+    const job = await this.degrades(() =>
+      this.publisher.queue(THUMBNAIL_QUEUE).getJob(input.params.id),
+    );
+    if (job === undefined) {
+      throw new HttpError(
+        HttpStatusCode.NOT_FOUND,
+        `No job ${input.params.id} on "${THUMBNAIL_QUEUE}"`,
+      );
+    }
+
+    return {
+      id: job.id ?? input.params.id,
+      state: await job.getState(),
+      result: (job.returnvalue as RenderResult | null) ?? null,
+      failedReason: job.failedReason ?? null,
+    };
+  }
+
+  /**
+   * No Redis is a degraded queue, not a broken app - the same contract the cache
+   * routes keep. bullmq surfaces the failure through ioredis rather than Bun's
+   * client, so the connection-error shape is not guaranteed to match; anything
+   * unrecognised still becomes a 503 rather than a 500, because "the queue is not
+   * reachable" is the only thing it can mean here.
+   */
+  private async degrades<T>(run: () => Promise<T>): Promise<T> {
+    try {
+      return await run();
+    } catch (error) {
+      if (error instanceof HttpError) throw error;
+      const reason = isConnectionError(error)
+        ? (error as Error).message
+        : `${(error as Error).name}: ${(error as Error).message}`;
+      throw new HttpError(
+        HttpStatusCode.SERVICE_UNAVAILABLE,
+        `Queue unavailable: ${reason}`,
+      );
+    }
+  }
+}

package/templates/features/jobs/jobs.module.ts

@@ -0,0 +1,35 @@
+import { Module } from '@dunx/core';
+import { QueueModule } from '@dunx/infra/queue';
+import { AppConfigService } from '../config.js';
+import { PicturesModule } from '../pictures/pictures.module.js';
+import { JobsController } from './jobs.controller.js';
+import { ThumbnailJobs } from './thumbnail.jobs.js';
+
+/**
+ * Imported by **both** containers, which is the whole shape of a queue: the web
+ * process publishes, a separate worker process consumes, and they agree only on
+ * this module.
+ *
+ * `QueueModule.forRoot` binds the publish side alone, so importing it does not
+ * open a worker - a web process that publishes never consumes by accident.
+ * `PicturesModule` is here because the handler injects `Thumbnails`, and the
+ * worker's container has to be able to build it.
+ */
+@Module({
+  imports: [
+    QueueModule.forRootAsync({
+      useFactory: (config: AppConfigService) => {
+        const { url } = config.get('redis');
+        return {
+          ...(url === undefined ? {} : { url }),
+          prefix: 'dunx-full',
+        };
+      },
+      inject: [AppConfigService] as const,
+    }),
+    PicturesModule,
+  ],
+  controllers: [JobsController],
+  providers: [ThumbnailJobs],
+})
+export class JobsModule {}

package/templates/features/jobs/thumbnail.jobs.ts

@@ -0,0 +1,53 @@
+import { Logger } from '@dunx/core';
+import { EncodableFormat, ImageFit } from '@dunx/infra/images';
+import { JobHandler } from '@dunx/infra/queue';
+import type { Job } from 'bullmq';
+import { Thumbnails } from '../pictures/thumbnails.service.js';
+
+export const THUMBNAIL_QUEUE = 'thumbnails';
+
+export interface RenderRequest {
+  readonly width: number;
+  readonly format: EncodableFormat;
+}
+
+export interface RenderResult {
+  readonly width: number;
+  readonly height: number;
+  readonly bytes: number;
+}
+
+/**
+ * A job handler is a method with a decorator and nothing else - no registry, no
+ * class decorator, no queue token. `WorkerFactory` finds it by walking the
+ * prototypes of the classes already in `providers`, the same marker-plus-scan the
+ * route and gateway discovery use.
+ *
+ * It injects like anything else, which is the point: the same `Thumbnails` service
+ * the HTTP routes use does the work here, with no second wiring.
+ */
+export class ThumbnailJobs {
+  constructor(
+    private readonly thumbnails: Thumbnails,
+    private readonly logger: Logger,
+  ) {}
+
+  @JobHandler({ queue: THUMBNAIL_QUEUE, name: 'render' })
+  async render(job: Job<RenderRequest>): Promise<RenderResult> {
+    const encoded = await this.thumbnails.render({
+      width: job.data.width,
+      fit: ImageFit.INSIDE,
+      format: job.data.format,
+    });
+
+    const result: RenderResult = {
+      width: encoded.width,
+      height: encoded.height,
+      bytes: encoded.bytes.byteLength,
+    };
+    // Written by the worker process, so seeing this line is how you know the job
+    // did not run in the web process.
+    this.logger.info(`rendered job ${job.id ?? '?'}`, result);
+    return result;
+  }
+}

package/templates/features/notes/notes.controller.ts

@@ -0,0 +1,65 @@
+import {
+  ClientAddress,
+  Controller,
+  Get,
+  HttpStatusCode,
+  Post,
+  type Input,
+  type RouteSchemas,
+} from '@dunx/http';
+import { ApiDoc } from '@dunx/openapi';
+import { z } from 'zod';
+import { NotesService } from './notes.service.js';
+
+const CreateNote = z
+  .object({ text: z.string().min(1) })
+  .meta({ id: 'CreateNote', title: 'Add a note' });
+
+// An explicit status, unlike the users controller which takes the POST default.
+const createNote = {
+  body: CreateNote,
+  status: HttpStatusCode.CREATED,
+} as const satisfies RouteSchemas;
+
+/**
+ * `@ApiDoc` carries what no zod schema can - prose, grouping, deprecation. It is a
+ * thin wrapper over `@dunx/http`'s generic route-metadata channel (`metaKey` mints
+ * a symbol, `meta` writes it), which is why documentation needs no parallel
+ * registry and no second discovery pass. At class scope it names the tag every
+ * route below is grouped under.
+ */
+@ApiDoc({
+  tags: ['Notes'],
+  description: 'A list in memory, for showing the prefix, middleware and CORS.',
+})
+@Controller('notes')
+export class NotesController {
+  // ClientAddress is a framework class with no registration - the container
+  // self-binds it, and app.listen() hands it the live server.
+  constructor(
+    private readonly notes: NotesService,
+    private readonly address: ClientAddress,
+  ) {}
+
+  @Get('/')
+  list(): readonly string[] {
+    return this.notes.rows();
+  }
+
+  // No schemas declared, so the request is all `input` carries.
+  @ApiDoc({
+    summary: 'Echo the caller’s address',
+    description:
+      'Reads the socket address, honouring `x-forwarded-for` because `trust proxy` is set.',
+    deprecated: true,
+  })
+  @Get('/whoami')
+  whoami(input: Input<RouteSchemas>): { ip: string | undefined } {
+    return { ip: this.address.of(input.req) };
+  }
+
+  @Post('/', createNote)
+  create(input: Input<typeof createNote>): readonly string[] {
+    return this.notes.add(input.body.text);
+  }
+}

package/templates/features/notes/notes.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@dunx/core';
+import { NotesController } from './notes.controller.js';
+import { NotesService } from './notes.service.js';
+
+@Module({
+  controllers: [NotesController],
+  providers: [NotesService],
+})
+export class NotesModule {}

package/templates/features/notes/notes.service.ts

@@ -0,0 +1,21 @@
+import { Logger } from '@dunx/core';
+import type { OnInit } from '@dunx/core';
+
+export class NotesService implements OnInit {
+  readonly #rows = ['read the architecture doc', 'measure before deciding'];
+
+  constructor(private readonly logger: Logger) {}
+
+  onInit(): void {
+    this.logger.info('notes ready');
+  }
+
+  rows(): readonly string[] {
+    return this.#rows;
+  }
+
+  add(text: string): readonly string[] {
+    this.#rows.push(text);
+    return this.#rows;
+  }
+}

package/templates/features/pictures/images.controller.ts

@@ -0,0 +1,74 @@
+import { Controller, Get, Post, type Input } from '@dunx/http';
+import { EncodableFormat, ImageFit } from '@dunx/infra/images';
+import { z } from 'zod';
+import { Thumbnails } from './thumbnails.service.js';
+
+const Resize = z
+  .object({
+    width: z.coerce.number().int().min(1).max(1024).default(64),
+    height: z.coerce.number().int().min(1).max(1024).optional(),
+    fit: z.enum(ImageFit).default(ImageFit.INSIDE),
+    format: z.enum(EncodableFormat).default(EncodableFormat.PNG),
+    quality: z.coerce.number().int().min(1).max(100).optional(),
+  })
+  .meta({ id: 'Resize', title: 'How to render the generated source image' });
+
+const render = { query: Resize } as const;
+const describe = {
+  body: z
+    .object({ base64: z.string().min(1) })
+    .meta({ id: 'InlineImage', title: 'Any image, base64-encoded' }),
+} as const;
+
+/**
+ * Every byte here is produced at runtime by `Bun.Image` from a 4x4 seed, so the
+ * example checks in no binaries and downloads nothing.
+ */
+@Controller('images')
+export class ImagesController {
+  constructor(private readonly thumbnails: Thumbnails) {}
+
+  /** Returns the encoded image itself, so a browser renders it inline. */
+  @Get('/render', render)
+  async render(input: Input<typeof render>): Promise<Response> {
+    const encoded = await this.thumbnails.render(input.query);
+    return new Response(encoded.bytes, {
+      headers: {
+        'content-type': encoded.mimeType,
+        'x-dimensions': `${encoded.width}x${encoded.height}`,
+      },
+    });
+  }
+
+  /** The same render, described rather than returned - easier to read in swagger. */
+  @Get('/metadata', render)
+  async metadata(input: Input<typeof render>): Promise<{
+    width: number;
+    height: number;
+    format: string;
+    mimeType: string;
+    bytes: number;
+  }> {
+    const encoded = await this.thumbnails.render(input.query);
+    return {
+      width: encoded.width,
+      height: encoded.height,
+      format: encoded.format,
+      mimeType: encoded.mimeType,
+      bytes: encoded.bytes.byteLength,
+    };
+  }
+
+  /**
+   * Format detection is content-based - magic bytes, never a filename - and this
+   * is a header read rather than a decode, so a truncated file still answers.
+   */
+  @Post('/describe', describe)
+  describe(input: Input<typeof describe>): Promise<{
+    width: number;
+    height: number;
+    format: string;
+  }> {
+    return this.thumbnails.describe(input.body.base64);
+  }
+}

package/templates/features/pictures/pictures.module.ts

@@ -0,0 +1,22 @@
+import { Module } from '@dunx/core';
+import { ImagesModule } from '@dunx/infra/images';
+import { AppConfigService } from '../config.js';
+import { ImagesController } from './images.controller.js';
+import { Thumbnails } from './thumbnails.service.js';
+
+@Module({
+  imports: [
+    // `forRootAsync` is what a factory needs in order to *inject*; asynchrony is
+    // free either way, since every factory settles before the first constructor.
+    ImagesModule.forRootAsync({
+      useFactory: (config: AppConfigService) => ({
+        quality: config.get('images').quality,
+        maxWidth: 1024,
+      }),
+      inject: [AppConfigService],
+    }),
+  ],
+  controllers: [ImagesController],
+  providers: [Thumbnails],
+})
+export class PicturesModule {}