@dunx/create-app 0.4.0 → 0.5.0

package/templates/features/chat/chat.demo.ts

@@ -0,0 +1,184 @@
+import { Logger, Module } from '@dunx/core';
+import { HttpFactory, PubSub, type HttpApp } from '@dunx/http';
+import { isConnectionError, RedisConnection } from '@dunx/infra/redis';
+import { RELAY_CHANNEL } from '../config.js';
+import { ChatGateway } from './chat.gateway.js';
+import { Lobby } from './lobby.service.js';
+
+interface Client {
+  next(): Promise<string>;
+  send(event: string, data: unknown): void;
+  close(): void;
+  /** Every frame this socket ever received, so a *second* delivery is visible. */
+  readonly received: readonly string[];
+}
+
+/** A real `new WebSocket()`, with a deadline so a stall fails instead of hanging. */
+const connect = async (base: string): Promise<Client> => {
+  const socket = new WebSocket(
+    new URL('chat', base).href.replace('http', 'ws'),
+  );
+  const frames: string[] = [];
+  const received: string[] = [];
+  const waiting: ((frame: string) => void)[] = [];
+
+  socket.addEventListener('message', (event: MessageEvent) => {
+    const frame = String(event.data);
+    received.push(frame);
+    const waiter = waiting.shift();
+    if (waiter) waiter(frame);
+    else frames.push(frame);
+  });
+  await new Promise<void>((resolve, reject) => {
+    socket.addEventListener('open', () => resolve(), { once: true });
+    setTimeout(() => reject(new Error('the socket never opened')), 2000);
+  });
+
+  return {
+    next: () =>
+      new Promise<string>((resolve, reject) => {
+        const queued = frames.shift();
+        if (queued !== undefined) {
+          resolve(queued);
+          return;
+        }
+        const timer = setTimeout(
+          () => reject(new Error('no frame arrived')),
+          2000,
+        );
+        waiting.push((frame) => {
+          clearTimeout(timer);
+          resolve(frame);
+        });
+      }),
+    send: (event, data) => socket.send(JSON.stringify({ event, data })),
+    close: () => socket.close(),
+    received,
+  };
+};
+
+/**
+ * A second node, in-process. Two `Bun.serve` instances, two containers, two
+ * `PubSub`s with two different origin ids - everything a second deployment has
+ * except a second pid, which the relay logic cannot tell apart anyway.
+ *
+ * It reuses the very same `ChatGateway`, and takes only what that gateway needs:
+ * `ChatDemo` itself is not in here, so this module cannot recurse.
+ */
+@Module({ providers: [ChatGateway, Lobby] })
+class PeerNode {}
+
+export class ChatDemo {
+  constructor(
+    private readonly pubsub: PubSub,
+    private readonly logger: Logger,
+    private readonly redis: RedisConnection,
+  ) {}
+
+  async demonstrate(app: HttpApp, url: string): Promise<void> {
+    const { logger } = this;
+    logger.info(
+      `gateway paths: ${JSON.stringify(app.gatewayPaths)} - setGlobalPrefix moves routes, not gateways`,
+    );
+
+    const [ada, grace] = await Promise.all([connect(url), connect(url)]);
+    logger.info(
+      `two clients connected: ${await ada.next()} / ${await grace.next()}`,
+    );
+
+    ada.send('say', 'one server, two protocols');
+    logger.info(
+      `grace <- ${await grace.next()} (the broadcast, Bun native pub/sub)`,
+    );
+    logger.info(
+      `ada   <- ${await ada.next()} (a server publish reaches the sender too)`,
+    );
+    logger.info(
+      `ada   <- ${await ada.next()} (then what the handler returned, as a reply)`,
+    );
+    logger.info(
+      `"${Lobby.TOPIC}" subscribers: ${this.pubsub.subscriberCount(Lobby.TOPIC)}`,
+    );
+
+    const alsoHttp = await fetch(new URL('api/notes', url));
+    logger.info(
+      `the same server still answers GET /api/notes -> ${alsoHttp.status}`,
+    );
+
+    ada.close();
+    grace.close();
+    // Long enough for @OnClose to run before the tour moves on.
+    await Bun.sleep(20);
+  }
+
+  /**
+   * The relay: a publish on this node reaching a client connected to a *different*
+   * node, exactly once. Both nodes run in this process - two `Bun.serve`
+   * instances, two containers - which is every part of a two-machine deployment
+   * that the fan-out logic can distinguish.
+   *
+   * Node A relays through `RedisRelay`, which `createApp` handed to
+   * `HttpFactory`. Node B relays through the application's **own**
+   * `RedisConnection`, which satisfies `PubSubRelay` structurally - two methods,
+   * no adapter, and `@dunx/http` depending on `@dunx/infra` not at all.
+   */
+  async relayed(url: string): Promise<void> {
+    const { logger } = this;
+    if (!(await this.#redisUp())) {
+      logger.warn('skipping the relay demo: no Redis to relay through');
+      logger.info(
+        'the app booted anyway and fan-out stayed local - that is the degraded path',
+      );
+      return;
+    }
+
+    const peer = await HttpFactory.create(PeerNode, { requestLogging: false });
+    const peerUrl = await peer.listen(0);
+    const peerPubsub = peer.get(PubSub);
+    await peerPubsub.relayThrough(this.redis, { channel: RELAY_CHANNEL });
+
+    try {
+      logger.info(`node A on ${url}, node B on ${peerUrl}`);
+      // The last chars, not the first: a v7 uuid starts with a timestamp, so two
+      // ids minted in the same second share their leading digits.
+      logger.info(
+        `origins: A …${this.pubsub.origin.slice(-6)} / B …${peerPubsub.origin.slice(-6)} ` +
+          '- what tells a node its own echoed frame',
+      );
+
+      const [onA, onB] = await Promise.all([connect(url), connect(peerUrl)]);
+      await Promise.all([onA.next(), onB.next()]);
+
+      const said = 'across nodes';
+      this.pubsub.publishEvent(Lobby.TOPIC, 'said', said);
+      logger.info(`node B's client <- ${await onB.next()} (relayed via Redis)`);
+      // Redis echoes a publish back to its publisher. Fanning that out again would
+      // deliver twice on node A, so the origin check drops it - and these counts
+      // are what would show it if it did not.
+      await Bun.sleep(200);
+      const delivered = (client: Client): number =>
+        client.received.filter((frame) => frame.includes(said)).length;
+      logger.info(
+        `deliveries of "${said}": A ${delivered(onA)}, B ${delivered(onB)} ` +
+          '(one each - the echo was dropped, not fanned out again)',
+      );
+
+      onA.close();
+      onB.close();
+      await Bun.sleep(20);
+    } finally {
+      await peer.shutdown();
+    }
+  }
+
+  /** A relay demo needs a broker; an absent one is a skip, not a failure. */
+  async #redisUp(): Promise<boolean> {
+    try {
+      await this.redis.ping();
+      return true;
+    } catch (error) {
+      if (!isConnectionError(error)) throw error;
+      return false;
+    }
+  }
+}

package/templates/features/chat/chat.gateway.ts

@@ -0,0 +1,85 @@
+import { Logger } from '@dunx/core';
+import {
+  Gateway,
+  HttpStatusCode,
+  OnClose,
+  OnDrain,
+  OnMessage,
+  OnOpen,
+  OnPing,
+  OnPong,
+  OnUpgrade,
+  type Socket,
+} from '@dunx/http';
+import type { BunRequest } from 'bun';
+import { Lobby } from './lobby.service.js';
+
+/**
+ * Served by the same `Bun.serve` call as the HTTP routes: `HttpFactory` discovers
+ * it from `providers`, and `listen()` mounts the upgrade as a native route.
+ */
+@Gateway('/chat')
+export class ChatGateway {
+  constructor(
+    private readonly lobby: Lobby,
+    private readonly logger: Logger,
+  ) {}
+
+  /**
+   * Runs before the socket exists, and is the only place a connection can be
+   * refused: return a `Response` and there is no upgrade. Anything else returned
+   * becomes `socket.data.context`, which is how a room name or an authenticated
+   * user gets carried onto the connection.
+   *
+   * It is handed the `BunRequest` because the upgrade really is a route - Bun
+   * matched it - so headers, query and path params are all readable here.
+   */
+  @OnUpgrade()
+  upgrade(req: BunRequest): Response | { nickname: string } {
+    const nickname = new URL(req.url).searchParams.get('as') ?? 'anonymous';
+    if (nickname === 'banned') {
+      return new Response('nope', { status: HttpStatusCode.FORBIDDEN });
+    }
+    return { nickname };
+  }
+
+  @OnOpen()
+  opened(socket: Socket): void {
+    // Bun's own pub/sub - topics live in the runtime, not in a JavaScript map.
+    socket.subscribe(Lobby.TOPIC);
+    socket.send('welcome');
+  }
+
+  @OnMessage('say')
+  say(text: string): { delivered: number } {
+    // The broadcast reaches everyone subscribed; the return value is replied to
+    // the sender under the same event name.
+    return { delivered: this.lobby.broadcast(text) };
+  }
+
+  /**
+   * Backpressure relieved: Bun buffered because the client was not reading fast
+   * enough and has now flushed. This is where a server streaming to a slow
+   * consumer resumes.
+   */
+  @OnDrain()
+  drained(socket: Socket): void {
+    this.logger.info(`${socket.data.path} drained, safe to resume sending`);
+  }
+
+  /** Bun answers with a pong itself; this is for observing liveness. */
+  @OnPing()
+  pinged(_data: Buffer, socket: Socket): void {
+    this.logger.info(`${socket.data.path} pinged`);
+  }
+
+  @OnPong()
+  ponged(_data: Buffer, socket: Socket): void {
+    this.logger.info(`${socket.data.path} ponged`);
+  }
+
+  @OnClose()
+  closed(socket: Socket, code: number): void {
+    this.logger.info(`${socket.data.path} closed with ${code}`);
+  }
+}

package/templates/features/chat/chat.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@dunx/core';
+import { ChatDemo } from './chat.demo.js';
+import { ChatGateway } from './chat.gateway.js';
+import { Lobby } from './lobby.service.js';
+
+// A gateway is declared in `providers`, next to the services it injects - there is
+// no separate list for it, and no second module to configure.
+@Module({
+  providers: [ChatGateway, Lobby, ChatDemo],
+})
+export class ChatModule {}

package/templates/features/chat/lobby.service.ts

@@ -0,0 +1,20 @@
+import { PubSub } from '@dunx/http';
+
+/**
+ * A plain service that publishes without holding a socket. `PubSub` is bound by
+ * `HttpFactory` around the root module, so nothing has to be imported or
+ * registered for this to resolve - listing it in `providers` would be the
+ * container's duplicate-binding error.
+ */
+export class Lobby {
+  static readonly TOPIC = 'lobby';
+
+  readonly said: string[] = [];
+
+  constructor(private readonly pubsub: PubSub) {}
+
+  broadcast(text: string): number {
+    this.said.push(text);
+    return this.pubsub.publishEvent(Lobby.TOPIC, 'said', text);
+  }
+}

package/templates/features/database/auth.schema.ts

@@ -0,0 +1,75 @@
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+/**
+ * better-auth's four tables, plus the columns its `admin` plugin adds. **Generated,
+ * not written**: `bunx @better-auth/cli generate` emits this from the very options
+ * `AuthModule` is configured with, which is why `@dunx/auth` ships no copy - the
+ * shape follows the plugins an app enables.
+ *
+ * They live in the app's one schema module, so `drizzle({ client, schema })` carries
+ * them and `drizzleDatabase(connection)` needs no schema argument.
+ */
+const stamp = () =>
+  integer({ mode: 'timestamp_ms' })
+    .notNull()
+    .$defaultFn(() => new Date());
+
+export const user = sqliteTable('user', {
+  id: text().primaryKey(),
+  name: text().notNull(),
+  email: text().notNull().unique(),
+  emailVerified: integer({ mode: 'boolean' }).notNull().default(false),
+  image: text(),
+  /** `admin` plugin. Comma-separated for more than one - `rolesOf` splits it. */
+  role: text(),
+  banned: integer({ mode: 'boolean' }),
+  banReason: text(),
+  banExpires: integer({ mode: 'timestamp_ms' }),
+  createdAt: stamp(),
+  updatedAt: stamp(),
+});
+
+export const session = sqliteTable('session', {
+  id: text().primaryKey(),
+  token: text().notNull().unique(),
+  userId: text()
+    .notNull()
+    .references(() => user.id, { onDelete: 'cascade' }),
+  expiresAt: integer({ mode: 'timestamp_ms' }).notNull(),
+  ipAddress: text(),
+  userAgent: text(),
+  /** `admin` plugin. */
+  impersonatedBy: text(),
+  createdAt: stamp(),
+  updatedAt: stamp(),
+});
+
+export const account = sqliteTable('account', {
+  id: text().primaryKey(),
+  accountId: text().notNull(),
+  /** `credential` for email/password, else the social provider's id. */
+  providerId: text().notNull(),
+  userId: text()
+    .notNull()
+    .references(() => user.id, { onDelete: 'cascade' }),
+  accessToken: text(),
+  refreshToken: text(),
+  idToken: text(),
+  accessTokenExpiresAt: integer({ mode: 'timestamp_ms' }),
+  refreshTokenExpiresAt: integer({ mode: 'timestamp_ms' }),
+  scope: text(),
+  password: text(),
+  createdAt: stamp(),
+  updatedAt: stamp(),
+});
+
+export const verification = sqliteTable('verification', {
+  id: text().primaryKey(),
+  identifier: text().notNull(),
+  value: text().notNull(),
+  expiresAt: integer({ mode: 'timestamp_ms' }).notNull(),
+  createdAt: stamp(),
+  updatedAt: stamp(),
+});
+
+export type AuthUser = typeof user.$inferSelect;

package/templates/features/database/database.module.ts

@@ -0,0 +1,39 @@
+import { Module } from '@dunx/core';
+import { DbModule, SyncDatabase, SyncSqliteOptions } from '@dunx/infra/db';
+import { AppConfigService } from '../config.js';
+import { LedgerController } from './ledger.controller.js';
+import { Ledger } from './ledger.service.js';
+import * as schema from './schema.js';
+
+@Module({
+  imports: [
+    // `forRootAsync` is not a second mechanism: dunx settles every async factory
+    // before the first constructor runs, so the connection is open and its pragmas
+    // applied by the time a repository is built.
+    //
+    // The first argument is the token, unlike `forRoot`. The database class is
+    // what a repository injects, and which class that is only becomes known once
+    // the factory has produced the options - too late to register a provider
+    // under it.
+    //
+    // `SyncSqliteOptions` rather than `SqliteOptions`, so this app runs SQLite in
+    // **synchronous mode**: the token becomes `SyncDatabase`, and `transactionSync`
+    // becomes reachable. `SqliteOptions` is the default and still what an app
+    // wants if it might move to Postgres later - sync mode is SQLite for good.
+    DbModule.forRootAsync(SyncDatabase, {
+      useFactory: (config: AppConfigService) =>
+        new SyncSqliteOptions({
+          // Required, and the reason it is: this is the type argument that reaches
+          // `SyncDatabase<typeof schema>` in every constructor below.
+          schema,
+          filename: config.get('database').file,
+          // The only place a pragma can run before the first query.
+          pragmas: ['foreign_keys = ON'],
+        }),
+      inject: [AppConfigService],
+    }),
+  ],
+  controllers: [LedgerController],
+  providers: [Ledger],
+})
+export class DatabaseModule {}

package/templates/features/database/ledger.controller.ts

@@ -0,0 +1,137 @@
+import {
+  Controller,
+  Delete,
+  Get,
+  HttpError,
+  HttpStatusCode,
+  Post,
+  type Input,
+} from '@dunx/http';
+import { z } from 'zod';
+import { Ledger } from './ledger.service.js';
+import type { Entry } from './schema.js';
+
+const EntryIndex = z
+  .object({ id: z.coerce.number().int().min(1) })
+  .meta({ id: 'EntryIndex', title: 'A ledger entry id in the path' });
+
+const CreateEntry = z
+  .object({
+    memo: z.string().min(1).max(80),
+    amount: z.number().int(),
+  })
+  .meta({ id: 'CreateEntry', title: 'A single ledger movement' });
+
+/** Both legs succeed or neither does - the rollback is the point of the route. */
+const Transfer = z
+  .object({
+    from: z.string().min(1).max(80),
+    to: z.string().min(1).max(80),
+    amount: z.number().int().positive(),
+    /**
+     * Throw between the two legs on purpose. The response is a 409 and the row
+     * count is unchanged - which is the only way to see from outside that the
+     * first insert was rolled back rather than committed.
+     */
+    fail: z.boolean().default(false),
+  })
+  .meta({ id: 'Transfer', title: 'Move an amount between two memos' });
+
+const listEntries = {
+  query: z.object({
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+  }),
+} as const;
+const oneEntry = { params: EntryIndex } as const;
+const createEntry = { body: CreateEntry } as const;
+const transfer = { body: Transfer } as const;
+
+@Controller('ledger')
+export class LedgerController {
+  constructor(private readonly ledger: Ledger) {}
+
+  @Get('/', listEntries)
+  list(input: Input<typeof listEntries>): {
+    entries: readonly Entry[];
+    balance: number;
+  } {
+    return {
+      entries: this.ledger.list(input.query.limit),
+      balance: this.ledger.balance(),
+    };
+  }
+
+  @Get('/:id', oneEntry)
+  one(input: Input<typeof oneEntry>): Entry {
+    const entry = this.ledger.find(input.params.id);
+    if (entry === undefined) {
+      throw new HttpError(
+        HttpStatusCode.NOT_FOUND,
+        `No ledger entry ${input.params.id}`,
+      );
+    }
+    return entry;
+  }
+
+  @Post('/', createEntry)
+  create(input: Input<typeof createEntry>): Entry {
+    return this.ledger.add(input.body.memo, input.body.amount);
+  }
+
+  /**
+   * The failure path is the interesting one: `"fail": true` throws between the
+   * two inserts, and the 409's `rows` is unchanged - proof the first leg was
+   * rolled back rather than committed.
+   */
+  @Post('/transfer', transfer)
+  async transfer(
+    input: Input<typeof transfer>,
+  ): Promise<{ balance: number; rows: number }> {
+    const { from, to, amount, fail } = input.body;
+    try {
+      const balance = await this.ledger.transfer(from, to, amount, fail);
+      return { balance, rows: this.ledger.rows() };
+    } catch (error) {
+      throw new HttpError(
+        HttpStatusCode.CONFLICT,
+        `${(error as Error).message} - rolled back, still ${this.ledger.rows()} rows`,
+      );
+    }
+  }
+
+  /**
+   * The same transfer with no `async` and no `await` on the path at all - the
+   * handler returns a value, `@dunx/http` turns it into a `Response` without
+   * allocating a promise, and SQLite answered on the same tick. What makes it
+   * possible is `SyncSqliteOptions` in `DatabaseModule`; `transactionSync` will not
+   * compile against the async mode's handle.
+   */
+  @Post('/transfer-sync', transfer)
+  transferSync(input: Input<typeof transfer>): {
+    balance: number;
+    rows: number;
+  } {
+    const { from, to, amount, fail } = input.body;
+    try {
+      const balance = this.ledger.transferSync(from, to, amount, fail);
+      return { balance, rows: this.ledger.rows() };
+    } catch (error) {
+      throw new HttpError(
+        HttpStatusCode.CONFLICT,
+        `${(error as Error).message} - rolled back, still ${this.ledger.rows()} rows`,
+      );
+    }
+  }
+
+  @Delete('/:id', oneEntry)
+  remove(input: Input<typeof oneEntry>): { deleted: boolean } {
+    const deleted = this.ledger.remove(input.params.id);
+    if (!deleted) {
+      throw new HttpError(
+        HttpStatusCode.NOT_FOUND,
+        `No ledger entry ${input.params.id}`,
+      );
+    }
+    return { deleted };
+  }
+}