@yunsoft/yuncms-core 0.1.0

package/src/services/files-service.js

@@ -0,0 +1,227 @@
+import { randomUUID } from 'node:crypto';
+
+import { BaseService } from './base-service.js';
+
+function fileError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function assertFileManager(accountability) {
+  if (accountability.admin === true || accountability.system === true) return;
+  throw fileError('FORBIDDEN', 'File management requires administrator accountability in V1');
+}
+
+function normalizeFilename(value) {
+  if (typeof value !== 'string') throw fileError('INVALID_PAYLOAD', 'Download filename is required');
+  const filename = value.trim();
+  if (!filename || filename.length > 255 || /[\u0000-\u001f\u007f]/.test(filename)) {
+    throw fileError('INVALID_PAYLOAD', 'Download filename is invalid');
+  }
+  return filename;
+}
+
+function normalizeMimeType(value) {
+  if (value == null || value === '') return 'application/octet-stream';
+  const mimetype = String(value).trim().toLowerCase();
+  if (!mimetype || mimetype.length > 191 || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mimetype)) {
+    throw fileError('INVALID_PAYLOAD', 'File MIME type is invalid');
+  }
+  return mimetype;
+}
+
+function decodeJson(value) {
+  if (value == null || typeof value === 'object') return value ?? null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeRow(row) {
+  return row ? { ...row, metadata: decodeJson(row.metadata) } : null;
+}
+
+export class FilesService extends BaseService {
+  constructor(options = {}) {
+    super(options);
+    if (!options.storage) throw new Error('FilesService requires a storage registry');
+    this.storage = options.storage;
+  }
+
+  async action(event, payload) {
+    if (!this.emitter) return;
+    await this.emitter.action(event, payload, {
+      accountability: this.accountability,
+      requestId: this.requestId,
+      collection: 'yuncms_files',
+    });
+  }
+
+  async readMany() {
+    assertFileManager(this.accountability);
+    const [rows] = await this.database.query(
+      `SELECT id, storage, filename_disk, filename_download, title, mimetype, filesize,
+              uploaded_by, uploaded_at, metadata
+       FROM yuncms_files
+       ORDER BY uploaded_at DESC, id DESC`,
+    );
+    return rows.map(normalizeRow);
+  }
+
+  async readOne(id) {
+    assertFileManager(this.accountability);
+    const [rows] = await this.database.query(
+      `SELECT id, storage, filename_disk, filename_download, title, mimetype, filesize,
+              uploaded_by, uploaded_at, metadata
+       FROM yuncms_files
+       WHERE id = ?
+       LIMIT 1`,
+      [id],
+    );
+    return normalizeRow(rows[0]);
+  }
+
+  async createOne({
+    contents,
+    filenameDownload,
+    title = null,
+    mimetype = 'application/octet-stream',
+    storage = 'local',
+    metadata = null,
+  } = {}) {
+    assertFileManager(this.accountability);
+    if (!Buffer.isBuffer(contents) && !(contents instanceof Uint8Array)) {
+      throw fileError('INVALID_FILE_CONTENT', 'File contents must be Buffer or Uint8Array');
+    }
+    if (contents.byteLength === 0) throw fileError('INVALID_FILE_CONTENT', 'Empty file uploads are not allowed');
+
+    const filename = normalizeFilename(filenameDownload);
+    const normalizedMime = normalizeMimeType(mimetype);
+    const driver = this.storage.get(storage);
+    const id = randomUUID();
+    const filenameDisk = id;
+    let stored = false;
+
+    try {
+      await driver.put(filenameDisk, contents);
+      stored = true;
+      await this.database.query(
+        `INSERT INTO yuncms_files
+         (id, storage, filename_disk, filename_download, title, mimetype, filesize, uploaded_by, metadata)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          id,
+          storage,
+          filenameDisk,
+          filename,
+          title == null ? null : String(title).slice(0, 255),
+          normalizedMime,
+          contents.byteLength,
+          this.accountability.user ?? null,
+          metadata == null ? null : JSON.stringify(metadata),
+        ],
+      );
+      const file = await this.readOne(id);
+      await this.action('files.create', {
+        key: id,
+        item: file,
+      });
+      return file;
+    } catch (error) {
+      if (stored) {
+        try {
+          await driver.delete(filenameDisk);
+        } catch (cleanupError) {
+          error.cleanupError = cleanupError;
+          error.code ||= 'FILE_STORAGE_CLEANUP_FAILED';
+        }
+      }
+      throw error;
+    }
+  }
+
+  async readContent(id) {
+    const file = await this.readOne(id);
+    if (!file) throw fileError('FILE_NOT_FOUND', `Unknown file: ${id}`);
+    const driver = this.storage.get(file.storage);
+    const contents = await driver.get(file.filename_disk);
+    return { file, contents };
+  }
+
+  async updateOne(id, patch = {}) {
+    assertFileManager(this.accountability);
+    if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+      throw fileError('INVALID_PAYLOAD', 'File metadata patch must be an object');
+    }
+    const keys = Object.keys(patch);
+    if (keys.length === 0 || keys.some((key) => !['filenameDownload', 'title', 'metadata'].includes(key))) {
+      throw fileError('INVALID_PAYLOAD', 'File update supports filenameDownload, title and metadata only');
+    }
+
+    const before = await this.readOne(id);
+    if (!before) throw fileError('FILE_NOT_FOUND', `Unknown file: ${id}`);
+
+    const assignments = [];
+    const params = [];
+    if (Object.hasOwn(patch, 'filenameDownload')) {
+      assignments.push('filename_download = ?');
+      params.push(normalizeFilename(patch.filenameDownload));
+    }
+    if (Object.hasOwn(patch, 'title')) {
+      assignments.push('title = ?');
+      params.push(patch.title == null ? null : String(patch.title).slice(0, 255));
+    }
+    if (Object.hasOwn(patch, 'metadata')) {
+      assignments.push('metadata = ?');
+      params.push(patch.metadata == null ? null : JSON.stringify(patch.metadata));
+    }
+
+    params.push(id);
+    const [result] = await this.database.query(
+      `UPDATE yuncms_files SET ${assignments.join(', ')} WHERE id = ?`,
+      params,
+    );
+    if (result.affectedRows !== 1) throw fileError('FILE_NOT_FOUND', `Unknown file: ${id}`);
+    const file = await this.readOne(id);
+    await this.action('files.update', {
+      key: id,
+      before,
+      item: file,
+      changes: patch,
+    });
+    return file;
+  }
+
+  async deleteOne(id) {
+    assertFileManager(this.accountability);
+    const file = await this.readOne(id);
+    if (!file) throw fileError('FILE_NOT_FOUND', `Unknown file: ${id}`);
+
+    const [result] = await this.database.query('DELETE FROM yuncms_files WHERE id = ?', [id]);
+    if (result.affectedRows !== 1) throw fileError('FILE_NOT_FOUND', `Unknown file: ${id}`);
+
+    const driver = this.storage.get(file.storage);
+    try {
+      await driver.delete(file.filename_disk);
+    } catch (cleanupError) {
+      const error = fileError(
+        'FILE_STORAGE_CLEANUP_FAILED',
+        'File metadata was deleted but the storage object could not be removed',
+      );
+      error.cleanupError = cleanupError;
+      error.file = file;
+      throw error;
+    }
+
+    await this.action('files.delete', {
+      key: id,
+      before: file,
+    });
+    return true;
+  }
+}
+
+export { normalizeFilename, normalizeMimeType };

package/src/services/items-service.js

@@ -0,0 +1,445 @@
+import { randomUUID } from 'node:crypto';
+
+import { assertIdentifier, quoteIdentifier } from '../identifier.js';
+import { enforcePermissionValidation } from '../permission-validation.js';
+import {
+  compileFilter,
+  compileSelectFields,
+  compileSort,
+  parseItemsQuery,
+} from '../query.js';
+import { SchemaCache } from '../schema.js';
+import { withTransaction } from '../transaction.js';
+import { BaseService } from './base-service.js';
+import { PermissionsService } from './permissions-service.js';
+
+const defaultSchemaCache = new SchemaCache();
+const MAX_BULK_VALIDATION_ROWS = 5000;
+
+function serviceError(code, message, path = null) {
+  const error = new Error(message);
+  error.code = code;
+  if (path) error.path = path;
+  return error;
+}
+
+function parseMetadata(value) {
+  if (value == null || typeof value === 'object') return value ?? {};
+  try {
+    return JSON.parse(value);
+  } catch {
+    return {};
+  }
+}
+
+function schemaForFields(schema, allowedFields) {
+  if (allowedFields == null) return schema;
+  return {
+    ...schema,
+    fields: Object.fromEntries(
+      allowedFields
+        .filter((field) => schema.fields[field])
+        .map((field) => [field, schema.fields[field]]),
+    ),
+  };
+}
+
+function normalizeFields(fields) {
+  if (fields == null) return null;
+  if (Array.isArray(fields)) return fields;
+  return String(fields).split(',').map((field) => field.trim()).filter(Boolean);
+}
+
+function combineCompiledFilters(...filters) {
+  const active = filters.filter((filter) => filter?.sql);
+  if (active.length === 0) return { sql: '', params: [] };
+
+  return {
+    sql: ` WHERE ${active.map((filter) => `(${filter.sql.replace(/^ WHERE /, '')})`).join(' AND ')}`,
+    params: active.flatMap((filter) => filter.params),
+  };
+}
+
+function createCandidateRecord(schema, id, entries) {
+  const provided = Object.fromEntries(entries);
+  const candidate = {};
+
+  for (const fieldSchema of Object.values(schema.fields)) {
+    if (fieldSchema.field === schema.primary_key) {
+      candidate[fieldSchema.field] = id;
+      continue;
+    }
+    if (Object.hasOwn(provided, fieldSchema.field)) {
+      candidate[fieldSchema.field] = provided[fieldSchema.field];
+      continue;
+    }
+    const metadata = parseMetadata(fieldSchema.schema_metadata);
+    candidate[fieldSchema.field] = Object.hasOwn(metadata, 'defaultValue')
+      ? metadata.defaultValue
+      : null;
+  }
+
+  return candidate;
+}
+
+export class ItemsService extends BaseService {
+  constructor(collection, options = {}) {
+    super(options);
+    this.collection = assertIdentifier(collection, 'collection name');
+    this.schemaCache = options.schemaCache ?? defaultSchemaCache;
+  }
+
+  hookContext(extra = {}) {
+    return {
+      accountability: this.accountability,
+      collection: this.collection,
+      requestId: this.requestId,
+      ...extra,
+    };
+  }
+
+  async filterMutation(event, payload, context = {}) {
+    if (!this.emitter) return payload;
+    return this.emitter.filter(event, payload, this.hookContext(context));
+  }
+
+  async actionMutation(event, payload, context = {}) {
+    if (!this.emitter) return;
+    await this.emitter.action(event, payload, this.hookContext(context));
+  }
+
+  async getCollectionSchema(database = this.database) {
+    const snapshot = this.schema ?? await this.schemaCache.get(database);
+    const collectionSchema = snapshot?.collections?.[this.collection];
+    if (!collectionSchema) {
+      throw serviceError('COLLECTION_NOT_FOUND', `Unknown collection: ${this.collection}`);
+    }
+    return collectionSchema;
+  }
+
+  async resolvePermission(action) {
+    const permissions = new PermissionsService({
+      accountability: this.accountability,
+      database: this.database,
+      schema: this.schema,
+      schemaCache: this.schemaCache,
+      emitter: this.emitter,
+      logger: this.logger,
+      permissionCache: this.permissionCache,
+      requestId: this.requestId,
+    });
+    return permissions.resolve(action, this.collection);
+  }
+
+  validatePayload(payload, schema, permission, { creating = false } = {}) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+      throw serviceError('INVALID_PAYLOAD', 'Payload must be an object');
+    }
+
+    const entries = Object.entries(payload);
+    for (const [field] of entries) {
+      const fieldSchema = schema.fields[field];
+      if (!fieldSchema) throw serviceError('INVALID_PAYLOAD', `Unknown field: ${field}`, field);
+      if (fieldSchema.readonly) throw serviceError('FIELD_READ_ONLY', `Field is read-only: ${field}`, field);
+      if (permission.fields && !permission.fields.includes(field)) {
+        throw serviceError('FORBIDDEN_FIELD', `Field is not allowed for ${permission.action}: ${field}`, field);
+      }
+    }
+
+    if (creating) {
+      for (const fieldSchema of Object.values(schema.fields)) {
+        if (!fieldSchema.required || fieldSchema.field === schema.primary_key) continue;
+        if (Object.hasOwn(payload, fieldSchema.field)) continue;
+        const metadata = parseMetadata(fieldSchema.schema_metadata);
+        if (Object.hasOwn(metadata, 'defaultValue')) continue;
+        throw serviceError('REQUIRED_FIELD_MISSING', `Required field is missing: ${fieldSchema.field}`, fieldSchema.field);
+      }
+    }
+
+    return entries;
+  }
+
+  compileActionFilters(userFilter, permissionFilter, userSchema, fullSchema) {
+    const permissionSql = compileFilter(permissionFilter, fullSchema);
+    const userSql = compileFilter(userFilter, userSchema);
+    return combineCompiledFilters(permissionSql, userSql);
+  }
+
+  async readMany(rawQuery = {}) {
+    return (await this.readManyWithMeta(rawQuery)).data;
+  }
+
+  async readManyWithMeta(rawQuery = {}) {
+    const schema = await this.getCollectionSchema();
+    const permission = await this.resolvePermission('read');
+    const accessSchema = schemaForFields(schema, permission.fields);
+    const query = parseItemsQuery(rawQuery);
+    const requestedFields = normalizeFields(query.fields);
+    const selected = compileSelectFields(requestedFields, accessSchema);
+    const filter = this.compileActionFilters(query.filter, permission.filter, accessSchema, schema);
+    const sortSql = compileSort(query.sort, accessSchema);
+    const table = quoteIdentifier(this.collection, 'collection name');
+
+    const [rows] = await this.database.query(
+      `SELECT ${selected.sql} FROM ${table}${filter.sql}${sortSql} LIMIT ? OFFSET ?`,
+      [...filter.params, query.limit, query.offset],
+    );
+    const [countRows] = await this.database.query(
+      `SELECT COUNT(*) AS total_count FROM ${table}${filter.sql}`,
+      filter.params,
+    );
+
+    return {
+      data: rows,
+      meta: {
+        total_count: Number(countRows?.[0]?.total_count ?? 0),
+        limit: query.limit,
+        offset: query.offset,
+      },
+    };
+  }
+
+  async readOne(id, { fields = null } = {}) {
+    const schema = await this.getCollectionSchema();
+    const permission = await this.resolvePermission('read');
+    const accessSchema = schemaForFields(schema, permission.fields);
+    const selected = compileSelectFields(normalizeFields(fields), accessSchema);
+    const table = quoteIdentifier(this.collection, 'collection name');
+    const primaryKey = schema.primary_key;
+    const filter = combineCompiledFilters(
+      compileFilter(permission.filter, schema),
+      compileFilter({ [primaryKey]: { _eq: id } }, schema),
+    );
+    const [rows] = await this.database.query(
+      `SELECT ${selected.sql} FROM ${table}${filter.sql} LIMIT 1`,
+      filter.params,
+    );
+    return rows[0] ?? null;
+  }
+
+  async returnCreatedOrUpdated(id, schema) {
+    try {
+      return await this.readOne(id);
+    } catch (error) {
+      if (error?.code !== 'FORBIDDEN') throw error;
+      return { [schema.primary_key]: id };
+    }
+  }
+
+  async createOne(payload = {}) {
+    const schema = await this.getCollectionSchema();
+    const permission = await this.resolvePermission('create');
+    const filteredPayload = await this.filterMutation('items.create', payload, { operation: 'create' });
+    const entries = this.validatePayload(filteredPayload, schema, permission, { creating: true });
+    const id = randomUUID();
+    const candidate = createCandidateRecord(schema, id, entries);
+    enforcePermissionValidation(candidate, permission.validation, schema);
+
+    const values = { [schema.primary_key]: id, ...Object.fromEntries(entries) };
+    const fields = Object.keys(values);
+    const table = quoteIdentifier(this.collection, 'collection name');
+
+    await this.database.query(
+      `INSERT INTO ${table} (${fields.map((field) => quoteIdentifier(field, 'field name')).join(', ')})
+       VALUES (${fields.map(() => '?').join(', ')})`,
+      fields.map((field) => values[field]),
+    );
+
+    const record = await this.returnCreatedOrUpdated(id, schema);
+    await this.actionMutation('items.create', { key: id, item: record }, { operation: 'create' });
+    return record;
+  }
+
+  async createMany(payloads = []) {
+    if (!Array.isArray(payloads) || payloads.length === 0) {
+      throw serviceError('INVALID_PAYLOAD', 'createMany requires a non-empty array');
+    }
+
+    const schema = await this.getCollectionSchema();
+    const permission = await this.resolvePermission('create');
+    const staged = [];
+
+    for (const payload of payloads) {
+      const filteredPayload = await this.filterMutation('items.create', payload, {
+        operation: 'create',
+        bulk: true,
+      });
+      const entries = this.validatePayload(filteredPayload, schema, permission, { creating: true });
+      const id = randomUUID();
+      const candidate = createCandidateRecord(schema, id, entries);
+      enforcePermissionValidation(candidate, permission.validation, schema);
+      staged.push({
+        id,
+        values: { [schema.primary_key]: id, ...Object.fromEntries(entries) },
+      });
+    }
+
+    await withTransaction(this.database, async (connection) => {
+      const table = quoteIdentifier(this.collection, 'collection name');
+
+      for (const entry of staged) {
+        const fields = Object.keys(entry.values);
+        await connection.query(
+          `INSERT INTO ${table} (${fields.map((field) => quoteIdentifier(field, 'field name')).join(', ')})
+           VALUES (${fields.map(() => '?').join(', ')})`,
+          fields.map((field) => entry.values[field]),
+        );
+      }
+    });
+
+    const records = [];
+    for (const entry of staged) {
+      const record = await this.returnCreatedOrUpdated(entry.id, schema);
+      records.push(record);
+      await this.actionMutation('items.create', { key: entry.id, item: record }, {
+        operation: 'create',
+        bulk: true,
+      });
+    }
+    return records;
+  }
+
+  async updateOne(id, payload = {}) {
+    const schema = await this.getCollectionSchema();
+    const permission = await this.resolvePermission('update');
+    const filteredPayload = await this.filterMutation('items.update', payload, {
+      operation: 'update',
+      key: id,
+    });
+    const entries = this.validatePayload(filteredPayload, schema, permission);
+    if (entries.length === 0) throw serviceError('INVALID_PAYLOAD', 'Update payload cannot be empty');
+
+    const table = quoteIdentifier(this.collection, 'collection name');
+    const filter = combineCompiledFilters(
+      compileFilter(permission.filter, schema),
+      compileFilter({ [schema.primary_key]: { _eq: id } }, schema),
+    );
+
+    if (permission.validation) {
+      const [currentRows] = await this.database.query(
+        `SELECT * FROM ${table}${filter.sql} LIMIT 1`,
+        filter.params,
+      );
+      const current = currentRows[0];
+      if (!current) return null;
+      enforcePermissionValidation({ ...current, ...filteredPayload }, permission.validation, schema);
+    }
+
+    const setSql = entries.map(([field]) => `${quoteIdentifier(field, 'field name')} = ?`).join(', ');
+    const [result] = await this.database.query(
+      `UPDATE ${table} SET ${setSql}${filter.sql}`,
+      [...entries.map(([, value]) => value), ...filter.params],
+    );
+
+    if (result.affectedRows === 0) return null;
+    const record = await this.returnCreatedOrUpdated(id, schema);
+    await this.actionMutation('items.update', {
+      key: id,
+      item: record,
+      changes: filteredPayload,
+    }, { operation: 'update' });
+    return record;
+  }
+
+  async updateMany(filterInput, payload = {}) {
+    if (!filterInput || typeof filterInput !== 'object' || Array.isArray(filterInput) || Object.keys(filterInput).length === 0) {
+      throw serviceError('FILTER_REQUIRED', 'updateMany requires an explicit non-empty filter');
+    }
+
+    const schema = await this.getCollectionSchema();
+    const permission = await this.resolvePermission('update');
+    const accessSchema = schemaForFields(schema, permission.fields);
+    const filteredPayload = await this.filterMutation('items.update', payload, {
+      operation: 'update',
+      bulk: true,
+      filter: filterInput,
+    });
+    const entries = this.validatePayload(filteredPayload, schema, permission);
+    if (entries.length === 0) throw serviceError('INVALID_PAYLOAD', 'Update payload cannot be empty');
+    const filter = this.compileActionFilters(filterInput, permission.filter, accessSchema, schema);
+    const table = quoteIdentifier(this.collection, 'collection name');
+
+    if (permission.validation) {
+      const [rows] = await this.database.query(
+        `SELECT * FROM ${table}${filter.sql} LIMIT ?`,
+        [...filter.params, MAX_BULK_VALIDATION_ROWS + 1],
+      );
+      if (rows.length > MAX_BULK_VALIDATION_ROWS) {
+        throw serviceError(
+          'VALIDATION_BULK_LIMIT',
+          `Permission validation can inspect at most ${MAX_BULK_VALIDATION_ROWS} rows per bulk update`,
+        );
+      }
+      for (const row of rows) {
+        enforcePermissionValidation({ ...row, ...filteredPayload }, permission.validation, schema);
+      }
+    }
+
+    const setSql = entries.map(([field]) => `${quoteIdentifier(field, 'field name')} = ?`).join(', ');
+    const [result] = await this.database.query(
+      `UPDATE ${table} SET ${setSql}${filter.sql}`,
+      [...entries.map(([, value]) => value), ...filter.params],
+    );
+    await this.actionMutation('items.update', {
+      filter: filterInput,
+      changes: filteredPayload,
+      affected: result.affectedRows,
+    }, { operation: 'update', bulk: true });
+    return result.affectedRows;
+  }
+
+  async deleteOne(id) {
+    const schema = await this.getCollectionSchema();
+    const permission = await this.resolvePermission('delete');
+    const filtered = await this.filterMutation('items.delete', { key: id }, {
+      operation: 'delete',
+      key: id,
+    });
+    const key = filtered?.key ?? id;
+    const table = quoteIdentifier(this.collection, 'collection name');
+    const filter = combineCompiledFilters(
+      compileFilter(permission.filter, schema),
+      compileFilter({ [schema.primary_key]: { _eq: key } }, schema),
+    );
+    const [result] = await this.database.query(
+      `DELETE FROM ${table}${filter.sql}`,
+      filter.params,
+    );
+    const deleted = result.affectedRows > 0;
+    if (deleted) {
+      await this.actionMutation('items.delete', { key }, { operation: 'delete' });
+    }
+    return deleted;
+  }
+
+  async deleteMany(filterInput) {
+    if (!filterInput || typeof filterInput !== 'object' || Array.isArray(filterInput) || Object.keys(filterInput).length === 0) {
+      throw serviceError('FILTER_REQUIRED', 'deleteMany requires an explicit non-empty filter');
+    }
+
+    const schema = await this.getCollectionSchema();
+    const permission = await this.resolvePermission('delete');
+    const accessSchema = schemaForFields(schema, permission.fields);
+    const filtered = await this.filterMutation('items.delete', { filter: filterInput }, {
+      operation: 'delete',
+      bulk: true,
+    });
+    const effectiveFilter = filtered?.filter ?? filterInput;
+    if (!effectiveFilter || typeof effectiveFilter !== 'object' || Array.isArray(effectiveFilter) || Object.keys(effectiveFilter).length === 0) {
+      throw serviceError('FILTER_REQUIRED', 'deleteMany hook result must preserve a non-empty filter');
+    }
+    const filter = this.compileActionFilters(effectiveFilter, permission.filter, accessSchema, schema);
+    const table = quoteIdentifier(this.collection, 'collection name');
+    const [result] = await this.database.query(
+      `DELETE FROM ${table}${filter.sql}`,
+      filter.params,
+    );
+    await this.actionMutation('items.delete', {
+      filter: effectiveFilter,
+      affected: result.affectedRows,
+    }, { operation: 'delete', bulk: true });
+    return result.affectedRows;
+  }
+}
+
+export { MAX_BULK_VALIDATION_ROWS, createCandidateRecord };