@trinacria/cli 0.1.1-alpha.1

package/dist/templates/api-events-rabbitmq/README.md

@@ -0,0 +1,97 @@
+# API Example: RabbitMQ Events
+
+A minimal API-only example using Trinacria Events with RabbitMQ transport.
+
+## Scope
+
+This app is intentionally a base template:
+
+- no authentication (no JWT/session/password flow)
+- no authorization roles/policies
+- no database persistence for domain data
+- focus only on event publish/consume flow via RabbitMQ
+
+## Endpoints
+
+- `GET /health`
+- `GET /events`
+- `POST /events/publish`
+- `GET /openapi.json`
+- `GET /docs` (Swagger UI)
+
+## Built-in middleware enabled
+
+- `requestId`
+- `requestLogger`
+- `cors`
+- `rateLimit`
+- `requestTimeout`
+- `securityHeaders`
+
+## First steps (local)
+
+1. Install dependencies from the monorepo root:
+
+```bash
+npm install
+```
+
+2. Copy the environment file:
+
+```bash
+cp apps/api-events-rabbitmq/.env.example apps/api-events-rabbitmq/.env.development
+```
+
+3. Make sure RabbitMQ is running locally and matches `RABBITMQ_URL`.
+
+4. Start the API:
+
+```bash
+npm run dev -w api-events-rabbitmq
+```
+
+5. Verify the app is running:
+
+```bash
+curl http://127.0.0.1:4004/health
+```
+
+## Publish your first event
+
+```bash
+curl -X POST http://127.0.0.1:4004/events/publish \
+  -H 'content-type: application/json' \
+  -d '{"message":"hello rabbitmq events"}'
+```
+
+Then list consumed events:
+
+```bash
+curl http://127.0.0.1:4004/events
+```
+
+## Docker quick start
+
+1. Create the Docker env file from the same template:
+
+```bash
+cp apps/api-events-rabbitmq/.env.example apps/api-events-rabbitmq/.env
+```
+
+2. Edit the Docker section in `apps/api-events-rabbitmq/.env` if you want custom RabbitMQ ports/queue setup.
+
+3. Start RabbitMQ + API using that `.env` file:
+
+```bash
+docker compose \
+  --env-file apps/api-events-rabbitmq/.env \
+  -f apps/api-events-rabbitmq/docker-compose.yml \
+  up --build
+```
+
+The API will be available at `http://127.0.0.1:${DOCKER_API_PORT}` (default `4004`).
+
+Compose services:
+
+- `rabbitmq`: RabbitMQ 3 (management image)
+- `api`: this Trinacria API

package/dist/templates/api-events-rabbitmq/docker-compose.yml

@@ -0,0 +1,30 @@
+services:
+  rabbitmq:
+    image: rabbitmq:3.13-management-alpine
+    ports:
+      - "${DOCKER_RABBITMQ_PORT}:5672"
+      - "${DOCKER_RABBITMQ_MANAGEMENT_PORT}:15672"
+    healthcheck:
+      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  api:
+    build:
+      context: ../..
+      dockerfile: apps/api-events-rabbitmq/Dockerfile
+    environment:
+      ENV: development
+      HOST: 0.0.0.0
+      PORT: 4004
+      OPENAPI_ENABLED: true
+      RABBITMQ_URL: ${DOCKER_RABBITMQ_URL}
+      RABBITMQ_EXCHANGE: ${DOCKER_RABBITMQ_EXCHANGE}
+      RABBITMQ_QUEUE_NAME: ${DOCKER_RABBITMQ_QUEUE_NAME}
+      RABBITMQ_ROUTING_PATTERN: ${DOCKER_RABBITMQ_ROUTING_PATTERN}
+    ports:
+      - "${DOCKER_API_PORT}:4004"
+    depends_on:
+      rabbitmq:
+        condition: service_healthy

package/dist/templates/api-events-rabbitmq/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "api-events-rabbitmq",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "start": "node ../../packages/cli/dist/index.js start",
+    "build": "node ../../packages/cli/dist/index.js build",
+    "dev": "node ../../packages/cli/dist/index.js dev"
+  },
+  "dependencies": {
+    "@trinacria/cli": "*",
+    "@trinacria/core": "*",
+    "@trinacria/events": "*",
+    "@trinacria/http": "*",
+    "@trinacria/schema": "*",
+    "amqplib": "^0.10.9"
+  },
+  "devDependencies": {
+    "@types/amqplib": "^0.10.8"
+  }
+}

package/dist/templates/api-events-rabbitmq/src/global/config.service.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createToken } from "@trinacria/core";
+import {
+  formatValidationError,
+  Infer,
+  s,
+  ValidationError,
+} from "@trinacria/schema";
+
+export const configSchema = s.object({
+  ENV: s.enum(["development", "staging", "production"]).default("development"),
+  PORT: s.number({ coerce: true, int: true, min: 1, max: 65535 }).default(4004),
+  HOST: s.string().default("127.0.0.1"),
+  OPENAPI_ENABLED: s.boolean({ coerce: true }).default(true),
+  CORS_ALLOWED_ORIGINS: s.array(s.string(), { coerce: true }).default([]),
+  RABBITMQ_URL: s.string(),
+  RABBITMQ_EXCHANGE: s.string().default("trinacria.events"),
+  RABBITMQ_QUEUE_NAME: s.string().default("api-events-rabbitmq.events"),
+  RABBITMQ_ROUTING_PATTERN: s.string().default("#"),
+});
+
+export type ConfigModel = Infer<typeof configSchema>;
+export const CONFIG_SERVICE = createToken<ConfigService>("CONFIG_SERVICE");
+
+export class ConfigService {
+  private readonly config: ConfigModel;
+
+  constructor() {
+    this.loadEnvFile();
+
+    try {
+      this.config = configSchema.parse(process.env);
+    } catch (error) {
+      if (error instanceof ValidationError) {
+        throw new Error(
+          formatValidationError(error, {
+            prefix: "Invalid environment configuration:",
+          }),
+        );
+      }
+
+      throw error;
+    }
+  }
+
+  private loadEnvFile() {
+    const currentEnv = process.env.ENV || "development";
+    const fileNames = [".env", `.env.${currentEnv}`];
+    const roots = [
+      process.cwd(),
+      path.join(process.cwd(), "apps/api-events-rabbitmq"),
+    ];
+
+    fileNames.forEach((fileName) => {
+      roots.forEach((root) => {
+        const filePath = path.join(root, fileName);
+        if (!fs.existsSync(filePath)) {
+          return;
+        }
+
+        const data = fs.readFileSync(filePath, "utf8");
+        data.split("\n").forEach((line) => {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith("#")) {
+            return;
+          }
+
+          const separatorIndex = trimmed.indexOf("=");
+          if (separatorIndex === -1) {
+            return;
+          }
+
+          const key = trimmed.slice(0, separatorIndex).trim();
+          const rawValue = trimmed.slice(separatorIndex + 1).trim();
+          const value =
+            (rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+            (rawValue.startsWith("'") && rawValue.endsWith("'"))
+              ? rawValue.slice(1, -1)
+              : rawValue;
+
+          process.env[key] = value;
+        });
+      });
+    });
+  }
+
+  get<K extends keyof ConfigModel>(key: K): ConfigModel[K] {
+    return this.config[key];
+  }
+
+  getAll(): ConfigModel {
+    return this.config;
+  }
+}

package/dist/templates/api-events-rabbitmq/src/global/controllers/swagger/docs.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>API Events RabbitMQ Docs</title>
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css"
+    />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        url: "/openapi.json",
+        dom_id: "#swagger-ui",
+        deepLinking: true,
+        tryItOutEnabled: true,
+        persistAuthorization: true,
+        presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+        layout: "StandaloneLayout",
+      });
+    </script>
+  </body>
+</html>

package/dist/templates/api-events-rabbitmq/src/global/controllers/swagger/swagger-docs.controller.ts

@@ -0,0 +1,79 @@
+import { createToken } from "@trinacria/core";
+import { HttpController, response } from "@trinacria/http";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { ConfigService } from "../../config.service";
+
+export const SWAGGER_DOCS_CONTROLLER = createToken<SwaggerDocsController>(
+  "SWAGGER_DOCS_CONTROLLER",
+);
+
+export class SwaggerDocsController extends HttpController {
+  constructor(private readonly config: ConfigService) {
+    super();
+  }
+
+  routes() {
+    return this.router()
+      .get("/docs", this.renderDocs, {
+        docs: {
+          excludeFromOpenApi: true,
+        },
+      })
+      .build();
+  }
+
+  async renderDocs() {
+    if (!this.config.get("OPENAPI_ENABLED")) {
+      return response({ message: "OpenAPI is disabled" }, { status: 404 });
+    }
+
+    return response(await readSwaggerHtml(), {
+      headers: {
+        "content-type": "text/html; charset=utf-8",
+        "content-security-policy": docsContentSecurityPolicy(),
+      },
+    });
+  }
+}
+
+let cachedSwaggerHtml: string | undefined;
+
+async function readSwaggerHtml(): Promise<string> {
+  if (cachedSwaggerHtml) {
+    return cachedSwaggerHtml;
+  }
+
+  const candidates = [
+    path.resolve(process.cwd(), "src/global/controllers/swagger/docs.html"),
+    path.resolve(
+      process.cwd(),
+      "apps/api-events-rabbitmq/src/global/controllers/swagger/docs.html",
+    ),
+  ];
+
+  for (const filePath of candidates) {
+    try {
+      cachedSwaggerHtml = await fs.readFile(filePath, "utf8");
+      return cachedSwaggerHtml;
+    } catch {
+      // keep trying next candidate
+    }
+  }
+
+  throw new Error("Swagger docs HTML template not found.");
+}
+
+function docsContentSecurityPolicy(): string {
+  return [
+    "default-src 'self'",
+    "base-uri 'self'",
+    "object-src 'none'",
+    "frame-ancestors 'none'",
+    "script-src 'self' 'unsafe-inline' https://unpkg.com",
+    "style-src 'self' 'unsafe-inline' https://unpkg.com",
+    "img-src 'self' data: blob:",
+    "font-src 'self' data: https://unpkg.com",
+    "connect-src 'self'",
+  ].join("; ");
+}

package/dist/templates/api-events-rabbitmq/src/global/rabbitmq.service.ts

@@ -0,0 +1,86 @@
+import { createToken } from "@trinacria/core";
+import type { RabbitMqChannelLike } from "@trinacria/events";
+import { connect, type Channel, type ChannelModel } from "amqplib";
+import type { ConfigService } from "./config.service";
+
+export const RABBITMQ_SERVICE =
+  createToken<RabbitMqService>("RABBITMQ_SERVICE");
+
+export class RabbitMqService {
+  private connection?: ChannelModel;
+  private channel?: Channel;
+
+  constructor(private readonly config: ConfigService) {}
+
+  async onInit(): Promise<void> {
+    if (!this.connection) {
+      this.connection = await connect(this.config.get("RABBITMQ_URL"));
+    }
+
+    if (!this.channel) {
+      this.channel = await this.connection.createChannel();
+    }
+  }
+
+  getChannel(): Channel {
+    if (!this.channel) {
+      throw new Error("RabbitMQ channel is not initialized.");
+    }
+
+    return this.channel;
+  }
+
+  getTransportChannel(): RabbitMqChannelLike {
+    const channel = this.getChannel();
+
+    return {
+      assertExchange: async (exchange, type, options) => {
+        await channel.assertExchange(exchange, type, options);
+      },
+      assertQueue: (queue, options) => channel.assertQueue(queue, options),
+      bindQueue: async (queue, exchange, pattern) => {
+        await channel.bindQueue(queue, exchange, pattern);
+      },
+      unbindQueue: async (queue, exchange, pattern) => {
+        await channel.unbindQueue(queue, exchange, pattern);
+      },
+      consume: async (queue, onMessage, options) => {
+        const consumeOk = await channel.consume(
+          queue,
+          async (message) => {
+            await onMessage(message);
+          },
+          options,
+        );
+
+        return { consumerTag: consumeOk.consumerTag };
+      },
+      cancel: async (consumerTag) => {
+        await channel.cancel(consumerTag);
+      },
+      publish: (exchange, routingKey, content, options) =>
+        channel.publish(exchange, routingKey, content, options),
+      ack: (message) => {
+        channel.ack(message as any);
+      },
+      nack: (message, allUpTo, requeue) => {
+        channel.nack(message as any, allUpTo, requeue);
+      },
+      deleteQueue: async (queue) => {
+        await channel.deleteQueue(queue);
+      },
+    };
+  }
+
+  async onDestroy(): Promise<void> {
+    if (this.channel) {
+      await this.channel.close();
+      this.channel = undefined;
+    }
+
+    if (this.connection) {
+      await this.connection.close();
+      this.connection = undefined;
+    }
+  }
+}

package/dist/templates/api-events-rabbitmq/src/global/register-global-controllers.ts

@@ -0,0 +1,20 @@
+import { TrinacriaApp } from "@trinacria/core";
+import { httpProvider } from "@trinacria/http";
+import { ConfigService, CONFIG_SERVICE } from "./config.service";
+import {
+  SWAGGER_DOCS_CONTROLLER,
+  SwaggerDocsController,
+} from "./controllers/swagger/swagger-docs.controller";
+
+export function registerGlobalControllers(
+  app: TrinacriaApp,
+  config: ConfigService,
+): void {
+  if (config.get("OPENAPI_ENABLED")) {
+    app.registerGlobalProvider(
+      httpProvider(SWAGGER_DOCS_CONTROLLER, SwaggerDocsController, [
+        CONFIG_SERVICE,
+      ]),
+    );
+  }
+}

package/dist/templates/api-events-rabbitmq/src/main.ts

@@ -0,0 +1,89 @@
+import { ConsoleLogger, TrinacriaApp, valueProvider } from "@trinacria/core";
+import { createEventsPlugin, RabbitMqEventTransport } from "@trinacria/events";
+import {
+  cors,
+  createHttpPlugin,
+  createSecurityHeadersBuilder,
+  rateLimit,
+  requestId,
+  requestLogger,
+  requestTimeout,
+} from "@trinacria/http";
+import { CONFIG_SERVICE, ConfigService } from "./global/config.service";
+import { RABBITMQ_SERVICE, RabbitMqService } from "./global/rabbitmq.service";
+import { registerGlobalControllers } from "./global/register-global-controllers";
+import { EventsModule } from "./modules/events/events.module";
+
+async function bootstrap() {
+  const app = new TrinacriaApp();
+  const configService = new ConfigService();
+  const config = configService.getAll();
+  const eventsLogger = new ConsoleLogger("api-events-rabbitmq:events");
+  const isProduction = config.ENV === "production";
+  const corsOrigins = config.CORS_ALLOWED_ORIGINS;
+  const securityHeadersMiddleware = createSecurityHeadersBuilder()
+    .preset(config.ENV)
+    .trustProxy(false)
+    .build();
+
+  const rabbitMqService = new RabbitMqService(configService);
+  await rabbitMqService.onInit();
+
+  app.registerGlobalProvider(valueProvider(CONFIG_SERVICE, configService));
+  app.registerGlobalProvider(valueProvider(RABBITMQ_SERVICE, rabbitMqService));
+  registerGlobalControllers(app, configService);
+
+  app.use(
+    createHttpPlugin({
+      host: config.HOST,
+      port: config.PORT,
+      middlewares: [
+        requestId(),
+        requestLogger({ includeUserAgent: !isProduction }),
+        cors({
+          origin: corsOrigins.length > 0 ? corsOrigins : "*",
+          credentials: true,
+          methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
+        }),
+        rateLimit({
+          windowMs: 60_000,
+          max: isProduction ? 240 : 2_000,
+          trustProxy: false,
+        }),
+        requestTimeout({ timeoutMs: 15_000 }),
+        securityHeadersMiddleware,
+      ],
+      openApi: config.OPENAPI_ENABLED
+        ? {
+            enabled: true,
+            title: "API Events RabbitMQ Example",
+            version: "1.0.0",
+          }
+        : undefined,
+    }),
+  );
+
+  app.use(
+    createEventsPlugin({
+      transport: new RabbitMqEventTransport({
+        channel: rabbitMqService.getTransportChannel(),
+        exchange: config.RABBITMQ_EXCHANGE,
+        queueName: config.RABBITMQ_QUEUE_NAME,
+        routingPattern: config.RABBITMQ_ROUTING_PATTERN,
+      }),
+      source: "api-events-rabbitmq",
+      dispatchLocalOnEmit: false,
+      onListenerError: (error, envelope) => {
+        eventsLogger.error(`Event listener error: ${envelope.name}`, error);
+      },
+    }),
+  );
+
+  await app.registerModule(EventsModule);
+  await app.start();
+}
+
+bootstrap().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/templates/api-events-rabbitmq/src/modules/events/dto/event.dto.ts

@@ -0,0 +1,24 @@
+import { s } from "@trinacria/schema";
+
+export interface EventDto {
+  id: string;
+  name: string;
+  payload: {
+    message: string;
+  };
+  receivedAt: Date;
+}
+
+export const EventDtoSchema = s.objectOf<EventDto>()(
+  {
+    id: s.string({ trim: true, minLength: 1 }),
+    name: s.string({ trim: true, minLength: 1 }),
+    payload: s.object({
+      message: s.string({ trim: true, minLength: 1 }),
+    }),
+    receivedAt: s.date(),
+  },
+  { strict: true },
+);
+
+export const EventListDtoSchema = s.array(EventDtoSchema);

package/dist/templates/api-events-rabbitmq/src/modules/events/dto/index.ts

@@ -0,0 +1,2 @@
+export * from "./event.dto";
+export * from "./publish-event.dto";

package/dist/templates/api-events-rabbitmq/src/modules/events/dto/publish-event.dto.ts

@@ -0,0 +1,12 @@
+import { s } from "@trinacria/schema";
+
+export interface PublishEventDto {
+  message: string;
+}
+
+export const PublishEventDtoSchema = s.objectOf<PublishEventDto>()(
+  {
+    message: s.string({ trim: true, minLength: 1 }),
+  },
+  { strict: true },
+);

package/dist/templates/api-events-rabbitmq/src/modules/events/events.controller.ts

@@ -0,0 +1,76 @@
+import { HttpController, HttpContext, response } from "@trinacria/http";
+import type { EventBus } from "@trinacria/events";
+import { EventListDtoSchema, PublishEventDtoSchema } from "./dto";
+import { DEMO_EVENT_NAME } from "./events.provider";
+import { EventsService } from "./events.service";
+
+export class EventsController extends HttpController {
+  constructor(
+    private readonly eventsService: EventsService,
+    private readonly eventBus: EventBus,
+  ) {
+    super();
+  }
+
+  routes() {
+    return this.router()
+      .get("/health", this.healthCheck, {
+        docs: {
+          tags: ["Health"],
+          summary: "Health check",
+        },
+      })
+      .get("/events", this.listEvents, {
+        docs: {
+          tags: ["Events"],
+          summary: "List consumed events",
+          responses: {
+            200: {
+              description: "Consumed events",
+              schema: EventListDtoSchema.toOpenApi(),
+            },
+          },
+        },
+      })
+      .post("/events/publish", this.publishEvent, {
+        docs: {
+          tags: ["Events"],
+          summary: "Publish demo event to RabbitMQ transport",
+          requestBody: {
+            required: true,
+            schema: PublishEventDtoSchema.toOpenApi(),
+          },
+          responses: {
+            202: {
+              description: "Event accepted",
+            },
+          },
+        },
+      })
+      .build();
+  }
+
+  healthCheck() {
+    return { status: "ok" };
+  }
+
+  listEvents() {
+    return this.eventsService.list();
+  }
+
+  async publishEvent(ctx: HttpContext) {
+    const payload = PublishEventDtoSchema.parse(ctx.body);
+
+    await this.eventBus.emit(DEMO_EVENT_NAME, {
+      message: payload.message,
+    });
+
+    return response(
+      {
+        status: "accepted",
+        event: DEMO_EVENT_NAME,
+      },
+      { status: 202 },
+    );
+  }
+}

package/dist/templates/api-events-rabbitmq/src/modules/events/events.module.ts

@@ -0,0 +1,27 @@
+import { classProvider, defineModule } from "@trinacria/core";
+import { EVENT_BUS_TOKEN, eventProvider } from "@trinacria/events";
+import { httpProvider } from "@trinacria/http";
+import {
+  EVENTS_CONTROLLER,
+  EVENTS_PROVIDER,
+  EVENTS_SERVICE,
+  EVENTS_STORE,
+} from "./events.tokens";
+import { EventsController } from "./events.controller";
+import { EventsProvider } from "./events.provider";
+import { EventsService } from "./events.service";
+import { EventsStore } from "./events.store";
+
+export const EventsModule = defineModule({
+  name: "EventsModule",
+  providers: [
+    classProvider(EVENTS_STORE, EventsStore),
+    classProvider(EVENTS_SERVICE, EventsService, [EVENTS_STORE]),
+    httpProvider(EVENTS_CONTROLLER, EventsController, [
+      EVENTS_SERVICE,
+      EVENT_BUS_TOKEN,
+    ]),
+    eventProvider(EVENTS_PROVIDER, EventsProvider, [EVENTS_SERVICE]),
+  ],
+  exports: [EVENTS_SERVICE, EVENTS_CONTROLLER, EVENTS_PROVIDER],
+});