@nerest/nerest 0.0.1 → 0.0.3

package/README.md

@@ -10,14 +10,28 @@ 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.
+
+OpenAPI specification is compiled automatically based on the provided schemas and becomes available at `/api/json`. It can also be explored through Swagger UI that becomes available at `/api`.
+
 ## 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,8 @@ 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");
+const swagger_1 = require("./swagger");
 // TODO: this turned out to be a dev server, production server
 // will most likely be implemented separately
 async function createServer() {
@@ -47,10 +49,31 @@ 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));
+    await (0, swagger_1.setupSwagger)(app);
     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 = {
+                // Use description as Swagger summary, since summary is visible
+                // even when the route is collapsed in the UI
+                summary: schema.description,
+                body: {
+                    ...schema,
+                    // Mix examples into the schema so they become accessible
+                    // in the Swagger UI
+                    examples: Object.values(examples),
+                },
+            };
+        }
         // 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,9 +82,21 @@ 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) => {
+            const exampleRoute = `/api/${name}/examples/${exampleName}`;
+            app.get(exampleRoute, {
+                schema: {
+                    // Add a clickable link to the example route in route's Swagger
+                    // description so it's easier to navigate to
+                    description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
+                },
+            }, async (_, reply) => {
                 const ssrComponent = await viteSsr.ssrLoadModule(entry, {
                     fixStacktrace: true,
                 });
@@ -72,7 +107,7 @@ async function createServer() {
         }
     }
     // TODO: only do this locally, load from CDN in production
-    app.register(static_1.default, {
+    await app.register(static_1.default, {
         root: path_1.default.join(root, 'dist'),
         // TODO: maybe use @fastify/cors instead
         setHeaders(res) {

package/dist/server/swagger.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyInstance } from 'fastify';
+export declare function setupSwagger(app: FastifyInstance): Promise<void>;

package/dist/server/swagger.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupSwagger = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const swagger_1 = __importDefault(require("@fastify/swagger"));
+const swagger_ui_1 = __importDefault(require("@fastify/swagger-ui"));
+// Setup automatic OpenAPI specification compilation and enable
+// Swagger UI at the `/api` route
+async function setupSwagger(app) {
+    let appInfo = {};
+    try {
+        const packageJson = fs_1.default.readFileSync(path_1.default.join(process.cwd(), 'package.json'), { encoding: 'utf-8' });
+        appInfo = JSON.parse(packageJson);
+    }
+    catch (e) {
+        // We only use package.json info to setup Swagger info and links,
+        // if we are unable to load them -- that's fine
+    }
+    const homepage = appInfo.homepage ||
+        (typeof appInfo.repository === 'string'
+            ? appInfo.repository
+            : appInfo.repository?.url);
+    await app.register(swagger_1.default, {
+        openapi: {
+            info: {
+                title: appInfo.name ?? 'Nerest micro frontend',
+                description: appInfo.description,
+                version: appInfo.version ?? '',
+                contact: homepage
+                    ? {
+                        name: 'Homepage',
+                        url: homepage,
+                    }
+                    : undefined,
+            },
+            externalDocs: {
+                url: 'https://github.com/nerestjs/nerest',
+                description: 'Built with Nerest',
+            },
+        },
+    });
+    await app.register(swagger_ui_1.default, {
+        routePrefix: '/api',
+    });
+}
+exports.setupSwagger = setupSwagger;

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.3",
   "description": "React micro frontend framework",
   "homepage": "https://github.com/nerestjs/nerest#readme",
   "repository": {
@@ -46,24 +46,29 @@
     ]
   },
   "dependencies": {
-    "@fastify/static": "^6.5.0",
-    "fastify": "^4.9.2",
+    "@fastify/static": "^6.9.0",
+    "@fastify/swagger": "^8.3.1",
+    "@fastify/swagger-ui": "^1.4.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,15 @@ 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';
+import { setupSwagger } from './swagger';
 
 // TODO: this turned out to be a dev server, production server
 // will most likely be implemented separately
@@ -53,11 +56,36 @@ 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));
+
+  await setupSwagger(app);
+
   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 = {
+        // Use description as Swagger summary, since summary is visible
+        // even when the route is collapsed in the UI
+        summary: schema.description as string,
+        body: {
+          ...schema,
+          // Mix examples into the schema so they become accessible
+          // in the Swagger UI
+          examples: Object.values(examples),
+        },
+      };
+    }
 
     // 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,27 +99,46 @@ export async function createServer() {
     });
 
     for (const [exampleName, example] of Object.entries(examples)) {
-      // GET /api/{name}/examples/{example} -> render a preview page
-      // with a predefined example body
-      app.get(`/api/${name}/examples/${exampleName}`, async (_, reply) => {
-        const ssrComponent = await viteSsr.ssrLoadModule(entry, {
-          fixStacktrace: true,
-        });
-        const { html, assets } = renderApp(
-          appEntry,
-          ssrComponent.default,
-          example as Record<string, unknown>
+      // 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()}`
         );
+      }
 
-        reply.type('text/html');
-
-        return renderPreviewPage(html, assets);
-      });
+      // GET /api/{name}/examples/{example} -> render a preview page
+      // with a predefined example body
+      const exampleRoute = `/api/${name}/examples/${exampleName}`;
+      app.get(
+        exampleRoute,
+        {
+          schema: {
+            // Add a clickable link to the example route in route's Swagger
+            // description so it's easier to navigate to
+            description: `Open sandbox: [${exampleRoute}](${exampleRoute})`,
+          },
+        },
+        async (_, reply) => {
+          const ssrComponent = await viteSsr.ssrLoadModule(entry, {
+            fixStacktrace: true,
+          });
+          const { html, assets } = renderApp(
+            appEntry,
+            ssrComponent.default,
+            example as Record<string, unknown>
+          );
+
+          reply.type('text/html');
+
+          return renderPreviewPage(html, assets);
+        }
+      );
     }
   }
 
   // TODO: only do this locally, load from CDN in production
-  app.register(fastifyStatic, {
+  await app.register(fastifyStatic, {
     root: path.join(root, 'dist'),
     // TODO: maybe use @fastify/cors instead
     setHeaders(res: ServerResponse) {

package/server/swagger.ts

@@ -0,0 +1,58 @@
+import path from 'path';
+import fs from 'fs';
+import type { FastifyInstance } from 'fastify';
+import fastifySwagger from '@fastify/swagger';
+import fastifySwaggerUi from '@fastify/swagger-ui';
+
+// Setup automatic OpenAPI specification compilation and enable
+// Swagger UI at the `/api` route
+export async function setupSwagger(app: FastifyInstance) {
+  let appInfo: {
+    name?: string;
+    description?: string;
+    version?: string;
+    homepage?: string;
+    repository?: string | { url?: string };
+  } = {};
+
+  try {
+    const packageJson = fs.readFileSync(
+      path.join(process.cwd(), 'package.json'),
+      { encoding: 'utf-8' }
+    );
+    appInfo = JSON.parse(packageJson);
+  } catch (e) {
+    // We only use package.json info to setup Swagger info and links,
+    // if we are unable to load them -- that's fine
+  }
+
+  const homepage =
+    appInfo.homepage ||
+    (typeof appInfo.repository === 'string'
+      ? appInfo.repository
+      : appInfo.repository?.url);
+
+  await app.register(fastifySwagger, {
+    openapi: {
+      info: {
+        title: appInfo.name ?? 'Nerest micro frontend',
+        description: appInfo.description,
+        version: appInfo.version ?? '',
+        contact: homepage
+          ? {
+              name: 'Homepage',
+              url: homepage,
+            }
+          : undefined,
+      },
+      externalDocs: {
+        url: 'https://github.com/nerestjs/nerest',
+        description: 'Built with Nerest',
+      },
+    },
+  });
+
+  await app.register(fastifySwaggerUi, {
+    routePrefix: '/api',
+  });
+}

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);