create-nexwire 4.3.0 → 4.4.0

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`);

package/fastify/src/database/migrations/sqlite/meta/0000_snapshot.json

@@ -0,0 +1,324 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "af502348-be37-45c6-84e4-df4db9f31bfb",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "roles": {
+      "name": "roles",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "roles_name_unique": {
+          "name": "roles_name_unique",
+          "columns": [
+            "name"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "email_verification_tokens": {
+      "name": "email_verification_tokens",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "password_reset_tokens": {
+      "name": "password_reset_tokens",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "refresh_tokens": {
+      "name": "refresh_tokens",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "jti": {
+          "name": "jti",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "refresh_tokens_jti_unique": {
+          "name": "refresh_tokens_jti_unique",
+          "columns": [
+            "jti"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "refresh_tokens_user_id_users_id_fk": {
+          "name": "refresh_tokens_user_id_users_id_fk",
+          "tableFrom": "refresh_tokens",
+          "tableTo": "users",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "users": {
+      "name": "users",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role_id": {
+          "name": "role_id",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "email_verified_at": {
+          "name": "email_verified_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast((julianday('now') - 2440587.5)*86400000 as integer))"
+        }
+      },
+      "indexes": {
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "columns": [
+            "email"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {
+        "users_role_id_roles_id_fk": {
+          "name": "users_role_id_roles_id_fk",
+          "tableFrom": "users",
+          "tableTo": "roles",
+          "columnsFrom": [
+            "role_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "cascade"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/fastify/src/database/migrations/sqlite/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1793719238470,
+      "tag": "0000_init",
+      "breakpoints": true
+    }
+  ]
+}

package/fastify/src/database/schema.ts

@@ -0,0 +1,2 @@
+export * from "../modules/auth/database/models/role.js";
+export * from "../modules/auth/database/models/user.js";

package/fastify/src/env.ts

@@ -0,0 +1,76 @@
+import { config } from "dotenv";
+import { expand } from "dotenv-expand";
+import { z } from "zod";
+
+expand(config({ override: true }));
+
+const envSchema = z
+  .object({
+    APP_NAME: z.string().default("nexwire"),
+    APP_ENV: z.enum(["development", "production", "test"]).default("development"),
+    APP_PORT: z.coerce.number().default(3000),
+    APP_URL: z.string().trim().min(1, "APP_URL is required in .env"),
+    UI: z
+      .string()
+      .default("true")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0"),
+    FRONTEND_URL: z
+      .string()
+      .optional()
+      .transform((value) => value?.trim() || undefined),
+    DATABASE_URL: z.string().default("sqlite:./src/storage/database/nexwire.sqlite"),
+    REDIS: z
+      .string()
+      .default("false")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0"),
+    REDIS_URL: z.string().default("redis://127.0.0.1:6379"),
+    REDIS_PREFIX: z
+      .string()
+      .default("nexwire")
+      .transform((value) => value.trim()),
+    JWT_ACCESS_SECRET: z.string(),
+    JWT_REFRESH_SECRET: z.string(),
+    COOKIE_SECRET: z.string(),
+    STORAGE_ACCESS_KEY_ID: z
+      .string()
+      .optional()
+      .transform((value) => value?.trim() || undefined),
+    STORAGE_SECRET_ACCESS_KEY: z
+      .string()
+      .optional()
+      .transform((value) => value?.trim() || undefined),
+    MAIL_USERNAME: z.string().default(""),
+    MAIL_PASSWORD: z.string().default(""),
+    OPEN_API: z
+      .string()
+      .default("true")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0"),
+    SOCKET: z
+      .string()
+      .default("false")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0"),
+    SECURITY_HEADERS: z
+      .string()
+      .default("true")
+      .transform((value) => value.trim().toLowerCase() !== "false" && value.trim() !== "0")
+  })
+  .superRefine((data, ctx) => {
+    for (const key of ["JWT_ACCESS_SECRET", "JWT_REFRESH_SECRET", "COOKIE_SECRET"] as const) {
+      if (!data[key]) {
+        ctx.addIssue({
+          code: "custom",
+          path: [key],
+          message: `${key} is required`
+        });
+      }
+    }
+  });
+
+const parsedEnv = envSchema.parse(process.env);
+
+export const env = {
+  ...parsedEnv,
+  FRONTEND_URL: parsedEnv.FRONTEND_URL
+};
+
+export type Env = typeof env;

package/fastify/src/framework/cache/cache.ts

@@ -0,0 +1,114 @@
+import { cacheConfig, redisConfig } from "@/config/index.js";
+import { createCircuitBreaker, isCircuitBreakerError } from "@/framework/circuit-breaker/cb.js";
+import { redisClientIfReady } from "@/framework/redis/client.js";
+
+function cacheKey(key: string) {
+  return `${cacheConfig.keyPrefix}:${key}`;
+}
+
+// Initialize the circuit breaker specifically for Cache operations
+const cacheBreaker = createCircuitBreaker({
+  name: "Redis Cache",
+  failureThreshold: 3,
+  resetTimeout: 30000
+});
+
+/**
+ * Why: Provides Redis-backed cache helpers with graceful fallback behavior.
+ * When: Controllers/jobs need temporary computed data caching.
+ * Where: Application module code via facade.
+ * How: Uses namespaced Redis keys and JSON serialization.
+ */
+export const cache = {
+  /**
+   * Why: Reads cached JSON value by key.
+   * When: A feature wants fast lookup before recomputing.
+   * Where: Controllers/jobs/services using shared cache.
+   * How: Fetches namespaced Redis key and parses JSON.
+   */
+  async get<T>(key: string, fallback: T | null = null) {
+    const client = redisClientIfReady();
+    // If the client isn't connected at all, fail fast to fallback
+    if (!client) return fallback;
+
+    try {
+      return await cacheBreaker.exec(async () => {
+        const value = await client.get(cacheKey(key));
+        return value ? (JSON.parse(value) as T) : fallback;
+      });
+    } catch (error) {
+      // If the circuit is open, or a Redis error occurs, return the fallback safely
+      if (isCircuitBreakerError(error)) return fallback;
+      return fallback;
+    }
+  },
+
+  async set(key: string, value: unknown, ttl = cacheConfig.ttlSeconds) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    try {
+      return await cacheBreaker.exec(async () => {
+        await client.set(cacheKey(key), JSON.stringify(value), "EX", ttl);
+        return true;
+      });
+    } catch (error) {
+      // If the circuit is open, or a Redis error occurs, silently fail
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
+  },
+
+  /**
+   * @deprecated Use set() instead.
+   */
+  async put(key: string, value: unknown, ttl = cacheConfig.ttlSeconds) {
+    return this.set(key, value, ttl);
+  },
+
+  /**
+   * Why: Deletes a cached value by key.
+   * When: Cached data becomes stale or must be invalidated.
+   * Where: Write/update flows that change source data.
+   * How: Removes namespaced Redis cache key.
+   */
+  async forget(key: string) {
+    const client = redisClientIfReady();
+    if (!client) return false;
+
+    try {
+      return await cacheBreaker.exec(async () => {
+        await client.del(cacheKey(key));
+        return true;
+      });
+    } catch (error) {
+      if (isCircuitBreakerError(error)) return false;
+      return false;
+    }
+  },
+
+  /**
+   * Why: Returns cached value or computes/stores a fresh one.
+   * When: A feature needs cache-aside behavior.
+   * Where: Read paths with potentially expensive callbacks.
+   * How: Attempts get first, then executes callback and put.
+   */
+  async remember<T>(key: string, ttl: number, callback: () => Promise<T>) {
+    const cached = await cache.get<T>(key);
+    if (cached !== null) return cached;
+
+    const fresh = await callback();
+    await this.set(key, fresh, ttl);
+    return fresh;
+  },
+
+  /**
+   * Why: Indicates whether Redis cache backend is currently usable.
+   * When: Runtime checks need to branch on cache availability.
+   * Where: Health/status endpoints and conditional flows.
+   * How: Confirms REDIS flag and ready Redis client instance.
+   */
+  isAvailable() {
+    return redisConfig.enabled && redisClientIfReady() !== null && cacheBreaker.getState() !== "open";
+  }
+};