@yunsoft/yuncms-core 0.1.2 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunsoft/yuncms-core",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Core services, schema, authentication, permissions and storage primitives for YunCMS.",
   "license": "MIT",
   "type": "module",

package/src/bootstrap.js

@@ -7,6 +7,11 @@ import { authActionTokensMigration } from './migrations/0004-auth-action-tokens.
 import { defaultPublicRoleMigration } from './migrations/0005-default-public-role.js';
 import { studioSettingsMigration } from './migrations/0006-studio-settings.js';
 import { systemPermissionResourcesMigration } from './migrations/0007-system-permission-resources.js';
+import { studioLogoFileMigration } from './migrations/0008-studio-logo-file.js';
+import { schemaDisplayNamesMigration } from './migrations/0009-schema-display-names.js';
+import { studioFaviconFileMigration } from './migrations/0010-studio-favicon-file.js';
+import { rolePermissionActionsMigration } from './migrations/0011-role-permission-actions.js';
+import { filesReadFiltersMigration } from './migrations/0012-files-read-filters.js';
 import { readSchemaVersion } from './schema-version.js';
 import { ensurePublicRole } from './setup.js';
 
@@ -18,6 +23,11 @@ export const CORE_MIGRATIONS = Object.freeze([
   defaultPublicRoleMigration,
   studioSettingsMigration,
   systemPermissionResourcesMigration,
+  studioLogoFileMigration,
+  schemaDisplayNamesMigration,
+  studioFaviconFileMigration,
+  rolePermissionActionsMigration,
+  filesReadFiltersMigration,
 ]);
 
 export const REQUIRED_CORE_MIGRATION_IDS = Object.freeze(

package/src/cache.js

@@ -0,0 +1,85 @@
+function cacheError(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_CACHE_CONFIG';
+  return error;
+}
+
+export function isCacheStore(store) {
+  return Boolean(
+    store
+    && typeof store.get === 'function'
+    && typeof store.set === 'function'
+    && typeof store.delete === 'function'
+    && typeof store.clear === 'function',
+  );
+}
+
+export class MemoryCacheStore {
+  constructor({
+    ttlMs = 30_000,
+    maxEntries = 5_000,
+    now = () => Date.now(),
+  } = {}) {
+    if (!Number.isInteger(ttlMs) || ttlMs < 1) throw cacheError('Cache ttlMs must be a positive integer');
+    if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+      throw cacheError('Cache maxEntries must be a positive integer');
+    }
+    if (typeof now !== 'function') throw cacheError('Cache now must be a function');
+
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+    this.now = now;
+    this.entries = new Map();
+  }
+
+  #deleteExpired(timestamp) {
+    for (const [key, entry] of this.entries) {
+      if (entry.expiresAt <= timestamp) this.entries.delete(key);
+    }
+  }
+
+  #ensureCapacity(timestamp, incomingKey) {
+    this.#deleteExpired(timestamp);
+    if (this.entries.has(incomingKey)) return;
+    while (this.entries.size >= this.maxEntries) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey === undefined) break;
+      this.entries.delete(oldestKey);
+    }
+  }
+
+  async get(key) {
+    const entry = this.entries.get(String(key));
+    if (!entry) return undefined;
+    if (entry.expiresAt <= this.now()) {
+      this.entries.delete(String(key));
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  async set(key, value, { ttlMs = this.ttlMs } = {}) {
+    if (!Number.isInteger(ttlMs) || ttlMs < 1) throw cacheError('Cache entry ttlMs must be a positive integer');
+    const normalizedKey = String(key);
+    const timestamp = this.now();
+    this.#ensureCapacity(timestamp, normalizedKey);
+    this.entries.delete(normalizedKey);
+    this.entries.set(normalizedKey, {
+      value,
+      expiresAt: timestamp + ttlMs,
+    });
+    return value;
+  }
+
+  async delete(key) {
+    return this.entries.delete(String(key));
+  }
+
+  async clear() {
+    this.entries.clear();
+  }
+
+  get size() {
+    return this.entries.size;
+  }
+}

package/src/config.js

@@ -24,6 +24,14 @@ function readString(value, fallback = '') {
   return value === undefined ? fallback : String(value);
 }
 
+function readCacheStore(value) {
+  const store = readString(value, 'memory').trim().toLowerCase();
+  if (store !== 'memory') {
+    throw new Error(`CACHE_STORE must be memory until a shared-store adapter is configured, received: ${store}`);
+  }
+  return store;
+}
+
 export function loadEnvFileIfPresent(path = '.env') {
   try {
     loadEnvFile(path);
@@ -44,10 +52,52 @@ export function loadConfig(env = process.env) {
       port: serverPort,
       studioOrigin,
       trustProxyHops: readInteger(env.TRUST_PROXY_HOPS, 0, 'TRUST_PROXY_HOPS', { min: 0, max: 10 }),
+      rateLimit: {
+        enabled: readBoolean(env.API_RATE_LIMIT_ENABLED, true),
+        windowMs: readInteger(env.API_RATE_LIMIT_WINDOW_MS, 60_000, 'API_RATE_LIMIT_WINDOW_MS', {
+          min: 1000,
+          max: 24 * 60 * 60 * 1000,
+        }),
+        max: readInteger(env.API_RATE_LIMIT_MAX, 300, 'API_RATE_LIMIT_MAX', {
+          min: 1,
+          max: 1_000_000,
+        }),
+        maxBuckets: readInteger(env.API_RATE_LIMIT_MAX_BUCKETS, 10_000, 'API_RATE_LIMIT_MAX_BUCKETS', {
+          min: 1,
+          max: 1_000_000,
+        }),
+      },
+      pressure: {
+        enabled: readBoolean(env.PRESSURE_LIMIT_ENABLED, true),
+        maxConcurrent: readInteger(env.PRESSURE_MAX_CONCURRENT, 250, 'PRESSURE_MAX_CONCURRENT', {
+          min: 1,
+          max: 100_000,
+        }),
+        maxHeapPercent: readInteger(env.PRESSURE_MAX_HEAP_PERCENT, 95, 'PRESSURE_MAX_HEAP_PERCENT', {
+          min: 1,
+          max: 100,
+        }),
+        retryAfterSeconds: readInteger(env.PRESSURE_RETRY_AFTER_SECONDS, 1, 'PRESSURE_RETRY_AFTER_SECONDS', {
+          min: 1,
+          max: 3600,
+        }),
+      },
     },
     logging: {
       level: readString(env.LOG_LEVEL, 'info'),
     },
+    cache: {
+      enabled: readBoolean(env.CACHE_ENABLED, true),
+      store: readCacheStore(env.CACHE_STORE),
+      ttlMs: readInteger(env.CACHE_TTL_MS, 30_000, 'CACHE_TTL_MS', {
+        min: 1,
+        max: 24 * 60 * 60 * 1000,
+      }),
+      maxEntries: readInteger(env.CACHE_MAX_ENTRIES, 5_000, 'CACHE_MAX_ENTRIES', {
+        min: 1,
+        max: 1_000_000,
+      }),
+    },
     database: {
       host: readString(env.DB_HOST, '127.0.0.1'),
       port: readInteger(env.DB_PORT, 3306, 'DB_PORT', { min: 1, max: 65535 }),

package/src/context.js

@@ -1,4 +1,5 @@
 import { requireAccountability } from './accountability.js';
+import { isCacheStore } from './cache.js';
 
 export function createRequestContext({
   accountability,
@@ -9,14 +10,16 @@ export function createRequestContext({
   env = {},
   emitter = null,
   storage = null,
-  permissionCache = new Map(),
+  permissionCache = null,
   requestId = null,
 } = {}) {
   requireAccountability(accountability);
 
   if (!services) throw new Error('Service registry is required');
   if (!database) throw new Error('Database handle is required');
-  if (!(permissionCache instanceof Map)) throw new Error('Permission cache must be a Map');
+  if (permissionCache !== null && !isCacheStore(permissionCache)) {
+    throw new Error('Permission cache must implement the cache-store contract');
+  }
 
   return Object.freeze({
     accountability,

package/src/index.js

@@ -1,9 +1,17 @@
 export { DEFAULT_SERVER_PORT, loadConfig, loadEnvFileIfPresent } from './config.js';
+export { isCacheStore, MemoryCacheStore } from './cache.js';
 export { createDatabasePool, pingDatabase, closeDatabasePool } from './database.js';
 export { withTransaction, withConnectionTransaction } from './transaction.js';
 export { assertIdentifier, quoteIdentifier } from './identifier.js';
+export { normalizeDisplayName, normalizeSchemaKey, resolveSchemaName } from './schema-key.js';
 export { YunCmsDatabaseError, normalizeDatabaseError, isRetryableDatabaseError } from './errors.js';
 export { withDatabaseRetry } from './retry.js';
+export {
+  MAINTENANCE_BYPASS_ENV,
+  maintenanceLockPath,
+  hashMaintenanceBypassToken,
+  assertMaintenanceStartupAllowed,
+} from './maintenance-state.js';
 export {
   createAccountability,
   createPublicAccountability,
@@ -41,6 +49,7 @@ export { AuditService, redactAuditValue } from './services/audit-service.js';
 export { ItemsService } from './services/items-service.js';
 export { CollectionsService } from './services/collections-service.js';
 export { FieldsService } from './services/fields-service.js';
+export { SystemCollectionFieldsService } from './services/system-collection-fields-service.js';
 export { RelationsService } from './services/relations-service.js';
 export { UsersService } from './services/users-service.js';
 export { RolesService } from './services/roles-service.js';
@@ -61,6 +70,7 @@ export {
 } from './system-fields.js';
 export {
   assertActionOnlyPermissionPayload,
+  assertSystemPermissionPayload,
   assertSystemResourceAction,
   isPermissionManagedSystemResource,
   systemPermissionConfig,
@@ -75,6 +85,7 @@ export { withAdvisoryLock } from './advisory-lock.js';
 export {
   ensureMigrationJournal,
   readAppliedMigrations,
+  readMigrationAttempts,
   validateMigration,
   applyMigrations,
   assertMigrationsApplied,
@@ -85,4 +96,4 @@ export {
   REQUIRED_CORE_MIGRATION_IDS,
   bootstrapDatabase,
   assertDatabaseCompatible,
-} from './bootstrap.js';
+} from './bootstrap.js';

package/src/maintenance-state.js

@@ -0,0 +1,89 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const MAINTENANCE_BYPASS_ENV = 'YUNCMS_MAINTENANCE_BYPASS_TOKEN';
+
+function sha256(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
+export function canonicalProjectPath(cwd = process.cwd()) {
+  const absolute = resolve(cwd);
+  try {
+    return realpathSync.native ? realpathSync.native(absolute) : realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+export function maintenanceLockPath(cwd = process.cwd()) {
+  const projectKey = sha256(canonicalProjectPath(cwd)).slice(0, 32);
+  return join(tmpdir(), 'yuncms-update-locks', `${projectKey}.lock`);
+}
+
+export function hashMaintenanceBypassToken(token) {
+  if (typeof token !== 'string' || token.length < 32) {
+    const error = new Error('Maintenance bypass token must contain at least 32 characters');
+    error.code = 'MAINTENANCE_BYPASS_TOKEN_INVALID';
+    throw error;
+  }
+  return sha256(token);
+}
+
+function hashesEqual(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string') return false;
+  if (!/^[0-9a-f]{64}$/i.test(left) || !/^[0-9a-f]{64}$/i.test(right)) return false;
+  const leftBuffer = Buffer.from(left, 'hex');
+  const rightBuffer = Buffer.from(right, 'hex');
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+async function readMaintenanceState(path, readFileFn) {
+  let text;
+  try {
+    text = await readFileFn(path, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+
+  try {
+    const state = JSON.parse(text);
+    if (!state || typeof state !== 'object' || Array.isArray(state)) throw new Error('invalid state');
+    return state;
+  } catch (cause) {
+    const error = new Error(`YunCMS maintenance lock is unreadable or invalid: ${path}`);
+    error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+    error.lockPath = path;
+    error.cause = cause;
+    throw error;
+  }
+}
+
+export async function assertMaintenanceStartupAllowed({
+  cwd = process.cwd(),
+  env = process.env,
+  readFileFn = readFile,
+} = {}) {
+  const path = maintenanceLockPath(cwd);
+  const state = await readMaintenanceState(path, readFileFn);
+  if (!state) return true;
+
+  const suppliedToken = env?.[MAINTENANCE_BYPASS_ENV];
+  if (typeof suppliedToken === 'string' && suppliedToken.length >= 32) {
+    const suppliedHash = sha256(suppliedToken);
+    if (hashesEqual(suppliedHash, state.bypassTokenHash)) return true;
+  }
+
+  const error = new Error(
+    `YunCMS maintenance is active for this project. Do not start the application until the maintenance operation finishes: ${path}`,
+  );
+  error.code = 'YUNCMS_MAINTENANCE_ACTIVE';
+  error.lockPath = path;
+  error.startedAt = typeof state.startedAt === 'string' ? state.startedAt : null;
+  error.pid = Number.isInteger(state.pid) ? state.pid : null;
+  throw error;
+}

package/src/migrations/0008-studio-logo-file.js

@@ -0,0 +1,10 @@
+export const studioLogoFileMigration = {
+  id: '0008-studio-logo-file',
+  statements: [
+    `ALTER TABLE yuncms_studio_settings
+       ADD COLUMN logo_file CHAR(36) NULL AFTER logo_url,
+       ADD KEY idx_yuncms_studio_settings_logo_file (logo_file),
+       ADD CONSTRAINT fk_yuncms_studio_settings_logo_file
+         FOREIGN KEY (logo_file) REFERENCES yuncms_files (id) ON DELETE SET NULL`,
+  ],
+};

package/src/migrations/0009-schema-display-names.js

@@ -0,0 +1,19 @@
+export const schemaDisplayNamesMigration = {
+  id: '0009-schema-display-names',
+  statements: [
+    `ALTER TABLE yuncms_collections
+      ADD COLUMN name VARCHAR(255) NULL AFTER collection`,
+    `UPDATE yuncms_collections
+      SET name = collection
+      WHERE name IS NULL OR TRIM(name) = ''`,
+    `ALTER TABLE yuncms_collections
+      MODIFY COLUMN name VARCHAR(255) NOT NULL`,
+    `ALTER TABLE yuncms_fields
+      ADD COLUMN name VARCHAR(255) NULL AFTER field`,
+    `UPDATE yuncms_fields
+      SET name = field
+      WHERE name IS NULL OR TRIM(name) = ''`,
+    `ALTER TABLE yuncms_fields
+      MODIFY COLUMN name VARCHAR(255) NOT NULL`,
+  ],
+};

package/src/migrations/0010-studio-favicon-file.js

@@ -0,0 +1,12 @@
+export const studioFaviconFileMigration = {
+  id: '0010-studio-favicon-file',
+  statements: [
+    `ALTER TABLE yuncms_studio_settings
+      ADD COLUMN favicon_file CHAR(36) NULL AFTER logo_file`,
+    `ALTER TABLE yuncms_studio_settings
+      ADD KEY idx_yuncms_studio_settings_favicon_file (favicon_file)`,
+    `ALTER TABLE yuncms_studio_settings
+      ADD CONSTRAINT fk_yuncms_studio_settings_favicon_file
+      FOREIGN KEY (favicon_file) REFERENCES yuncms_files (id) ON DELETE SET NULL`,
+  ],
+};

package/src/migrations/0011-role-permission-actions.js

@@ -0,0 +1,15 @@
+export const rolePermissionActionsMigration = {
+  id: '0011-role-permission-actions',
+  statements: [
+    `UPDATE yuncms_collections
+     SET metadata = JSON_SET(
+       COALESCE(metadata, JSON_OBJECT()),
+       '$.permissionManaged', TRUE,
+       '$.permissionMode', 'action-only',
+       '$.resource', 'roles',
+       '$.allowedActions', JSON_ARRAY('read', 'create', 'update', 'delete')
+     )
+     WHERE collection = 'yuncms_roles' AND \`system\` = 1`,
+    `UPDATE yuncms_schema_state SET version = version + 1 WHERE id = 1`,
+  ],
+};

package/src/migrations/0012-files-read-filters.js

@@ -0,0 +1,14 @@
+export const filesReadFiltersMigration = {
+  id: '0012-files-read-filters',
+  statements: [
+    `UPDATE yuncms_collections
+     SET metadata = JSON_SET(
+       COALESCE(metadata, JSON_OBJECT()),
+       '$.permissionMode',
+       'filter-read'
+     )
+     WHERE collection = 'yuncms_files'
+       AND \`system\` = 1`,
+    `UPDATE yuncms_schema_state SET version = version + 1 WHERE id = 1`,
+  ],
+};

package/src/migrations.js

@@ -1,4 +1,10 @@
 const JOURNAL_TABLE = 'yuncms_schema_migrations';
+const ATTEMPT_TABLE = 'yuncms_schema_migration_attempts';
+
+function truncateErrorMessage(value, maxLength = 1000) {
+  const message = String(value ?? 'Migration failed');
+  return message.length > maxLength ? message.slice(0, maxLength) : message;
+}
 
 export async function ensureMigrationJournal(database) {
   await database.query(`
@@ -7,6 +13,20 @@ export async function ensureMigrationJournal(database) {
       applied_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
   `);
+
+  await database.query(`
+    CREATE TABLE IF NOT EXISTS ${ATTEMPT_TABLE} (
+      migration_id VARCHAR(191) NOT NULL PRIMARY KEY,
+      status VARCHAR(16) NOT NULL,
+      statement_index INT UNSIGNED NOT NULL DEFAULT 0,
+      started_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+      finished_at DATETIME(3) NULL,
+      error_code VARCHAR(128) NULL,
+      error_message VARCHAR(1000) NULL,
+      CONSTRAINT chk_yuncms_schema_migration_attempt_status
+        CHECK (status IN ('applying', 'applied', 'failed'))
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+  `);
 }
 
 export async function readAppliedMigrations(database) {
@@ -14,6 +34,15 @@ export async function readAppliedMigrations(database) {
   return new Set(rows.map((row) => row.id));
 }
 
+export async function readMigrationAttempts(database) {
+  const [rows] = await database.query(
+    `SELECT migration_id, status, statement_index, started_at, finished_at, error_code, error_message
+     FROM ${ATTEMPT_TABLE}
+     ORDER BY started_at ASC, migration_id ASC`,
+  );
+  return rows;
+}
+
 export function validateMigration(migration) {
   if (!migration || typeof migration !== 'object') throw new Error('Migration must be an object');
   if (!migration.id || typeof migration.id !== 'string') throw new Error('Migration id is required');
@@ -26,23 +55,102 @@ export function validateMigration(migration) {
   return migration;
 }
 
+function migrationRecoveryError(attempts) {
+  const ids = attempts.map((attempt) => attempt.migration_id);
+  const error = new Error(
+    `Database contains an incomplete migration attempt and must be restored before retrying: ${ids.join(', ')}`,
+  );
+  error.code = 'DATABASE_MIGRATION_RECOVERY_REQUIRED';
+  error.migrationAttempts = attempts.map((attempt) => ({ ...attempt }));
+  return error;
+}
+
+async function assertNoIncompleteMigrationAttempts(database, applied, { allowMissingJournal = false } = {}) {
+  let attempts;
+  try {
+    attempts = await readMigrationAttempts(database);
+  } catch (error) {
+    if (allowMissingJournal && error?.code === 'ER_NO_SUCH_TABLE') return;
+    throw error;
+  }
+  const inconsistent = attempts.filter((attempt) => !applied.has(attempt.migration_id));
+  if (inconsistent.length > 0) throw migrationRecoveryError(inconsistent);
+}
+
+async function beginMigrationAttempt(database, migration) {
+  await database.query(
+    `INSERT INTO ${ATTEMPT_TABLE}
+       (migration_id, status, statement_index, started_at, finished_at, error_code, error_message)
+     VALUES (?, 'applying', 0, CURRENT_TIMESTAMP(3), NULL, NULL, NULL)`,
+    [migration.id],
+  );
+}
+
+async function advanceMigrationAttempt(database, migrationId, statementIndex) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET statement_index = ?
+     WHERE migration_id = ? AND status = 'applying'`,
+    [statementIndex, migrationId],
+  );
+}
+
+async function completeMigrationAttempt(database, migrationId) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET status = 'applied', finished_at = CURRENT_TIMESTAMP(3), error_code = NULL, error_message = NULL
+     WHERE migration_id = ?`,
+    [migrationId],
+  );
+}
+
+async function failMigrationAttempt(database, migrationId, error) {
+  await database.query(
+    `UPDATE ${ATTEMPT_TABLE}
+     SET status = 'failed', finished_at = CURRENT_TIMESTAMP(3), error_code = ?, error_message = ?
+     WHERE migration_id = ?`,
+    [
+      error?.code == null ? null : String(error.code).slice(0, 128),
+      truncateErrorMessage(error?.message),
+      migrationId,
+    ],
+  );
+}
+
 export async function applyMigrations(database, migrations) {
   if (!database) throw new Error('Database handle is required');
   if (!Array.isArray(migrations)) throw new Error('Migrations must be an array');
 
   await ensureMigrationJournal(database);
   const applied = await readAppliedMigrations(database);
+  await assertNoIncompleteMigrationAttempts(database, applied);
   const newlyApplied = [];
 
   for (const rawMigration of migrations) {
     const migration = validateMigration(rawMigration);
     if (applied.has(migration.id)) continue;
 
-    for (const statement of migration.statements) {
-      await database.query(statement);
+    await beginMigrationAttempt(database, migration);
+
+    try {
+      for (let index = 0; index < migration.statements.length; index += 1) {
+        await database.query(migration.statements[index]);
+        await advanceMigrationAttempt(database, migration.id, index + 1);
+      }
+
+      await database.query(`INSERT INTO ${JOURNAL_TABLE} (id) VALUES (?)`, [migration.id]);
+      await completeMigrationAttempt(database, migration.id);
+    } catch (error) {
+      try {
+        await failMigrationAttempt(database, migration.id, error);
+      } catch {
+        // The original migration error remains the source of truth. A stale 'applying'
+        // row still fails closed on the next bootstrap and requires restore/recovery.
+      }
+      error.migrationId ||= migration.id;
+      throw error;
     }
 
-    await database.query(`INSERT INTO ${JOURNAL_TABLE} (id) VALUES (?)`, [migration.id]);
     applied.add(migration.id);
     newlyApplied.push(migration.id);
   }
@@ -68,6 +176,8 @@ export async function assertMigrationsApplied(database, requiredMigrationIds) {
     throw error;
   }
 
+  await assertNoIncompleteMigrationAttempts(database, applied, { allowMissingJournal: true });
+
   const missing = requiredMigrationIds.filter((id) => !applied.has(id));
 
   if (missing.length > 0) {