create-rebe 1.0.0

package/template/core/express.core.js

@@ -0,0 +1,161 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const http = require('http')
+const crypto = require('crypto')
+
+const express = require('express')
+const helmet = require('helmet')
+const compression = require('compression')
+const rateLimit = require('express-rate-limit')
+const multer = require('multer')
+
+const config = require('@config/index')
+const logger = require('@core/logger.core')
+const ErrorHandler = require('@core/error.core')
+const Register = require('@core/register.core')
+
+const Routes = require('@refkinscallv/express-routing')
+
+const MIDDLEWARE_REGISTER = Register.path('app', 'http', 'middlewares', 'register.middleware.js')
+
+// HTTP backbone. Builds the Express app and an http.Server without listening, so
+// the socket core can attach to the same server before the port is opened.
+class Express {
+	static app = null
+	static server = null
+
+	// Build the app + server once (idempotent). Returns { app, server }.
+	static async create() {
+		if (Express.app && Express.server) return { app: Express.app, server: Express.server }
+
+		const app = express()
+
+		app.disable('x-powered-by')
+		if (config.express.trustProxy) app.set('trust proxy', config.express.trustProxy)
+
+		app.use(helmet(config.express.helmet))
+		app.use(config.cors.express)
+		app.use(compression())
+		app.use(express.json({ limit: config.express.bodyLimit }))
+		app.use(express.urlencoded({ extended: true, limit: config.express.bodyLimit }))
+
+		if (config.express.rateLimit.enabled) {
+			app.use(
+				rateLimit({
+					windowMs: config.express.rateLimit.windowMs,
+					max: config.express.rateLimit.max,
+					standardHeaders: config.express.rateLimit.standardHeaders,
+					legacyHeaders: config.express.rateLimit.legacyHeaders,
+					message: config.express.rateLimit.message,
+				}),
+			)
+		}
+
+		Express._applyUserMiddleware(app)
+		Express._applyStatic(app)
+		await Express._applyRoutes(app)
+		Express._applyErrorHandling(app)
+
+		Express.app = app
+		Express.server = http.createServer(app)
+		return { app, server: Express.server }
+	}
+
+	// Global application middleware: app/http/middlewares/register.middleware.js
+	// exports (app) => { ... }.
+	static _applyUserMiddleware(app) {
+		const register = Register.require(MIDDLEWARE_REGISTER, { label: 'app/http/middlewares/register.middleware.js' })
+		if (typeof register === 'function') register(app)
+	}
+
+	// Serve ./public at the root and uploaded files under /uploads. The whole
+	// storage root is intentionally NOT exposed — it may hold private files.
+	static _applyStatic(app) {
+		const root = process.cwd()
+
+		const publicDir = path.join(root, 'public')
+		if (fs.existsSync(publicDir)) app.use(express.static(publicDir))
+
+		const uploadDir = path.resolve(root, config.storage.uploadPath)
+		if (fs.existsSync(uploadDir)) {
+			app.use(
+				'/uploads',
+				express.static(uploadDir, {
+					// nosniff stops browsers from re-interpreting an uploaded file's
+					// content-type (e.g. treating an image as HTML).
+					setHeaders: (res) => res.setHeader('X-Content-Type-Options', 'nosniff'),
+				}),
+			)
+		}
+	}
+
+	// Mount application routes. register.route loads web + api routes as a side
+	// effect, then Routes.apply binds them onto a router and app.use()s it.
+	static async _applyRoutes(app) {
+		require('@routes/register.route')
+		await Routes.apply(app, express.Router())
+	}
+
+	static _applyErrorHandling(app) {
+		app.use(ErrorHandler.notFoundHandler)
+		app.use(ErrorHandler.expressErrorHandler)
+	}
+
+	static listen() {
+		return new Promise((resolve, reject) => {
+			if (!Express.server) {
+				return reject(new Error('Express.create() must be called before listen()'))
+			}
+			Express.server.once('error', reject)
+			Express.server.listen(config.app.port, () => {
+				logger.info(`HTTP server listening on ${config.app.url} (port ${config.app.port})`)
+				resolve(Express.server)
+			})
+		})
+	}
+
+	static close() {
+		return new Promise((resolve) => {
+			if (!Express.server) return resolve()
+			Express.server.close(() => {
+				Express.server = null
+				Express.app = null
+				logger.info('HTTP server closed')
+				resolve()
+			})
+		})
+	}
+
+	// Build a multer middleware from storage config. Filenames are randomised to
+	// avoid path traversal and collisions; size and mime-type are constrained.
+	static upload(field) {
+		const uploadDir = path.resolve(process.cwd(), config.storage.uploadPath)
+		fs.mkdirSync(uploadDir, { recursive: true })
+
+		const storage = multer.diskStorage({
+			destination: (req, file, cb) => cb(null, uploadDir),
+			filename: (req, file, cb) => {
+				const ext = path
+					.extname(file.originalname)
+					.toLowerCase()
+					.replace(/[^.a-z0-9]/g, '')
+				cb(null, `${Date.now()}-${crypto.randomBytes(8).toString('hex')}${ext}`)
+			},
+		})
+
+		const limits = { fileSize: config.storage.maxSizeMb * 1024 * 1024 }
+
+		const fileFilter = (req, file, cb) => {
+			const allowed = config.storage.allowedTypes
+			if (!allowed.length || allowed.includes(file.mimetype)) return cb(null, true)
+			cb(new Error(`Unsupported file type: ${file.mimetype}`))
+		}
+
+		const instance = multer({ storage, limits, fileFilter })
+		return field ? instance.single(field) : instance
+	}
+}
+
+module.exports = Express

package/template/core/hooks.core.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const logger = require('@core/logger.core')
+const Register = require('@core/register.core')
+
+const REGISTER_FILE = Register.path('app', 'hooks', 'register.hook.js')
+const STAGES = ['before', 'after', 'shutdown']
+
+// Application lifecycle hooks. The bootstrap core invokes `before` (after config
+// is ready, before services start), `after` (once the server is listening), and
+// `shutdown` (on SIGINT/SIGTERM). Handlers live in app/hooks/register.hook.js.
+class Hooks {
+	static _handlers = undefined
+
+	static _resolve() {
+		if (Hooks._handlers === undefined) {
+			Hooks._handlers = Register.object(REGISTER_FILE, STAGES, { label: 'app/hooks/register.hook.js' }) || {}
+		}
+		return Hooks._handlers
+	}
+
+	static async run(stage, ctx = {}) {
+		const fn = Hooks._resolve()[stage]
+		if (typeof fn !== 'function') return
+
+		try {
+			await fn(ctx)
+		} catch (err) {
+			logger.error(`Hook "${stage}" failed`, err)
+			throw err
+		}
+	}
+
+	static before(ctx) {
+		return Hooks.run('before', ctx)
+	}
+
+	static after(ctx) {
+		return Hooks.run('after', ctx)
+	}
+
+	static shutdown(ctx) {
+		return Hooks.run('shutdown', ctx)
+	}
+}
+
+module.exports = Hooks

package/template/core/jwt.core.js

@@ -0,0 +1,81 @@
+'use strict'
+
+const jwt = require('jsonwebtoken')
+
+const config = require('@config/index')
+
+// Algorithm is pinned to a single symmetric scheme. Pinning on both sign and
+// verify defeats algorithm-confusion attacks (e.g. a forged token using "none"
+// or an RS/HS swap) — verification will reject anything not signed with HS256.
+const ALGORITHM = 'HS256'
+
+class Jwt {
+	static _assertSecret(secret, label) {
+		if (!secret) throw new Error(`${label} is not configured`)
+	}
+
+	static sign(payload, options = {}) {
+		Jwt._assertSecret(config.jwt.secret, 'JWT_SECRET')
+		return jwt.sign(payload, config.jwt.secret, { expiresIn: config.jwt.expiresIn, algorithm: ALGORITHM, ...options })
+	}
+
+	static verify(token, options = {}) {
+		Jwt._assertSecret(config.jwt.secret, 'JWT_SECRET')
+		return jwt.verify(token, config.jwt.secret, { algorithms: [ALGORITHM], ...options })
+	}
+
+	static signRefresh(payload, options = {}) {
+		Jwt._assertSecret(config.jwt.refreshSecret, 'JWT_REFRESH_SECRET')
+		return jwt.sign(payload, config.jwt.refreshSecret, { expiresIn: config.jwt.refreshExpiresIn, algorithm: ALGORITHM, ...options })
+	}
+
+	static verifyRefresh(token, options = {}) {
+		Jwt._assertSecret(config.jwt.refreshSecret, 'JWT_REFRESH_SECRET')
+		return jwt.verify(token, config.jwt.refreshSecret, { algorithms: [ALGORITHM], ...options })
+	}
+
+	// Issue an access + refresh pair for a payload (typically { sub, ... }).
+	static issue(payload) {
+		return {
+			accessToken: Jwt.sign(payload),
+			refreshToken: Jwt.signRefresh(payload),
+			tokenType: 'Bearer',
+			expiresIn: config.jwt.expiresIn,
+		}
+	}
+
+	// Non-throwing verify. Returns { valid, payload, error } for control flow that
+	// prefers a result object over try/catch.
+	static tryVerify(token) {
+		try {
+			return { valid: true, payload: Jwt.verify(token), error: null }
+		} catch (error) {
+			return { valid: false, payload: null, error }
+		}
+	}
+
+	static decode(token, options = {}) {
+		return jwt.decode(token, options)
+	}
+
+	// Expiry as a Date, or null when the token has no `exp` claim.
+	static expiresAt(token) {
+		const decoded = jwt.decode(token)
+		if (!decoded || typeof decoded.exp !== 'number') return null
+		return new Date(decoded.exp * 1000)
+	}
+
+	static isExpired(token) {
+		const at = Jwt.expiresAt(token)
+		return at ? at.getTime() <= Date.now() : true
+	}
+
+	// Extract the bearer token from an Authorization header value, or null.
+	static fromHeader(authHeader) {
+		if (!authHeader || typeof authHeader !== 'string') return null
+		const match = authHeader.match(/^Bearer\s+(.+)$/i)
+		return match ? match[1].trim() : null
+	}
+}
+
+module.exports = Jwt

package/template/core/logger.core.js

@@ -0,0 +1,100 @@
+'use strict'
+const path = require('path')
+const winston = require('winston')
+const config = require('@config/index')
+require('winston-daily-rotate-file')
+const { createLogger, format, transports } = winston
+const { combine, timestamp, printf, errors } = format
+
+class Logger {
+	static isProd = config.app.env === 'production'
+	static logDir = path.resolve(process.cwd(), config.logger.file)
+	static appName = `[${config.app.name.toUpperCase()}]`
+	static _consoleFormat = null
+	static _fileFormat = null
+
+	static outputColors = {
+		error: '\x1b[31m\x1b[1m',
+		warn: '\x1b[33m\x1b[1m',
+		info: '\x1b[36m\x1b[1m',
+		debug: '\x1b[35m\x1b[1m',
+		http: '\x1b[32m\x1b[1m',
+		verbose: '\x1b[34m\x1b[1m',
+		silly: '\x1b[90m\x1b[1m',
+		reset: '\x1b[0m',
+	}
+
+	static colorLevel(level) {
+		const c = Logger.outputColors[level] || '\x1b[37m\x1b[1m'
+		return `${c}[${level.toUpperCase()}]${Logger.outputColors.reset}`
+	}
+
+	static buildMessage({ message, stack }) {
+		if (stack) return stack
+		if (message instanceof Error) return message.stack || message.message
+		return String(message)
+	}
+
+	static get consoleFormat() {
+		if (!Logger._consoleFormat) {
+			Logger._consoleFormat = combine(
+				errors({ stack: true }),
+				timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+				printf((info) => {
+					const msg = Logger.buildMessage(info)
+					return `${Logger.appName} ${Logger.colorLevel(info.level)} [${info.timestamp}] ${msg}`
+				}),
+			)
+		}
+		return Logger._consoleFormat
+	}
+
+	static get fileFormat() {
+		if (!Logger._fileFormat) {
+			Logger._fileFormat = combine(
+				errors({ stack: true }),
+				timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
+				printf((info) => {
+					const msg = Logger.buildMessage(info)
+					return `${Logger.appName} [${info.level.toUpperCase()}] [${info.timestamp}] ${msg}`
+				}),
+			)
+		}
+		return Logger._fileFormat
+	}
+
+	static get productionFilter() {
+		return format((info) => {
+			if (['error', 'warn', 'debug'].includes(info.level)) return false
+			return info
+		})
+	}
+
+	static makeRotateTransport(level, name) {
+		return new transports.DailyRotateFile({
+			level,
+			dirname: Logger.logDir,
+			filename: `${name}-%DATE%.log`,
+			datePattern: 'YYYY-MM-DD',
+			zippedArchive: true,
+			maxSize: config.logger.maxSize,
+			maxFiles: config.logger.maxFiles,
+			format: Logger.fileFormat,
+		})
+	}
+
+	static create() {
+		const consoleTransport = new transports.Console({
+			level: config.logger.level,
+			format: Logger.isProd ? combine(Logger.productionFilter(), Logger.consoleFormat) : Logger.consoleFormat,
+		})
+
+		return createLogger({
+			level: config.logger.level,
+			exitOnError: false,
+			transports: [consoleTransport, Logger.makeRotateTransport('error', 'error'), Logger.makeRotateTransport(config.logger.level, 'combined')],
+		})
+	}
+}
+
+module.exports = Logger.create()

package/template/core/mailer.core.js

@@ -0,0 +1,65 @@
+'use strict'
+
+const nodemailer = require('nodemailer')
+
+const config = require('@config/index')
+const logger = require('@core/logger.core')
+
+class Mailer {
+	static _transporter = null
+
+	// Lazily create and cache the SMTP transport. Auth is omitted when no username
+	// is configured (e.g. local relays / Mailtrap without credentials).
+	static _transport() {
+		if (Mailer._transporter) return Mailer._transporter
+
+		const mail = config.mail
+		Mailer._transporter = nodemailer.createTransport({
+			host: mail.host,
+			port: mail.port,
+			secure: mail.secure,
+			auth: mail.username ? { user: mail.username, pass: mail.password } : undefined,
+		})
+
+		return Mailer._transporter
+	}
+
+	static _defaultFrom() {
+		const { fromName, fromAddress } = config.mail
+		if (!fromAddress) return undefined
+		return fromName ? `"${fromName}" <${fromAddress}>` : fromAddress
+	}
+
+	// Send a message. When mail is disabled the call is a safe no-op so application
+	// code never has to branch on MAIL_ENABLED.
+	static async send(message) {
+		if (!config.mail.enabled) {
+			logger.warn('Mail is disabled (MAIL_ENABLED=false); skipping send')
+			return { skipped: true }
+		}
+
+		const payload = { ...message, from: message.from || Mailer._defaultFrom() }
+		const info = await Mailer._transport().sendMail(payload)
+		logger.debug(`Mail sent: ${info.messageId}`)
+		return info
+	}
+
+	// Verify the SMTP connection/credentials. Returns false (and logs) on failure
+	// rather than throwing, so it is safe to call during boot diagnostics.
+	static async verify() {
+		if (!config.mail.enabled) {
+			logger.warn('Mail is disabled (MAIL_ENABLED=false)')
+			return false
+		}
+
+		try {
+			await Mailer._transport().verify()
+			return true
+		} catch (err) {
+			logger.error('Mail transport verification failed', err)
+			return false
+		}
+	}
+}
+
+module.exports = Mailer

package/template/core/queue.core.js

@@ -0,0 +1,226 @@
+'use strict'
+
+const crypto = require('crypto')
+
+const config = require('@config/index')
+const logger = require('@core/logger.core')
+const Register = require('@core/register.core')
+
+const REGISTER_FILE = Register.path('app', 'queue', 'register.queue.js')
+const TABLE = 'queue_jobs'
+
+class Queue {
+	static queues = new Map()
+	static draining = false
+	static _db = null
+
+	static define(name, handler, options = {}) {
+		Queue.queues.set(name, {
+			name,
+			handler,
+			concurrency: options.concurrency ?? config.queue.concurrency,
+			maxRetries: options.maxRetries ?? config.queue.maxRetries,
+			retryDelay: options.retryDelay ?? config.queue.retryDelay,
+			pending: [],
+			active: 0,
+		})
+		return Queue
+	}
+
+	static dispatch(name, payload = {}, options = {}) {
+		const queue = Queue.queues.get(name)
+		if (!queue) throw new Error(`Queue "${name}" is not defined`)
+
+		const job = {
+			id: crypto.randomUUID(),
+			queue: name,
+			payload,
+			attempts: 0,
+			maxRetries: options.maxRetries ?? queue.maxRetries,
+			createdAt: Date.now(),
+		}
+
+		const delay = options.delay || 0
+		if (Queue._db) {
+			Queue._insertJob(job, delay).catch((err) => logger.warn(`Queue: failed to persist job ${job.id}: ${err.message}`))
+		}
+
+		if (delay > 0) {
+			setTimeout(() => Queue._enqueue(queue, job), delay).unref?.()
+		} else {
+			Queue._enqueue(queue, job)
+		}
+
+		return job.id
+	}
+
+	static _enqueue(queue, job) {
+		queue.pending.push(job)
+		Queue._drain(queue)
+	}
+
+	static _drain(queue) {
+		if (Queue.draining) return
+		while (queue.active < queue.concurrency && queue.pending.length > 0) {
+			const job = queue.pending.shift()
+			Queue._process(queue, job)
+		}
+	}
+
+	static async _process(queue, job) {
+		queue.active++
+		job.attempts++
+		if (Queue._db) await Queue._markProcessing(job.id, job.attempts).catch(() => {})
+
+		try {
+			await queue.handler(job.payload, job)
+			if (Queue._db) await Queue._markCompleted(job.id).catch(() => {})
+			logger.debug(`Queue "${queue.name}" processed job ${job.id} (attempt ${job.attempts})`)
+		} catch (err) {
+			if (job.attempts <= job.maxRetries) {
+				const backoff = queue.retryDelay * Math.pow(2, job.attempts - 1)
+				logger.warn(`Queue "${queue.name}" job ${job.id} failed (attempt ${job.attempts}), retrying in ${backoff}ms: ${err.message}`)
+				if (Queue._db) await Queue._markPending(job.id, job.attempts).catch(() => {})
+				setTimeout(() => Queue._enqueue(queue, job), backoff).unref?.()
+			} else {
+				if (Queue._db) await Queue._markFailed(job.id, err.message).catch(() => {})
+				logger.error(`Queue "${queue.name}" job ${job.id} permanently failed after ${job.attempts} attempt(s)`, err)
+			}
+		} finally {
+			queue.active--
+			Queue._drain(queue)
+		}
+	}
+
+	static async start() {
+		if (!config.queue.enabled) {
+			logger.info('Queue is disabled (QUEUE_ENABLED=false)')
+			return
+		}
+
+		await Register.invoke(REGISTER_FILE, [Queue], { label: 'app/queue/register.queue.js' })
+
+		if (config.queue.persist && config.db.enabled) {
+			try {
+				const Database = require('@core/database.core')
+				if (Database.sequelize) {
+					Queue._db = Database.sequelize
+					await Queue._ensureTable()
+					await Queue._loadPending()
+				}
+			} catch (err) {
+				logger.warn(`Queue: DB persistence unavailable, running in-memory only: ${err.message}`)
+			}
+		}
+
+		logger.info(`Queue started ${Queue.queues.size} queue(s)${Queue.queues.size ? `: ${[...Queue.queues.keys()].join(', ')}` : ''}`)
+	}
+
+	static async stop(timeoutMs = 10000) {
+		Queue.draining = true
+		const deadline = Date.now() + timeoutMs
+		while (Date.now() < deadline) {
+			const busy = [...Queue.queues.values()].some((q) => q.active > 0)
+			if (!busy) break
+			await new Promise((resolve) => setTimeout(resolve, 100))
+		}
+		logger.info('Queue stopped')
+	}
+
+	static stats() {
+		const out = {}
+		for (const [name, queue] of Queue.queues) {
+			out[name] = { pending: queue.pending.length, active: queue.active }
+		}
+		return out
+	}
+
+	// ── DB helpers ────────────────────────────────────────────────────────────
+
+	static async _ensureTable() {
+		await Queue._db.query(`
+			CREATE TABLE IF NOT EXISTS \`${TABLE}\` (
+				\`id\`           VARCHAR(36)                                              NOT NULL,
+				\`queue\`        VARCHAR(100)                                             NOT NULL,
+				\`payload\`      JSON                                                     NOT NULL,
+				\`status\`       ENUM('pending','processing','completed','failed')        NOT NULL DEFAULT 'pending',
+				\`attempts\`     INT                                                      NOT NULL DEFAULT 0,
+				\`max_retries\`  INT                                                      NOT NULL DEFAULT 3,
+				\`error\`        TEXT                                                     NULL,
+				\`available_at\` DATETIME                                                 NOT NULL,
+				\`processed_at\` DATETIME                                                 NULL,
+				\`created_at\`   DATETIME                                                 NOT NULL,
+				\`updated_at\`   DATETIME                                                 NOT NULL,
+				PRIMARY KEY (\`id\`),
+				INDEX idx_queue_status (\`queue\`, \`status\`, \`available_at\`)
+			) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+		`)
+	}
+
+	static async _insertJob(job, delay) {
+		const now = new Date()
+		await Queue._db.query(
+			`INSERT INTO \`${TABLE}\` (id, \`queue\`, payload, status, attempts, max_retries, available_at, created_at, updated_at)
+			 VALUES (:id, :queue, :payload, 'pending', 0, :maxRetries, :availableAt, :now, :now)`,
+			{
+				replacements: {
+					id: job.id,
+					queue: job.queue,
+					payload: JSON.stringify(job.payload),
+					maxRetries: job.maxRetries,
+					availableAt: new Date(Date.now() + delay),
+					now,
+				},
+			},
+		)
+	}
+
+	static async _markProcessing(id, attempts) {
+		await Queue._db.query(`UPDATE \`${TABLE}\` SET status = 'processing', attempts = :attempts, updated_at = :now WHERE id = :id`, { replacements: { attempts, now: new Date(), id } })
+	}
+
+	static async _markCompleted(id) {
+		const now = new Date()
+		await Queue._db.query(`UPDATE \`${TABLE}\` SET status = 'completed', processed_at = :now, updated_at = :now WHERE id = :id`, { replacements: { now, id } })
+	}
+
+	static async _markFailed(id, errorMsg) {
+		const now = new Date()
+		await Queue._db.query(`UPDATE \`${TABLE}\` SET status = 'failed', error = :error, processed_at = :now, updated_at = :now WHERE id = :id`, { replacements: { error: errorMsg, now, id } })
+	}
+
+	static async _markPending(id, attempts) {
+		await Queue._db.query(`UPDATE \`${TABLE}\` SET status = 'pending', attempts = :attempts, updated_at = :now WHERE id = :id`, { replacements: { attempts, now: new Date(), id } })
+	}
+
+	static async _loadPending() {
+		const [rows] = await Queue._db.query(
+			`SELECT id, \`queue\`, payload, attempts, max_retries AS maxRetries
+			 FROM \`${TABLE}\`
+			 WHERE status IN ('pending', 'processing') AND available_at <= :now`,
+			{ replacements: { now: new Date() } },
+		)
+
+		let loaded = 0
+		for (const row of rows) {
+			const queue = Queue.queues.get(row.queue)
+			if (!queue) {
+				logger.warn(`Queue "${row.queue}" not registered; skipping orphaned job ${row.id}`)
+				continue
+			}
+			Queue._enqueue(queue, {
+				id: row.id,
+				queue: row.queue,
+				payload: typeof row.payload === 'string' ? JSON.parse(row.payload) : row.payload,
+				attempts: row.attempts,
+				maxRetries: row.maxRetries,
+				createdAt: Date.now(),
+			})
+			loaded++
+		}
+
+		if (loaded > 0) logger.info(`Queue: recovered ${loaded} pending job(s) from database`)
+	}
+}
+
+module.exports = Queue