@nerest/nerest 0.0.1 → 0.0.2

package/README.md

@@ -10,14 +10,26 @@ React micro frontend framework
 npm i --save @nerest/nerest react react-dom
 ```
 
+## Points of Interest
+
+- SSR server entry: [server/index.ts](server/index.ts)
+- Hydrating client entry: [client/index.ts](client/index.ts)
+- CLI entry: [bin/index.ts](bin/index.ts)
+
 ## Conventions
 
 The `apps` directory must contain all of the apps provided by the micro frontend. E.g. `/apps/foo/index.tsx` is the entrypoint component of the `foo` app. It becomes available as the `/api/foo` route of the micro frontend server.
 
-The single app directory may contain an `examples` subdirectory with example JSON files which can be used as props for the app entrypoint component. E.g. `/apps/foo/examples/example-1.json` becomes available as the `/api/foo/examples/example-1` route of the micro frontend server.
-
 See [nerest-harness](https://github.com/nerestjs/harness) for the minimal example of a nerest micro frontend.
 
+### Examples (`/examples/*.json`)
+
+The app directory may contain an `examples` subdirectory with example JSON files which can be used as props for the app entrypoint component. E.g. `/apps/foo/examples/example-1.json` becomes available as the `/api/foo/examples/example-1` route of the micro frontend server.
+
+### Schema (`/schema.json`)
+
+The app directory should contain a `schema.json` file that describes the schema of a request body for this specific app in the [JSON Schema language](https://json-schema.org/). All requests sent to this app, and app examples from the `examples` subdirectory will be validated against this schema. `ajv` and `ajv-formats` are used for validation, so all JSON Schema features implemented by them are supported.
+
 ## Development
 
 Run the build script to build the framework.

package/dist/server/app-parts/schema.d.ts

@@ -0,0 +1 @@
+export declare function loadAppSchema(appRoot: string): Promise<any>;

package/dist/server/app-parts/schema.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAppSchema = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("fs");
+const promises_1 = __importDefault(require("fs/promises"));
+// Loads and parses the schema file for a specific app
+async function loadAppSchema(appRoot) {
+    const schemaPath = path_1.default.join(appRoot, 'schema.json');
+    let schema = null;
+    // TODO: error handling and reporting
+    if ((0, fs_1.existsSync)(schemaPath)) {
+        const file = await promises_1.default.readFile(schemaPath, { encoding: 'utf-8' });
+        schema = JSON.parse(file);
+    }
+    return schema;
+}
+exports.loadAppSchema = loadAppSchema;

package/dist/server/apps.d.ts

@@ -1,9 +1,10 @@
-export declare type AppEntry = {
+export type AppEntry = {
     name: string;
     root: string;
     entry: string;
     assets: string[];
     examples: Record<string, unknown>;
+    schema: Record<string, unknown> | null;
 };
 export declare function loadApps(root: string): Promise<{
     [k: string]: AppEntry;

package/dist/server/apps.js

@@ -8,6 +8,7 @@ const path_1 = __importDefault(require("path"));
 const promises_1 = __importDefault(require("fs/promises"));
 const assets_1 = require("./app-parts/assets");
 const examples_1 = require("./app-parts/examples");
+const schema_1 = require("./app-parts/schema");
 // Build the record of the available apps by convention
 // apps -> /apps/{name}/index.tsx
 // examples -> /apps/{name}/examples/{example}.json
@@ -35,6 +36,7 @@ async function loadApp(appsRoot, name, manifest) {
             entry: path_1.default.join(appRoot, 'index.tsx'),
             assets: (0, assets_1.loadAppAssets)(manifest, name),
             examples: await (0, examples_1.loadAppExamples)(appRoot),
+            schema: await (0, schema_1.loadAppSchema)(appRoot),
         },
     ];
 }

package/dist/server/index.js

@@ -12,6 +12,7 @@ const static_1 = __importDefault(require("@fastify/static"));
 const apps_1 = require("./apps");
 const render_1 = require("./render");
 const preview_1 = require("./preview");
+const validator_1 = require("./validator");
 // TODO: this turned out to be a dev server, production server
 // will most likely be implemented separately
 async function createServer() {
@@ -47,10 +48,22 @@ async function createServer() {
     // Start vite server that will be rendering SSR components
     const viteSsr = await vite_1.default.createServer(config);
     const app = (0, fastify_1.default)();
+    // Setup schema validation. We have to use our own ajv instance that
+    // we can use both to validate request bodies and examples against
+    // app schemas
+    app.setValidatorCompiler(({ schema }) => validator_1.validator.compile(schema));
     for (const appEntry of Object.values(apps)) {
-        const { name, entry, examples } = appEntry;
+        const { name, entry, examples, schema } = appEntry;
+        const routeOptions = {};
+        // TODO: report error if schema is missing, unless this app is client-only.
+        // TODO: disallow apps without schemas in production build
+        if (schema) {
+            routeOptions.schema = {
+                body: schema,
+            };
+        }
         // POST /api/{name} -> render app with request.body as props
-        app.post(`/api/${name}`, async (request) => {
+        app.post(`/api/${name}`, routeOptions, async (request) => {
             // ssrLoadModule drives the "hot-reload" logic, and allows
             // picking up changes to the source without restarting the server
             const ssrComponent = await viteSsr.ssrLoadModule(entry, {
@@ -59,6 +72,11 @@ async function createServer() {
             return (0, render_1.renderApp)(appEntry, ssrComponent.default, request.body);
         });
         for (const [exampleName, example] of Object.entries(examples)) {
+            // Validate example against schema when specified
+            if (schema && !validator_1.validator.validate(schema, example)) {
+                // TODO: use logger and display errors more prominently
+                console.error(`Example "${exampleName}" of app "${name}" does not satisfy schema: ${validator_1.validator.errorsText()}`);
+            }
             // GET /api/{name}/examples/{example} -> render a preview page
             // with a predefined example body
             app.get(`/api/${name}/examples/${exampleName}`, async (_, reply) => {

package/dist/server/validator.d.ts

@@ -0,0 +1,2 @@
+import Ajv from 'ajv';
+export declare const validator: Ajv;

package/dist/server/validator.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validator = void 0;
+const ajv_1 = __importDefault(require("ajv"));
+const fast_uri_1 = __importDefault(require("fast-uri"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+exports.validator = new ajv_1.default({
+    coerceTypes: 'array',
+    useDefaults: true,
+    removeAdditional: true,
+    uriResolver: fast_uri_1.default,
+    addUsedSchema: false,
+    // Explicitly set allErrors to `false`.
+    // When set to `true`, a DoS attack is possible.
+    allErrors: false,
+});
+// Support additional type formats in JSON schema like `date`,
+// `email`, `url`, etc. Used by default in fastify
+// https://www.npmjs.com/package/ajv-formats
+(0, ajv_formats_1.default)(exports.validator);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerest/nerest",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "React micro frontend framework",
   "homepage": "https://github.com/nerestjs/nerest#readme",
   "repository": {
@@ -46,24 +46,27 @@
     ]
   },
   "dependencies": {
-    "@fastify/static": "^6.5.0",
-    "fastify": "^4.9.2",
+    "@fastify/static": "^6.9.0",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "fast-uri": "^2.2.0",
+    "fastify": "^4.13.0",
     "nanoid": "^3.3.4",
-    "vite": "^3.2.3"
+    "vite": "^4.1.4"
   },
   "devDependencies": {
-    "@tinkoff/eslint-config": "^1.41.0",
-    "@tinkoff/eslint-config-react": "^1.41.0",
-    "@tinkoff/prettier-config": "^1.32.1",
-    "@types/react": "^18.0.25",
-    "@types/react-dom": "^18.0.8",
-    "jest": "^29.3.1",
-    "lint-staged": "^13.0.3",
+    "@tinkoff/eslint-config": "^1.50.1",
+    "@tinkoff/eslint-config-react": "^1.50.2",
+    "@tinkoff/prettier-config": "^1.47.1",
+    "@types/react": "^18.0.28",
+    "@types/react-dom": "^18.0.11",
+    "jest": "^29.4.3",
+    "lint-staged": "^13.1.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "simple-git-hooks": "^2.8.1",
-    "sort-package-json": "^2.1.0",
-    "typescript": "^4.8.4"
+    "sort-package-json": "^2.4.1",
+    "typescript": "^4.9.5"
   },
   "peerDependencies": {
     "react": "^18.0.0",

package/server/app-parts/schema.ts

@@ -0,0 +1,18 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import fs from 'fs/promises';
+
+// Loads and parses the schema file for a specific app
+export async function loadAppSchema(appRoot: string) {
+  const schemaPath = path.join(appRoot, 'schema.json');
+
+  let schema = null;
+
+  // TODO: error handling and reporting
+  if (existsSync(schemaPath)) {
+    const file = await fs.readFile(schemaPath, { encoding: 'utf-8' });
+    schema = JSON.parse(file);
+  }
+
+  return schema;
+}

package/server/apps.ts

@@ -4,6 +4,7 @@ import type { Manifest } from 'vite';
 
 import { loadAppAssets } from './app-parts/assets';
 import { loadAppExamples } from './app-parts/examples';
+import { loadAppSchema } from './app-parts/schema';
 
 export type AppEntry = {
   name: string;
@@ -11,6 +12,7 @@ export type AppEntry = {
   entry: string;
   assets: string[];
   examples: Record<string, unknown>;
+  schema: Record<string, unknown> | null;
 };
 
 // Build the record of the available apps by convention
@@ -47,6 +49,7 @@ async function loadApp(
       entry: path.join(appRoot, 'index.tsx'),
       assets: loadAppAssets(manifest, name),
       examples: await loadAppExamples(appRoot),
+      schema: await loadAppSchema(appRoot),
     },
   ];
 }

package/server/index.ts

@@ -6,12 +6,14 @@ import vite from 'vite';
 import type { InlineConfig } from 'vite';
 import type { RollupWatcher, RollupWatcherEvent } from 'rollup';
 
+import type { RouteShorthandOptions } from 'fastify';
 import fastify from 'fastify';
 import fastifyStatic from '@fastify/static';
 
 import { loadApps } from './apps';
 import { renderApp } from './render';
 import { renderPreviewPage } from './preview';
+import { validator } from './validator';
 
 // TODO: this turned out to be a dev server, production server
 // will most likely be implemented separately
@@ -53,11 +55,26 @@ export async function createServer() {
   const viteSsr = await vite.createServer(config);
   const app = fastify();
 
+  // Setup schema validation. We have to use our own ajv instance that
+  // we can use both to validate request bodies and examples against
+  // app schemas
+  app.setValidatorCompiler(({ schema }) => validator.compile(schema));
+
   for (const appEntry of Object.values(apps)) {
-    const { name, entry, examples } = appEntry;
+    const { name, entry, examples, schema } = appEntry;
+
+    const routeOptions: RouteShorthandOptions = {};
+
+    // TODO: report error if schema is missing, unless this app is client-only.
+    // TODO: disallow apps without schemas in production build
+    if (schema) {
+      routeOptions.schema = {
+        body: schema,
+      };
+    }
 
     // POST /api/{name} -> render app with request.body as props
-    app.post(`/api/${name}`, async (request) => {
+    app.post(`/api/${name}`, routeOptions, async (request) => {
       // ssrLoadModule drives the "hot-reload" logic, and allows
       // picking up changes to the source without restarting the server
       const ssrComponent = await viteSsr.ssrLoadModule(entry, {
@@ -71,6 +88,14 @@ export async function createServer() {
     });
 
     for (const [exampleName, example] of Object.entries(examples)) {
+      // Validate example against schema when specified
+      if (schema && !validator.validate(schema, example)) {
+        // TODO: use logger and display errors more prominently
+        console.error(
+          `Example "${exampleName}" of app "${name}" does not satisfy schema: ${validator.errorsText()}`
+        );
+      }
+
       // GET /api/{name}/examples/{example} -> render a preview page
       // with a predefined example body
       app.get(`/api/${name}/examples/${exampleName}`, async (_, reply) => {

package/server/validator.ts

@@ -0,0 +1,19 @@
+import Ajv from 'ajv';
+import fastUri from 'fast-uri';
+import addFormats from 'ajv-formats';
+
+export const validator = new Ajv({
+  coerceTypes: 'array',
+  useDefaults: true,
+  removeAdditional: true,
+  uriResolver: fastUri,
+  addUsedSchema: false,
+  // Explicitly set allErrors to `false`.
+  // When set to `true`, a DoS attack is possible.
+  allErrors: false,
+});
+
+// Support additional type formats in JSON schema like `date`,
+// `email`, `url`, etc. Used by default in fastify
+// https://www.npmjs.com/package/ajv-formats
+addFormats(validator);