@kollors/deep-json-server 0.3.2 → 0.5.0

package/src/config.js

@@ -0,0 +1,97 @@
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isObject } from './utils.js';
+
+const CONFIG_KEYS = new Set(['database', 'files', 'openapi', 'server']);
+const DATABASE_KEYS = new Set(['path', 'schema']);
+const FILES_KEYS = new Set(['directory', 'metadata']);
+const OPENAPI_KEYS = new Set(['path']);
+const SERVER_KEYS = new Set(['host', 'port']);
+let configImportIndex = 0;
+
+const assertKnownKeys = (value, keys, path) => {
+  const unknownKey = Object.keys(value).find((key) => !keys.has(key));
+
+  if (unknownKey != null) {
+    throw new Error(`Неизвестный ключ ${path}.${unknownKey}`);
+  }
+};
+
+const getObject = (value, path) => {
+  if (value == null) {
+    return {};
+  }
+
+  if (!isObject(value)) {
+    throw new Error(`Ключ ${path} должен быть JSON-объектом`);
+  }
+
+  return value;
+};
+
+const getString = (value, path, required = false) => {
+  if (value == null && !required) {
+    return undefined;
+  }
+
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`Ключ ${path} должен содержать непустую строку`);
+  }
+
+  return value;
+};
+
+const resolveConfigPath = (value, directoryPath) => (value == null ? undefined : resolve(directoryPath, value));
+
+export async function readServerConfig(configPath) {
+  const resolvedConfigPath = resolve(getString(configPath, 'config', true));
+  let config;
+
+  try {
+    const configUrl = pathToFileURL(resolvedConfigPath);
+
+    configUrl.searchParams.set('deep-json-server-import', String(configImportIndex++));
+    config = (await import(configUrl.href)).default;
+  } catch (error) {
+    throw new Error(`Не удалось загрузить конфигурацию ${resolvedConfigPath}: ${error.message}`, { cause: error });
+  }
+
+  if (!isObject(config)) {
+    throw new Error('Конфигурация сервера должна экспортировать JSON-объект через export default');
+  }
+
+  assertKnownKeys(config, CONFIG_KEYS, 'config');
+
+  const database = getObject(config.database, 'config.database');
+  const files = getObject(config.files, 'config.files');
+  const openapi = getObject(config.openapi, 'config.openapi');
+  const server = getObject(config.server, 'config.server');
+
+  assertKnownKeys(database, DATABASE_KEYS, 'config.database');
+  assertKnownKeys(files, FILES_KEYS, 'config.files');
+  assertKnownKeys(openapi, OPENAPI_KEYS, 'config.openapi');
+  assertKnownKeys(server, SERVER_KEYS, 'config.server');
+
+  const directoryPath = dirname(resolvedConfigPath);
+  const databasePath = getString(database.path, 'config.database.path', true);
+  const schemaPath = getString(database.schema, 'config.database.schema');
+  const openapiPath = getString(openapi.path, 'config.openapi.path');
+  const filesDirectory = getString(files.directory, 'config.files.directory');
+  const filesMetadata = getString(files.metadata, 'config.files.metadata');
+  const host = getString(server.host, 'config.server.host');
+
+  if (server.port != null && (!Number.isInteger(server.port) || server.port < 0 || server.port > 65_535)) {
+    throw new Error('Ключ config.server.port должен быть целым числом от 0 до 65535');
+  }
+
+  return {
+    configPath: resolvedConfigPath,
+    databasePath: resolveConfigPath(databasePath, directoryPath),
+    filesDirectoryPath: resolveConfigPath(filesDirectory, directoryPath),
+    filesMetadataPath: resolveConfigPath(filesMetadata, directoryPath),
+    host,
+    openapiPath: resolveConfigPath(openapiPath, directoryPath),
+    port: server.port,
+    schemaPath: resolveConfigPath(schemaPath, directoryPath),
+  };
+}

package/src/constants.js

@@ -0,0 +1,5 @@
+export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024;
+export const DEFAULT_PAGE_SIZE = 10;
+export const DEFAULT_PORT = 4001;
+export const MAX_PAGE_SIZE = 1000;

package/src/database.js

@@ -0,0 +1,128 @@
+import { randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { JSONFilePreset } from 'lowdb/node';
+import { createHttpError, isObject, isSafeKey, resolveDatabasePath } from './utils.js';
+
+const RESOURCE_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+export const validateDatabase = (data) => {
+  if (!isObject(data)) {
+    throw new Error('База данных должна содержать JSON-объект');
+  }
+
+  Object.entries(data).forEach(([resource, records]) => {
+    if (!RESOURCE_NAME_PATTERN.test(resource) || !isSafeKey(resource)) {
+      throw new Error(`Недопустимое имя ресурса «${resource}»`);
+    }
+
+    if (!Array.isArray(records)) {
+      throw new Error(`Ресурс «${resource}» должен содержать JSON-массив`);
+    }
+
+    const ids = new Set();
+
+    records.forEach((record, index) => {
+      if (!isObject(record)) {
+        throw new Error(`Запись ${index} ресурса «${resource}» должна содержать JSON-объект`);
+      }
+
+      if (typeof record.id !== 'string' && !(typeof record.id === 'number' && Number.isFinite(record.id))) {
+        throw new Error(`Запись ${index} ресурса «${resource}» должна содержать строковый или числовой id`);
+      }
+
+      if (String(record.id) === '') {
+        throw new Error(`Запись ${index} ресурса «${resource}» должна содержать непустой id`);
+      }
+
+      const id = String(record.id);
+
+      if (ids.has(id)) {
+        throw new Error(`Ресурс «${resource}» содержит повторяющийся id «${id}»`);
+      }
+
+      ids.add(id);
+    });
+  });
+
+  return data;
+};
+
+export const readJsonObject = async (path, label) => {
+  let source;
+
+  try {
+    source = await readFile(resolve(path), 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(`${label} не найден: ${resolve(path)}`);
+    }
+
+    throw error;
+  }
+
+  const value = JSON.parse(source);
+
+  if (!isObject(value)) {
+    throw new Error(`${label} должен содержать JSON-объект`);
+  }
+
+  return value;
+};
+
+export const readDatabaseFile = async (databasePath) => validateDatabase(await readJsonObject(databasePath, 'Файл базы данных'));
+
+/** @returns {Promise<any>} Internal LowDB-backed store. */
+export const createDatabaseStore = async (databasePath) => {
+  const resolvedDatabasePath = resolveDatabasePath(databasePath);
+  const initialData = await readDatabaseFile(resolvedDatabasePath);
+  const database = await JSONFilePreset(resolvedDatabasePath, initialData);
+  let writeQueue = Promise.resolve();
+
+  const read = async () => {
+    database.data = await readDatabaseFile(resolvedDatabasePath);
+
+    return database.data;
+  };
+
+  const update = (operation) => {
+    const pendingOperation = writeQueue.then(async () => {
+      await read();
+
+      const result = operation(database);
+
+      validateDatabase(database.data);
+      await database.write();
+
+      return result;
+    });
+
+    writeQueue = pendingOperation.catch(() => undefined);
+
+    return pendingOperation;
+  };
+
+  return { database, path: resolvedDatabasePath, read, update };
+};
+
+export const getCollection = (database, resource) => {
+  const collection = isSafeKey(resource) ? database.data[resource] : undefined;
+
+  if (!Array.isArray(collection)) {
+    throw createHttpError(404, 'Ресурс не найден');
+  }
+
+  return collection;
+};
+
+export const findItem = (collection, id) => collection.find((item) => String(item.id) === String(id));
+
+export const createId = (collection) => {
+  let id;
+
+  do {
+    id = randomBytes(8).toString('base64url');
+  } while (findItem(collection, id) != null);
+
+  return id;
+};

package/src/files.js

@@ -0,0 +1,278 @@
+import { randomBytes } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { access, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createHttpError, isObject } from './utils.js';
+
+const createFileId = (files) => {
+  let id;
+
+  do {
+    id = randomBytes(8).toString('base64url');
+  } while (files.some((file) => file.id === id));
+
+  return id;
+};
+
+const validateFileMetadata = (files, metadataPath) => {
+  if (!Array.isArray(files)) {
+    throw new Error(`Файл метаданных ${metadataPath} должен содержать JSON-массив`);
+  }
+
+  const ids = new Set();
+
+  files.forEach((file, index) => {
+    if (
+      !isObject(file) ||
+      typeof file.id !== 'string' ||
+      file.id === '' ||
+      typeof file.mimeType !== 'string' ||
+      file.mimeType === '' ||
+      typeof file.name !== 'string' ||
+      file.name === '' ||
+      !Number.isInteger(file.size) ||
+      file.size < 0 ||
+      file.url !== `/_files/${file.id}`
+    ) {
+      throw new Error(`Некорректная запись ${index} в файле метаданных ${metadataPath}`);
+    }
+
+    if (ids.has(file.id)) {
+      throw new Error(`Файл метаданных ${metadataPath} содержит повторяющийся id «${file.id}»`);
+    }
+
+    ids.add(file.id);
+  });
+
+  return files;
+};
+
+const readMetadata = async (metadataPath) => {
+  try {
+    return validateFileMetadata(JSON.parse(await readFile(metadataPath, 'utf8')), metadataPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return [];
+    }
+
+    throw error;
+  }
+};
+
+const writeMetadata = async (metadataPath, files) => {
+  const temporaryPath = `${metadataPath}.${randomBytes(6).toString('hex')}.tmp`;
+
+  try {
+    await writeFile(temporaryPath, JSON.stringify(files, null, 2), { encoding: 'utf8', flag: 'wx' });
+    await rename(temporaryPath, metadataPath);
+  } catch (error) {
+    await rm(temporaryPath, { force: true });
+    throw error;
+  }
+};
+
+const getContentName = (value) => {
+  if (typeof value !== 'string' || value === '') {
+    throw createHttpError(400, 'Заголовок Content-Name обязателен');
+  }
+
+  let name;
+
+  try {
+    name = decodeURIComponent(value).replaceAll('\\', '/');
+  } catch {
+    throw createHttpError(400, 'Заголовок Content-Name содержит некорректное значение');
+  }
+
+  const parts = name.split('/');
+
+  if (name.startsWith('/') || parts.some((part) => part === '' || part === '.' || part === '..' || part.includes('\0'))) {
+    throw createHttpError(400, 'Заголовок Content-Name должен содержать безопасный относительный путь');
+  }
+
+  return name;
+};
+
+const getMimeType = (value) => {
+  const mimeType = typeof value === 'string' ? value.split(';', 1)[0].trim().toLowerCase() : '';
+
+  if (mimeType === '' || !/^[\w!#$&^.+-]+\/[\w!#$&^.+-]+$/.test(mimeType)) {
+    throw createHttpError(400, 'Заголовок Content-Type должен содержать корректный MIME-тип');
+  }
+
+  return mimeType;
+};
+
+const createSizeLimiter = (maxFileSize, onSize) => {
+  let size = 0;
+
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      size += chunk.length;
+
+      if (size > maxFileSize) {
+        callback(createHttpError(413, `Размер файла не должен превышать ${maxFileSize} байт`));
+        return;
+      }
+
+      onSize(size);
+      callback(null, chunk);
+    },
+  });
+};
+
+const createFileStore = async ({ directoryPath: sourceDirectoryPath, metadataPath: sourceMetadataPath }) => {
+  if (typeof sourceDirectoryPath !== 'string' || sourceDirectoryPath.trim() === '') {
+    throw new Error('Путь к директории файлов не должен быть пустым');
+  }
+
+  if (typeof sourceMetadataPath !== 'string' || sourceMetadataPath.trim() === '') {
+    throw new Error('Путь к файлу метаданных не должен быть пустым');
+  }
+
+  const directoryPath = resolve(sourceDirectoryPath);
+  const metadataPath = resolve(sourceMetadataPath);
+  let operationQueue = Promise.resolve();
+
+  await Promise.all([mkdir(directoryPath, { recursive: true }), mkdir(dirname(metadataPath), { recursive: true })]);
+  await readMetadata(metadataPath);
+
+  const schedule = (operation) => {
+    const pendingOperation = operationQueue.then(operation);
+
+    operationQueue = pendingOperation.catch(() => undefined);
+
+    return pendingOperation;
+  };
+
+  const get = (id) =>
+    schedule(async () => {
+      const files = await readMetadata(metadataPath);
+      const file = files.find((item) => item.id === id);
+
+      if (file == null) {
+        throw createHttpError(404, 'Файл не найден');
+      }
+
+      const path = join(directoryPath, file.id);
+
+      try {
+        await access(path);
+      } catch (error) {
+        if (error?.code === 'ENOENT') {
+          throw createHttpError(404, 'Файл не найден');
+        }
+
+        throw error;
+      }
+
+      return { file, path };
+    });
+
+  const upload = ({ maxFileSize, mimeType, name, stream }) =>
+    schedule(async () => {
+      const files = await readMetadata(metadataPath);
+      const id = createFileId(files);
+      const path = join(directoryPath, id);
+      const temporaryPath = `${path}.upload`;
+      let size = 0;
+
+      try {
+        await pipeline(
+          stream,
+          createSizeLimiter(maxFileSize, (value) => (size = value)),
+          createWriteStream(temporaryPath, { flags: 'wx' }),
+        );
+        await rename(temporaryPath, path);
+
+        const file = { id, mimeType, name, size, url: `/_files/${id}` };
+
+        files.push(file);
+        await writeMetadata(metadataPath, files);
+
+        return file;
+      } catch (error) {
+        await Promise.all([rm(temporaryPath, { force: true }), rm(path, { force: true })]);
+        throw error;
+      }
+    });
+
+  const remove = (id) =>
+    schedule(async () => {
+      const files = await readMetadata(metadataPath);
+      const index = files.findIndex((file) => file.id === id);
+
+      if (index === -1) {
+        throw createHttpError(404, 'Файл не найден');
+      }
+
+      const [file] = files.splice(index, 1);
+      const path = join(directoryPath, file.id);
+      const temporaryPath = `${path}.${randomBytes(6).toString('hex')}.delete`;
+
+      try {
+        await rename(path, temporaryPath);
+      } catch (error) {
+        if (error?.code === 'ENOENT') {
+          throw createHttpError(404, 'Файл не найден');
+        }
+
+        throw error;
+      }
+
+      try {
+        await writeMetadata(metadataPath, files);
+      } catch (error) {
+        await rename(temporaryPath, path);
+        throw error;
+      }
+
+      await rm(temporaryPath, { force: true }).catch(() => undefined);
+
+      return file;
+    });
+
+  return { get, remove, upload };
+};
+
+const getDownloadName = (name) => encodeURIComponent(basename(name)).replaceAll("'", '%27');
+
+export const registerFileRoutes = async (server, { directoryPath, maxFileSize, metadataPath }) => {
+  const store = await createFileStore({ directoryPath, metadataPath });
+
+  server.register((fileServer, _options, done) => {
+    fileServer.removeAllContentTypeParsers();
+    fileServer.addContentTypeParser('*', (_request, payload, parserDone) => parserDone(null, payload));
+
+    fileServer.post('/_files', async (request, reply) => {
+      const contentLength = Number(request.headers['content-length']);
+
+      if (Number.isFinite(contentLength) && contentLength > maxFileSize) {
+        throw createHttpError(413, `Размер файла не должен превышать ${maxFileSize} байт`);
+      }
+
+      const file = await store.upload({
+        maxFileSize,
+        mimeType: getMimeType(request.headers['content-type']),
+        name: getContentName(request.headers['content-name']),
+        stream: request.body,
+      });
+
+      return reply.code(201).send(file);
+    });
+
+    fileServer.get('/_files/:id', async (request, reply) => {
+      const { file, path } = await store.get(request.params.id);
+
+      reply.header('Content-Disposition', `inline; filename*=UTF-8''${getDownloadName(file.name)}`);
+      reply.type(file.mimeType);
+
+      return reply.send(createReadStream(path));
+    });
+
+    fileServer.delete('/_files/:id', async (request) => store.remove(request.params.id));
+    done();
+  });
+};

package/src/openapi/config.js

@@ -0,0 +1,110 @@
+import { readJsonObject } from '../database.js';
+import { isObject } from '../utils.js';
+import { applyRequiredFields, getSchemasAtPath, updateSchemasAtPath } from './inference.js';
+
+const validateSchemaOverride = (schema, path) => {
+  if (!isObject(schema)) {
+    throw new Error(`OpenAPI-схема свойства «${path}» должна содержать JSON-объект`);
+  }
+
+  if (schema.properties != null) {
+    if (!isObject(schema.properties)) {
+      throw new Error(`properties свойства «${path}» должен содержать JSON-объект`);
+    }
+
+    Object.entries(schema.properties).forEach(([key, value]) => {
+      validateSchemaOverride(value, `${path}.${key}`);
+    });
+  }
+
+  if (schema.items != null) {
+    validateSchemaOverride(schema.items, `${path}[]`);
+  }
+
+  if (schema.oneOf != null) {
+    if (!Array.isArray(schema.oneOf) || schema.oneOf.length === 0) {
+      throw new Error(`oneOf свойства «${path}» должен содержать непустой массив`);
+    }
+
+    schema.oneOf.forEach((value, index) => {
+      validateSchemaOverride(value, `${path}.oneOf[${index}]`);
+    });
+  }
+};
+
+export const validateSchemaConfig = (schemaConfig, resources) => {
+  if (
+    Object.hasOwn(schemaConfig, '$info') &&
+    (!isObject(schemaConfig.$info) || !['title', 'version'].every((key) => typeof schemaConfig.$info[key] === 'string' && schemaConfig.$info[key].trim() !== ''))
+  ) {
+    throw new Error('$info должен содержать непустые строковые поля title и version');
+  }
+
+  if (Object.hasOwn(schemaConfig, '$schema') && !isObject(schemaConfig.$schema)) {
+    throw new Error('$schema должен содержать JSON-объект');
+  }
+
+  const resourceConfigs = schemaConfig.$schema ?? {};
+
+  Object.entries(resourceConfigs).forEach(([resource, resourceConfig]) => {
+    if (!resources.includes(resource)) {
+      throw new Error(`В $schema указан неизвестный ресурс «${resource}»`);
+    }
+
+    if (!isObject(resourceConfig)) {
+      throw new Error(`Настройки ресурса «${resource}» должны содержать JSON-объект`);
+    }
+
+    if (resourceConfig.name != null && (typeof resourceConfig.name !== 'string' || resourceConfig.name.trim() === '')) {
+      throw new Error(`$schema.${resource}.name должен содержать непустую строку`);
+    }
+
+    if (resourceConfig.required != null && (!Array.isArray(resourceConfig.required) || resourceConfig.required.some((path) => typeof path !== 'string' || path === ''))) {
+      throw new Error(`$schema.${resource}.required должен содержать массив непустых строк`);
+    }
+
+    if (
+      resourceConfig.formats != null &&
+      (!isObject(resourceConfig.formats) || Object.entries(resourceConfig.formats).some(([path, format]) => path === '' || typeof format !== 'string' || format === ''))
+    ) {
+      throw new Error(`$schema.${resource}.formats должен содержать JSON-объект с непустыми строковыми путями и форматами`);
+    }
+
+    if (resourceConfig.properties != null) {
+      if (!isObject(resourceConfig.properties)) {
+        throw new Error(`$schema.${resource}.properties должен содержать JSON-объект`);
+      }
+
+      Object.entries(resourceConfig.properties).forEach(([key, value]) => {
+        validateSchemaOverride(value, `${resource}.${key}`);
+      });
+    }
+  });
+
+  return resourceConfigs;
+};
+
+export const applyConfiguredFields = (schema, resource, resourceConfig) => {
+  const requiredFields = Array.isArray(resourceConfig.required) ? resourceConfig.required : [];
+  const formats = isObject(resourceConfig.formats) ? resourceConfig.formats : {};
+
+  [...requiredFields, ...Object.keys(formats)].forEach((path) => {
+    if (getSchemasAtPath(schema, path.split('.')).length === 0) {
+      throw new Error(`Путь «${path}» из настроек ресурса «${resource}» отсутствует в итоговой схеме`);
+    }
+  });
+
+  const schemaWithFormats = Object.entries(formats).reduce((result, [path, format]) => {
+    const schemas = getSchemasAtPath(result, path.split('.'));
+
+    if (!schemas.some((nestedSchema) => nestedSchema.type === 'string')) {
+      throw new Error(`Формат «${format}» для пути «${resource}.${path}» можно применить только к строковому полю`);
+    }
+
+    return updateSchemasAtPath(result, path.split('.'), (nestedSchema) => (nestedSchema.type === 'string' ? { ...nestedSchema, format } : nestedSchema));
+  }, schema);
+
+  return applyRequiredFields(schemaWithFormats, '', new Set(requiredFields));
+};
+
+export const readSchemaConfig = async (schemaPath) => (schemaPath == null ? {} : readJsonObject(schemaPath, 'Файл схемы базы данных'));