@yunsoft/yuncms-core 0.1.0

package/src/services/fields-service.js

@@ -0,0 +1,471 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+import { withAdvisoryLock } from '../advisory-lock.js';
+import { compileFieldColumn } from '../field-types.js';
+import { assertIdentifier, quoteIdentifier } from '../identifier.js';
+import { SchemaMetadataRepository } from '../schema-metadata-repository.js';
+import { incrementSchemaVersion } from '../schema-version.js';
+import { withConnectionTransaction } from '../transaction.js';
+import { BaseService } from './base-service.js';
+import { assertSchemaManager } from './schema-access.js';
+
+const FIELD_METADATA_KEYS = new Set(['readonly', 'hidden', 'sort', 'interface', 'options']);
+const FIELD_PHYSICAL_KEYS = new Set(['required', 'defaultValue', 'removeDefault', 'indexed']);
+
+function assertFieldName(field) {
+  assertIdentifier(field, 'field name');
+  if (field.length > 64) throw new Error('Field name cannot exceed 64 characters');
+  return field;
+}
+
+function assertFieldMetadataPatch(patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    const error = new Error('Field metadata patch must be an object');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+  for (const key of Object.keys(patch)) {
+    if (!FIELD_METADATA_KEYS.has(key)) {
+      const error = new Error(`Field property cannot be updated through metadata-only V1 update: ${key}`);
+      error.code = 'UNSUPPORTED_SCHEMA_UPDATE';
+      throw error;
+    }
+  }
+  if (Object.keys(patch).length === 0) {
+    const error = new Error('Field metadata patch cannot be empty');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+}
+
+function assertPhysicalPatch(patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    const error = new Error('Physical field patch must be an object');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+  const keys = Object.keys(patch);
+  if (keys.length === 0) {
+    const error = new Error('Physical field patch cannot be empty');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+  for (const key of keys) {
+    if (!FIELD_PHYSICAL_KEYS.has(key)) {
+      const error = new Error(`Physical field property cannot be changed in V1: ${key}`);
+      error.code = 'UNSUPPORTED_SCHEMA_UPDATE';
+      throw error;
+    }
+  }
+  if (Object.hasOwn(patch, 'required') && typeof patch.required !== 'boolean') {
+    const error = new Error('required must be boolean');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+  if (Object.hasOwn(patch, 'indexed') && typeof patch.indexed !== 'boolean') {
+    const error = new Error('indexed must be boolean');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+  if (Object.hasOwn(patch, 'removeDefault') && patch.removeDefault !== true) {
+    const error = new Error('removeDefault must be true when provided');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+  if (Object.hasOwn(patch, 'defaultValue') && patch.removeDefault === true) {
+    const error = new Error('defaultValue and removeDefault cannot be used together');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+}
+
+function parseSchemaMetadata(value) {
+  if (value == null) return {};
+  if (typeof value === 'object') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return {};
+  }
+}
+
+function fieldInputFromMetadata(field, schemaMetadata) {
+  const input = {
+    type: field.type,
+    required: Boolean(field.required),
+  };
+  if (schemaMetadata.length !== undefined && field.type === 'string') input.length = schemaMetadata.length;
+  if (schemaMetadata.precision !== undefined && field.type === 'decimal') input.precision = schemaMetadata.precision;
+  if (schemaMetadata.scale !== undefined && field.type === 'decimal') input.scale = schemaMetadata.scale;
+  if (Object.hasOwn(schemaMetadata, 'defaultValue')) input.defaultValue = schemaMetadata.defaultValue;
+  return input;
+}
+
+function indexName(collection, field) {
+  const digest = createHash('sha256').update(`${collection}:${field}:index`).digest('hex').slice(0, 24);
+  return `yidx_${digest}`;
+}
+
+function temporaryDropName() {
+  return `_yuncms_drop_${randomUUID().replaceAll('-', '').slice(0, 24)}`;
+}
+
+export class FieldsService extends BaseService {
+  async readMany(collection) {
+    assertSchemaManager(this.accountability);
+    assertIdentifier(collection, 'collection name');
+    return new SchemaMetadataRepository(this.database).listFields(collection);
+  }
+
+  async readOne(collection, field) {
+    assertSchemaManager(this.accountability);
+    assertIdentifier(collection, 'collection name');
+    assertFieldName(field);
+    return new SchemaMetadataRepository(this.database).readField(collection, field);
+  }
+
+  async createOne(collection, input = {}) {
+    assertSchemaManager(this.accountability);
+    assertIdentifier(collection, 'collection name');
+    const field = assertFieldName(input.field);
+
+    if (field === 'id') {
+      const error = new Error('The id field is created with the collection and cannot be added again');
+      error.code = 'FIELD_EXISTS';
+      throw error;
+    }
+
+    const compiled = compileFieldColumn(input);
+
+    return withAdvisoryLock(this.database, 'yuncms:schema', async (connection) => {
+      const metadata = new SchemaMetadataRepository(connection);
+      const collectionMetadata = await metadata.readCollection(collection);
+      if (!collectionMetadata) {
+        const error = new Error(`Unknown collection: ${collection}`);
+        error.code = 'COLLECTION_NOT_FOUND';
+        throw error;
+      }
+      if (collectionMetadata.system) {
+        const error = new Error('System collection fields cannot be changed through the dynamic schema API');
+        error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+        throw error;
+      }
+
+      const existing = await metadata.readField(collection, field);
+      if (existing) {
+        const error = new Error(`Field already exists: ${collection}.${field}`);
+        error.code = 'FIELD_EXISTS';
+        throw error;
+      }
+
+      const tableName = quoteIdentifier(collection, 'collection name');
+      const fieldName = quoteIdentifier(field, 'field name');
+      let physicalFieldCreated = false;
+
+      try {
+        await connection.query(
+          `ALTER TABLE ${tableName} ADD COLUMN ${fieldName} ${compiled.sql}`,
+          compiled.params,
+        );
+        physicalFieldCreated = true;
+
+        return await withConnectionTransaction(connection, async () => {
+          const created = await metadata.createField({
+            collection,
+            field,
+            type: input.type,
+            required: input.required === true,
+            readonly: input.readonly === true,
+            hidden: input.hidden === true,
+            sort: input.sort ?? null,
+            interface: input.interface ?? null,
+            options: input.options ?? null,
+            schemaMetadata: compiled.schemaMetadata,
+          });
+
+          const schemaVersion = await incrementSchemaVersion(connection);
+          return { ...created, schemaVersion };
+        });
+      } catch (error) {
+        const cleanupErrors = [];
+
+        try {
+          await metadata.deleteField(collection, field);
+        } catch (cleanupError) {
+          cleanupErrors.push(cleanupError);
+        }
+
+        if (physicalFieldCreated) {
+          try {
+            await connection.query(`ALTER TABLE ${tableName} DROP COLUMN ${fieldName}`);
+          } catch (cleanupError) {
+            cleanupErrors.push(cleanupError);
+          }
+        }
+
+        if (cleanupErrors.length > 0) {
+          error.cleanupErrors = cleanupErrors;
+          error.code ||= 'SCHEMA_PARTIAL_FAILURE';
+        }
+        throw error;
+      }
+    });
+  }
+
+  async updateOne(collection, field, patch) {
+    assertSchemaManager(this.accountability);
+    assertIdentifier(collection, 'collection name');
+    assertFieldName(field);
+    assertFieldMetadataPatch(patch);
+
+    if (field === 'id') {
+      const error = new Error('Primary key field metadata is read-only in V1');
+      error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+      throw error;
+    }
+
+    return withAdvisoryLock(this.database, 'yuncms:schema', async (connection) => {
+      const metadata = new SchemaMetadataRepository(connection);
+      const [collectionMetadata, existing] = await Promise.all([
+        metadata.readCollection(collection),
+        metadata.readField(collection, field),
+      ]);
+
+      if (!collectionMetadata) {
+        const error = new Error(`Unknown collection: ${collection}`);
+        error.code = 'COLLECTION_NOT_FOUND';
+        throw error;
+      }
+      if (collectionMetadata.system) {
+        const error = new Error('System collection fields cannot be changed through the dynamic schema API');
+        error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+        throw error;
+      }
+      if (!existing) {
+        const error = new Error(`Unknown field: ${collection}.${field}`);
+        error.code = 'FIELD_NOT_FOUND';
+        throw error;
+      }
+
+      return withConnectionTransaction(connection, async () => {
+        const updated = await metadata.updateFieldMetadata(collection, field, patch);
+        const schemaVersion = await incrementSchemaVersion(connection);
+        return { ...updated, schemaVersion };
+      });
+    });
+  }
+
+  async updateSchema(collection, field, patch) {
+    assertSchemaManager(this.accountability);
+    assertIdentifier(collection, 'collection name');
+    assertFieldName(field);
+    assertPhysicalPatch(patch);
+    if (field === 'id') {
+      const error = new Error('Primary key field schema cannot be changed in V1');
+      error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+      throw error;
+    }
+
+    return withAdvisoryLock(this.database, 'yuncms:schema', async (connection) => {
+      const metadata = new SchemaMetadataRepository(connection);
+      const [collectionMetadata, existing, relations] = await Promise.all([
+        metadata.readCollection(collection),
+        metadata.readField(collection, field),
+        metadata.listRelations(),
+      ]);
+      if (!collectionMetadata) {
+        const error = new Error(`Unknown collection: ${collection}`);
+        error.code = 'COLLECTION_NOT_FOUND';
+        throw error;
+      }
+      if (collectionMetadata.system) {
+        const error = new Error('System collection fields cannot be changed through the dynamic schema API');
+        error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+        throw error;
+      }
+      if (!existing) {
+        const error = new Error(`Unknown field: ${collection}.${field}`);
+        error.code = 'FIELD_NOT_FOUND';
+        throw error;
+      }
+
+      const relation = relations.find((candidate) =>
+        candidate.many_collection === collection && candidate.many_field === field);
+      const nextRequired = Object.hasOwn(patch, 'required') ? patch.required : Boolean(existing.required);
+      if (relation?.on_delete === 'SET NULL' && nextRequired) {
+        const error = new Error('A SET NULL relation field cannot be changed to required');
+        error.code = 'INVALID_ON_DELETE';
+        throw error;
+      }
+
+      const currentMetadata = parseSchemaMetadata(existing.schema_metadata);
+      const currentInput = fieldInputFromMetadata(existing, currentMetadata);
+      const nextInput = { ...currentInput, required: nextRequired };
+      if (patch.removeDefault === true) delete nextInput.defaultValue;
+      else if (Object.hasOwn(patch, 'defaultValue')) nextInput.defaultValue = patch.defaultValue;
+
+      const currentCompiled = compileFieldColumn(currentInput);
+      const nextCompiled = compileFieldColumn(nextInput);
+      const currentIndexed = currentMetadata.indexed === true;
+      const nextIndexed = Object.hasOwn(patch, 'indexed') ? patch.indexed : currentIndexed;
+      const tableName = quoteIdentifier(collection, 'collection name');
+      const fieldName = quoteIdentifier(field, 'field name');
+      const physicalIndexName = indexName(collection, field);
+      const indexSql = quoteIdentifier(physicalIndexName, 'index name');
+
+      const restorePhysical = async () => {
+        const restoreErrors = [];
+        try {
+          await connection.query(
+            `ALTER TABLE ${tableName} MODIFY COLUMN ${fieldName} ${currentCompiled.sql}`,
+            currentCompiled.params,
+          );
+        } catch (error) {
+          restoreErrors.push(error);
+        }
+        if (currentIndexed !== nextIndexed) {
+          try {
+            if (currentIndexed) {
+              await connection.query(`ALTER TABLE ${tableName} ADD INDEX ${indexSql} (${fieldName})`);
+            } else {
+              await connection.query(`ALTER TABLE ${tableName} DROP INDEX ${indexSql}`);
+            }
+          } catch (error) {
+            restoreErrors.push(error);
+          }
+        }
+        return restoreErrors;
+      };
+
+      try {
+        await connection.query(
+          `ALTER TABLE ${tableName} MODIFY COLUMN ${fieldName} ${nextCompiled.sql}`,
+          nextCompiled.params,
+        );
+        if (currentIndexed !== nextIndexed) {
+          if (nextIndexed) {
+            await connection.query(`ALTER TABLE ${tableName} ADD INDEX ${indexSql} (${fieldName})`);
+          } else {
+            await connection.query(`ALTER TABLE ${tableName} DROP INDEX ${indexSql}`);
+          }
+        }
+
+        return await withConnectionTransaction(connection, async () => {
+          const updated = await metadata.updateFieldPhysicalMetadata(collection, field, {
+            required: nextRequired,
+            schemaMetadata: {
+              ...nextCompiled.schemaMetadata,
+              indexed: nextIndexed,
+            },
+          });
+          const schemaVersion = await incrementSchemaVersion(connection);
+          return { ...updated, schemaVersion };
+        });
+      } catch (error) {
+        const restoreErrors = await restorePhysical();
+        if (restoreErrors.length > 0) {
+          error.restoreErrors = restoreErrors;
+          error.code ||= 'SCHEMA_PARTIAL_FAILURE';
+        }
+        throw error;
+      }
+    });
+  }
+
+  async deleteOne(collection, field, { destructive = false } = {}) {
+    assertSchemaManager(this.accountability);
+    assertIdentifier(collection, 'collection name');
+    assertFieldName(field);
+    if (destructive !== true) {
+      const error = new Error('Field deletion requires destructive: true');
+      error.code = 'DESTRUCTIVE_OPERATION_REQUIRED';
+      throw error;
+    }
+    if (field === 'id') {
+      const error = new Error('Primary key fields cannot be deleted in V1');
+      error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+      throw error;
+    }
+
+    return withAdvisoryLock(this.database, 'yuncms:schema', async (connection) => {
+      const metadata = new SchemaMetadataRepository(connection);
+      const [collectionMetadata, existing, relations] = await Promise.all([
+        metadata.readCollection(collection),
+        metadata.readField(collection, field),
+        metadata.listRelations(),
+      ]);
+
+      if (!collectionMetadata) {
+        const error = new Error(`Unknown collection: ${collection}`);
+        error.code = 'COLLECTION_NOT_FOUND';
+        throw error;
+      }
+      if (collectionMetadata.system) {
+        const error = new Error('System collection fields cannot be deleted through the dynamic schema API');
+        error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+        throw error;
+      }
+      if (!existing) {
+        const error = new Error(`Unknown field: ${collection}.${field}`);
+        error.code = 'FIELD_NOT_FOUND';
+        throw error;
+      }
+
+      const blockingRelation = relations.find((relation) =>
+        (relation.many_collection === collection && relation.many_field === field) ||
+        (relation.one_collection === collection && relation.one_field === field) ||
+        (relation.junction_collection === collection && relation.junction_field === field));
+      if (blockingRelation) {
+        const error = new Error(`Field participates in a relation and cannot be deleted: ${collection}.${field}`);
+        error.code = 'FIELD_HAS_RELATION';
+        throw error;
+      }
+
+      const tableName = quoteIdentifier(collection, 'collection name');
+      const fieldName = quoteIdentifier(field, 'field name');
+      const tombstoneName = temporaryDropName();
+      const tombstoneField = quoteIdentifier(tombstoneName, 'temporary field name');
+
+      await connection.query(
+        `ALTER TABLE ${tableName} RENAME COLUMN ${fieldName} TO ${tombstoneField}`,
+      );
+
+      let result;
+      try {
+        result = await withConnectionTransaction(connection, async () => {
+          const deleted = await metadata.deleteField(collection, field);
+          if (deleted !== 1) {
+            const error = new Error(`Field metadata disappeared during delete: ${collection}.${field}`);
+            error.code = 'SCHEMA_METADATA_DRIFT';
+            throw error;
+          }
+          const schemaVersion = await incrementSchemaVersion(connection);
+          return { deleted: true, collection, field, schemaVersion };
+        });
+      } catch (error) {
+        try {
+          await connection.query(
+            `ALTER TABLE ${tableName} RENAME COLUMN ${tombstoneField} TO ${fieldName}`,
+          );
+        } catch (restoreError) {
+          error.restoreError = restoreError;
+          error.code ||= 'SCHEMA_PARTIAL_FAILURE';
+        }
+        throw error;
+      }
+
+      try {
+        await connection.query(`ALTER TABLE ${tableName} DROP COLUMN ${tombstoneField}`);
+      } catch (cleanupError) {
+        const error = new Error(`Field was logically deleted but physical cleanup failed: ${collection}.${field}`);
+        error.code = 'SCHEMA_PARTIAL_FAILURE';
+        error.cleanupError = cleanupError;
+        error.cleanupField = tombstoneName;
+        error.logicalDelete = result;
+        throw error;
+      }
+
+      return result;
+    });
+  }
+}

package/src/services/file-reconciliation-service.js

@@ -0,0 +1,127 @@
+import { BaseService } from './base-service.js';
+
+const DEFAULT_MIN_AGE_MS = 60 * 60 * 1000;
+const MIN_SAFE_AGE_MS = 60 * 1000;
+const MAX_INVENTORY_OBJECTS = 100_000;
+
+function serviceError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function assertFileManager(accountability) {
+  if (accountability?.admin === true || accountability?.system === true) return;
+  throw serviceError('FORBIDDEN', 'Storage reconciliation requires administrator accountability');
+}
+
+function normalizeAge(value) {
+  const age = value ?? DEFAULT_MIN_AGE_MS;
+  if (!Number.isInteger(age) || age < MIN_SAFE_AGE_MS || age > 30 * 24 * 60 * 60 * 1000) {
+    throw serviceError(
+      'INVALID_PAYLOAD',
+      'Storage orphan minimum age must be between 1 minute and 30 days',
+    );
+  }
+  return age;
+}
+
+function objectAgeMs(object, nowMs) {
+  if (!object?.modifiedAt) return null;
+  const modifiedMs = new Date(object.modifiedAt).getTime();
+  if (!Number.isFinite(modifiedMs)) return null;
+  return Math.max(0, nowMs - modifiedMs);
+}
+
+export class FileReconciliationService extends BaseService {
+  constructor(options = {}) {
+    super(options);
+    if (!options.storage) throw new Error('FileReconciliationService requires a storage registry');
+    this.storage = options.storage;
+  }
+
+  async scan({
+    storage = 'local',
+    deleteOrphans = false,
+    minimumAgeMs = DEFAULT_MIN_AGE_MS,
+  } = {}) {
+    assertFileManager(this.accountability);
+    const ageGuardMs = normalizeAge(minimumAgeMs);
+    const driver = this.storage.get(storage);
+    if (typeof driver.list !== 'function') {
+      throw serviceError(
+        'STORAGE_INVENTORY_UNSUPPORTED',
+        `Storage driver ${storage} does not support inventory listing`,
+      );
+    }
+
+    const [rows] = await this.database.query(
+      `SELECT id, filename_disk, filename_download, filesize, uploaded_at
+       FROM yuncms_files
+       WHERE storage = ?
+       ORDER BY uploaded_at ASC, id ASC`,
+      [storage],
+    );
+    const objects = await driver.list();
+    if (objects.length > MAX_INVENTORY_OBJECTS) {
+      throw serviceError(
+        'STORAGE_INVENTORY_LIMIT',
+        `Storage inventory exceeds the V1 safety limit of ${MAX_INVENTORY_OBJECTS} objects`,
+      );
+    }
+
+    const metadataByKey = new Map(rows.map((row) => [row.filename_disk, row]));
+    const objectByKey = new Map(objects.map((object) => [object.key, object]));
+    const missingObjects = rows
+      .filter((row) => !objectByKey.has(row.filename_disk))
+      .map((row) => ({
+        id: row.id,
+        key: row.filename_disk,
+        filename: row.filename_download,
+        expectedSize: Number(row.filesize ?? 0),
+        uploadedAt: row.uploaded_at,
+      }));
+
+    const nowMs = Date.now();
+    const orphanObjects = objects
+      .filter((object) => !metadataByKey.has(object.key))
+      .map((object) => {
+        const ageMs = objectAgeMs(object, nowMs);
+        return {
+          key: object.key,
+          size: Number(object.size ?? 0),
+          modifiedAt: object.modifiedAt ?? null,
+          ageMs,
+          eligibleForDelete: ageMs !== null && ageMs >= ageGuardMs,
+        };
+      });
+
+    const deletedOrphans = [];
+    if (deleteOrphans === true) {
+      for (const orphan of orphanObjects) {
+        if (!orphan.eligibleForDelete) continue;
+        await driver.delete(orphan.key);
+        deletedOrphans.push(orphan.key);
+      }
+    }
+
+    return {
+      storage,
+      minimumAgeMs: ageGuardMs,
+      deleteOrphans: deleteOrphans === true,
+      metadataCount: rows.length,
+      storageObjectCount: objects.length,
+      missingObjects,
+      orphanObjects,
+      deletedOrphans,
+    };
+  }
+}
+
+export {
+  DEFAULT_MIN_AGE_MS,
+  MAX_INVENTORY_OBJECTS,
+  MIN_SAFE_AGE_MS,
+  normalizeAge,
+  objectAgeMs,
+};