create-nexwire 4.2.5 → 4.4.0

package/fastify/src/config/database.ts

@@ -0,0 +1,48 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: Database connection settings.
+ * When: Database bootstrap and dialect detection.
+ * Where: src/config/database.ts.
+ * How: Only DATABASE_URL is required. Pool settings use generic,
+ *      provider-agnostic defaults.
+ */
+
+const rawUrl = env.DATABASE_URL;
+
+export const databaseConfig = {
+  // If it's sqlite, convert "sqlite:./db.sqlite" to "file:./db.sqlite"
+  url: rawUrl.startsWith("sqlite:") ? `file:${rawUrl.slice("sqlite:".length)}` : rawUrl,
+
+  /** Generic, sensible pool defaults for any provider */
+  pool: {
+    max: 10,
+    idleTimeout: 20000, // ms
+    connectTimeout: 10000, // ms
+    keepAlive: true
+  },
+
+  /**
+   * Default to true. If a provider (like a pooler) doesn't support it,
+   * they usually indicate this in the connection string or require the user
+   * to handle it at the driver level.
+   */
+  prepare: true,
+
+  /**
+   * Require TLS for MySQL and PostgreSQL connections. Set this to true, or
+   * append `?sslmode=require` to DATABASE_URL if your provider documents that.
+   */
+  ssl: false
+};
+
+export type DatabaseConfig = typeof databaseConfig;
+
+export function detectDialectFrom(url: string): "sqlite" | "mysql" | "postgresql" {
+  const value = url.toLowerCase();
+  if (value.startsWith("mysql")) return "mysql";
+  if (value.startsWith("postgres")) return "postgresql";
+  return "sqlite";
+}
+
+export const databaseDialect = detectDialectFrom(rawUrl);

package/fastify/src/config/index.ts

@@ -0,0 +1,83 @@
+import { type AppConfig, appConfig } from "./app.js";
+import { type AuthConfig, authConfig } from "./auth.js";
+import { type CacheConfig, cacheConfig } from "./cache.js";
+import { type CookieConfig, cookieConfig } from "./cookie.js";
+import { type CorsConfig, corsConfig } from "./cors.js";
+import { type DatabaseConfig, databaseConfig } from "./database.js";
+import { type JwtConfig, jwtConfig } from "./jwt.js";
+import { type LoggingConfig, loggingConfig } from "./logging.js";
+import { type MailConfig, mailConfig } from "./mail.js";
+import { type OpenApiConfig, openApiConfig } from "./openapi.js";
+import { type QueueConfig, queueConfig } from "./queue.js";
+import { type RateLimitConfig, rateLimitConfig } from "./rateLimit.js";
+import { type RealtimeConfig, realtimeConfig } from "./realtime.js";
+import { type RedisConfig, redisConfig } from "./redis.js";
+import { type SecurityConfig, securityConfig } from "./security.js";
+import { type SessionConfig, sessionConfig } from "./session.js";
+import { type StorageConfig, storageConfig } from "./storage.js";
+
+export { appConfig } from "./app.js";
+export { authConfig } from "./auth.js";
+export { cacheConfig } from "./cache.js";
+export { cookieConfig } from "./cookie.js";
+export { corsConfig } from "./cors.js";
+export { databaseConfig, databaseDialect, detectDialectFrom } from "./database.js";
+export { jwtConfig } from "./jwt.js";
+export { loggingConfig } from "./logging.js";
+export { mailConfig } from "./mail.js";
+export { openApiConfig } from "./openapi.js";
+export { queueConfig } from "./queue.js";
+export { rateLimitConfig } from "./rateLimit.js";
+export { realtimeConfig } from "./realtime.js";
+export { redisConfig } from "./redis.js";
+export { securityConfig } from "./security.js";
+export { sessionConfig } from "./session.js";
+export { storageConfig } from "./storage.js";
+
+/**
+ * Why: Single import point for every config domain.
+ * When: Application code needs configuration values.
+ * Where: Imported as `import { config } from "@/config/index.js"`.
+ * How: Aggregates per-domain config objects; individual files remain the
+ *      place to edit each setting.
+ */
+export const config = {
+  app: appConfig,
+  auth: authConfig,
+  cache: cacheConfig,
+  cookie: cookieConfig,
+  cors: corsConfig,
+  database: databaseConfig,
+  jwt: jwtConfig,
+  logging: loggingConfig,
+  mail: mailConfig,
+  openApi: openApiConfig,
+  queue: queueConfig,
+  rateLimit: rateLimitConfig,
+  realtime: realtimeConfig,
+  redis: redisConfig,
+  session: sessionConfig,
+  security: securityConfig,
+  storage: storageConfig
+} as const;
+
+export type Config = typeof config;
+export type {
+  AppConfig,
+  AuthConfig,
+  CacheConfig,
+  CookieConfig,
+  CorsConfig,
+  DatabaseConfig,
+  JwtConfig,
+  LoggingConfig,
+  MailConfig,
+  OpenApiConfig,
+  QueueConfig,
+  RateLimitConfig,
+  RealtimeConfig,
+  RedisConfig,
+  SecurityConfig,
+  SessionConfig,
+  StorageConfig
+};

package/fastify/src/config/jwt.ts

@@ -0,0 +1,19 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: JWT signing and lifetime settings.
+ * When: Access/refresh token generation and verification.
+ * Where: src/config/jwt.ts.
+ * How: Signing secrets are confidential and stay in .env. Expiries are plain
+ *      literals you can tune here (seconds).
+ */
+export const jwtConfig = {
+  accessSecret: env.JWT_ACCESS_SECRET,
+  refreshSecret: env.JWT_REFRESH_SECRET,
+  accessExpirySeconds: 900,
+  refreshExpirySeconds: 3600,
+  refreshRememberExpirySeconds: 2592000,
+  algorithm: "HS256" as const
+};
+
+export type JwtConfig = typeof jwtConfig;

package/fastify/src/config/logging.ts

@@ -0,0 +1,13 @@
+/**
+ * Why: Logging behavior shared by the framework logger and HTTP request log.
+ * When: Logger bootstrap and global HTTP middleware.
+ * Where: src/config/logging.ts.
+ * How: Plain literals — edit directly. `httpRequests` mirrors the old
+ *      `LOG_HTTP` switch: set `false` to quiet per-request console logs.
+ */
+export const loggingConfig = {
+  level: "info",
+  httpRequests: true
+};
+
+export type LoggingConfig = typeof loggingConfig;

package/fastify/src/config/mail.ts

@@ -0,0 +1,24 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: SMTP mail transport settings.
+ * When: Transactional mail (signup, reset, verify) is sent.
+ * Where: src/config/mail.ts.
+ * How: Host, ports, encryption, from address and fail-silent are plain
+ *      literals. Username/password are credentials and stay in .env.
+ */
+export const mailConfig = {
+  host: "127.0.0.1",
+  port: 1089,
+  encryption: "none",
+  username: env.MAIL_USERNAME,
+  password: env.MAIL_PASSWORD,
+  fromAddress: "no-reply@example.com",
+  failSilent: true,
+  maildev: {
+    smtpPort: 1089,
+    webPort: 1080
+  }
+};
+
+export type MailConfig = typeof mailConfig;

package/fastify/src/config/openapi.ts

@@ -0,0 +1,36 @@
+import { appConfig } from "./app.js";
+
+/**
+ * Why: OpenAPI documentation settings — API metadata and Scalar UI presentation.
+ * When: OPEN_API=true during app boot.
+ * Where: src/config/openapi.ts.
+ * How: Edit this file to customise your API title, version, description,
+ *      and the Scalar docs UI appearance.
+ */
+export const openApiConfig = {
+  version: "3.0.0",
+  title: `${appConfig.name} API`,
+  apiVersion: "1.0.0",
+  description: "",
+
+  /** Scalar docs UI settings */
+  scalar: {
+    specUrl: "/doc", // URL path to the OpenAPI JSON spec
+    docsPath: "/api-docs", // URL path to the interactive docs UI
+    layout: "classic" as const, // UI layout: "classic" or "modern"
+    /** UI theme: "default", "moon", "purple", "solarized", "bluePlanet", "fastify", "kepler", "mars", "nebula", "none" */
+    theme: "moon" as const,
+    pageTitle: `${appConfig.name} API`, // HTML page title for the /api-docs page
+    /** Favicon file (project-relative) served at /favicon.ico for the /api-docs page */
+    favicon: "src/resources/src/assets/images/favicon/favicon.ico",
+    /** Default HTTP client shown in code examples */
+    defaultHttpClient: {
+      targetKey: "js" as const,
+      clientKey: "fetch" as const
+    },
+    defaultOpenAllTags: true, // Expand all tags on load
+    showDeveloperTools: "never"
+  }
+} as const;
+
+export type OpenApiConfig = typeof openApiConfig;

package/fastify/src/config/queue.ts

@@ -0,0 +1,30 @@
+import { redisConfig } from "./redis.js";
+
+/**
+ * Why: Queue workers, concurrency, and BullMQ key namespaces.
+ * When: The queue facade bootstraps workers and the dashboard connects.
+ * Where: src/config/queue.ts.
+ * How: `queues` lists which queue names get a worker by default (default,
+ *      mail, maintenance). `concurrency` caps parallel jobs per worker.
+ *      Key prefixes derive from the shared `REDIS_PREFIX`.
+ */
+export const queueConfig = {
+  queues: ["default", "mail", "maintenance"],
+  concurrency: 10,
+  /**
+   * autoPruneQueues
+   * Why: Automatically deletes phantom queues (Redis keys for queue names that
+   *      no longer exist in `queues`) when a queue worker boots. Safe because
+   *      only empty, unconfigured queues are removed, and BullMQ recreates a
+   *      queue's keys on demand if code still dispatches to it.
+   * When: Set false to disable automatic pruning and rely on manual
+   *      `queue:clear` instead.
+   */
+  autoPruneQueues: true,
+  prefix: `${redisConfig.prefix}:queue`,
+  durablePrefix: `${redisConfig.prefix}:durable`,
+  queueUi: "/queues",
+  allowedEmails: "" // Comma-separated list of email addresses allowed to access the queue UI. Empty means no restriction.
+};
+
+export type QueueConfig = typeof queueConfig;

package/fastify/src/config/rateLimit.ts

@@ -0,0 +1,17 @@
+import { redisConfig } from "./redis.js";
+
+/**
+ * Why: HTTP rate limiting policy and Redis key namespace.
+ * When: Global and login-specific rate limiters are built.
+ * Where: src/config/rateLimit.ts.
+ * How: Limits are plain literals; `keyPrefix` is derived from the shared
+ *      `REDIS_PREFIX` (`nexwire:rl:*` by default).
+ */
+export const rateLimitConfig = {
+  windowMs: 60000,
+  maxRequests: 500,
+  loginMaxRequests: 60,
+  keyPrefix: `${redisConfig.prefix}:rl`
+};
+
+export type RateLimitConfig = typeof rateLimitConfig;

package/fastify/src/config/realtime.ts

@@ -0,0 +1,15 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: Realtime (Socket.IO) settings.
+ * When: The realtime server bootstraps and registers its HTTP path.
+ * Where: src/config/realtime.ts.
+ * How: Reads `SOCKET` from env. `enabled` flips the WebSocket server
+ *      on/off; the admin UI is served when the environment is not production.
+ */
+export const realtimeConfig = {
+  enabled: env.SOCKET,
+  path: "/socket.io"
+};
+
+export type RealtimeConfig = typeof realtimeConfig;

package/fastify/src/config/redis.ts

@@ -0,0 +1,18 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: Redis connection and namespace settings.
+ * When: Cache, session, queue, events, and the queue dashboard bootstrap.
+ * Where: src/config/redis.ts.
+ * How: `prefix` is shared by cache/session/queue/events, so it stays in .env
+ *      (`REDIS_PREFIX`) and every namespace derives from it here. `enabled`
+ *      and the commander port are literals you can change here.
+ */
+export const redisConfig = {
+  enabled: env.REDIS,
+  url: env.REDIS_URL,
+  prefix: env.REDIS_PREFIX,
+  commanderPort: 1369
+};
+
+export type RedisConfig = typeof redisConfig;

package/fastify/src/config/security.ts

@@ -0,0 +1,44 @@
+// config/security.ts
+import { env } from "@/env.js";
+
+const isProd = env.APP_ENV === "production";
+
+/**
+ * Dev CSP is intentionally lax so HMR / inline bootstrap scripts work.
+ * Prod CSP is strict and blocks unsafe-inline.
+ *
+ * NOTE: if you serve a bundled SPA (Vite/Next) in prod, you MUST add
+ * either a nonce, a hash, or 'unsafe-inline' to script-src — otherwise
+ * the inline bootstrap script will be blocked, exactly as you saw.
+ */
+const csp = isProd
+  ? [
+      "default-src 'self'",
+      "script-src 'self' https://cdn.jsdelivr.net",         // Scalar UI loads its bundle from jsdelivr CDN
+      "style-src 'self' https://cdn.jsdelivr.net 'unsafe-inline'",
+      "img-src 'self' data: blob: https://cdn.jsdelivr.net",
+      "font-src 'self' data: https://cdn.jsdelivr.net https://fonts.scalar.com",
+      "connect-src 'self' https://cdn.jsdelivr.net https://api.scalar.com",
+      "frame-ancestors 'none'",
+      "base-uri 'self'",
+      "form-action 'self'"
+    ].join("; ")
+  : [
+      "default-src 'self'",
+      "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.jsdelivr.net",
+      "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net",
+      "img-src 'self' data: blob: https://cdn.jsdelivr.net",
+      "font-src 'self' data: https://cdn.jsdelivr.net https://fonts.scalar.com",
+      "connect-src 'self' ws: wss: https://cdn.jsdelivr.net https://api.scalar.com",   // HMR websocket + Scalar
+      "frame-ancestors 'none'"
+    ].join("; ");
+
+export const securityConfig = {
+  enabled: env.SECURITY_HEADERS,
+  csp,
+  hsts: env.APP_ENV === "production",
+  hstsMaxAge: "max-age=31536000; includeSubDomains",
+  xFrame: "DENY"
+};
+
+export type SecurityConfig = typeof securityConfig;

package/fastify/src/config/session.ts

@@ -0,0 +1,17 @@
+import { cookieConfig } from "./cookie.js";
+import { redisConfig } from "./redis.js";
+
+/**
+ * Why: Server-side session cookie and lifetime settings.
+ * When: Session middleware creates/refreshes sessions for each request.
+ * Where: src/config/session.ts.
+ * How: `cookieName` and `ttlSeconds` are plain literals; `keyPrefix` is
+ *      derived from the shared `REDIS_PREFIX` (`nexwire:session:*` by default).
+ */
+export const sessionConfig = {
+  cookieName: `${cookieConfig.name}_session`,
+  ttlSeconds: 7200,
+  keyPrefix: `${redisConfig.prefix}:session`
+};
+
+export type SessionConfig = typeof sessionConfig;

package/fastify/src/config/storage.ts

@@ -0,0 +1,22 @@
+import { env } from "@/env.js";
+
+/**
+ * Why: File storage settings for local and S3 backends.
+ * When: Storage facade bootstrap and file operations.
+ * Where: src/config/storage.ts.
+ * How: Driver, disk, region and TTL are plain literals you can change here.
+ *      Credentials (access key, secret) are confidential and stay in .env.
+ */
+export const storageConfig = {
+  driver: "local",
+  defaultDisk: "public",
+  bucket: "",
+  region: "us-east-1",
+  endpoint: "",
+  forcePathStyle: false,
+  signedUrlTtlSeconds: 900,
+  accessKeyId: env.STORAGE_ACCESS_KEY_ID,
+  secretAccessKey: env.STORAGE_SECRET_ACCESS_KEY
+};
+
+export type StorageConfig = typeof storageConfig;

package/fastify/src/config/validate.ts

@@ -0,0 +1,50 @@
+import { databaseConfig } from "./database.js";
+import { mailConfig } from "./mail.js";
+import { redisConfig } from "./redis.js";
+import { storageConfig } from "./storage.js";
+
+/**
+ * Why: Validates that resolved configs are internally consistent at startup.
+ * When: Called before any framework subsystem initializes.
+ * Where: kernel.ts, before storage.init() and initRedis().
+ * How: Checks cross-config dependencies and throws clear errors for inconsistencies.
+ */
+export function validateConfig(): void {
+  if (!databaseConfig.url) {
+    throw new Error("DATABASE_URL is required but is empty");
+  }
+
+  if (storageConfig.driver === "s3") {
+    if (!storageConfig.bucket) {
+      throw new Error("STORAGE_BUCKET is required when storage driver is s3");
+    }
+    if (!storageConfig.accessKeyId || !storageConfig.secretAccessKey) {
+      throw new Error("STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY are required when storage driver is s3");
+    }
+  }
+
+  if (redisConfig.enabled) {
+    try {
+      const url = new URL(redisConfig.url);
+
+      // Ensure it starts with redis:// or rediss://
+      if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
+        throw new Error("URL must start with redis:// or rediss://");
+      }
+
+      // Hostname is mandatory (e.g., localhost, 127.0.0.1, redis-container)
+      if (!url.hostname) {
+        throw new Error("URL must include a valid hostname");
+      }
+
+      // Note: We do NOT check if the port is empty.
+      // ioredis automatically defaults to 6379 if no port is provided.
+    } catch (error) {
+      throw new Error(`REDIS_URL is invalid: "${redisConfig.url}" — ${error instanceof Error ? error.message : error}`);
+    }
+  }
+
+  if (!mailConfig.failSilent && !mailConfig.username) {
+    throw new Error("MAIL_USERNAME is required when MAIL_FAIL_SILENT is false");
+  }
+}

package/fastify/src/database/migrations/sqlite/0000_init.sql

@@ -0,0 +1,48 @@
+CREATE TABLE `roles` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `roles_name_unique` ON `roles` (`name`);--> statement-breakpoint
+CREATE TABLE `email_verification_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`email` text NOT NULL,
+	`token` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `password_reset_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`email` text NOT NULL,
+	`token` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `refresh_tokens` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`user_id` integer,
+	`jti` text NOT NULL,
+	`revoked` integer DEFAULT false,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE cascade ON DELETE set null
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `refresh_tokens_jti_unique` ON `refresh_tokens` (`jti`);--> statement-breakpoint
+CREATE TABLE `users` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`email` text NOT NULL,
+	`password` text NOT NULL,
+	`role_id` integer,
+	`email_verified_at` integer,
+	`created_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	`updated_at` integer DEFAULT (cast((julianday('now') - 2440587.5)*86400000 as integer)) NOT NULL,
+	FOREIGN KEY (`role_id`) REFERENCES `roles`(`id`) ON UPDATE cascade ON DELETE set null
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `users_email_unique` ON `users` (`email`);