@nerest/nerest 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerest/nerest",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "React micro frontend framework",
   "homepage": "https://github.com/nerestjs/nerest#readme",
   "repository": {
@@ -13,6 +13,7 @@
   "files": [
     "/dist",
     "/bin",
+    "/build",
     "/client",
     "/server",
     "/README.md"
@@ -46,29 +47,31 @@
     ]
   },
   "dependencies": {
-    "@fastify/static": "^6.9.0",
-    "@fastify/swagger": "^8.3.1",
-    "@fastify/swagger-ui": "^1.4.0",
+    "@fastify/static": "^6.10.2",
+    "@fastify/swagger": "^8.5.1",
+    "@fastify/swagger-ui": "^1.8.1",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
+    "dotenv": "^16.1.4",
     "fast-uri": "^2.2.0",
-    "fastify": "^4.13.0",
-    "nanoid": "^3.3.4",
-    "vite": "^4.1.4"
+    "fastify": "^4.17.0",
+    "fastify-graceful-shutdown": "^3.5.1",
+    "nanoid": "^3.3.6",
+    "vite": "^4.3.9"
   },
   "devDependencies": {
-    "@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",
+    "@tinkoff/eslint-config": "^1.52.1",
+    "@tinkoff/eslint-config-react": "^1.52.1",
+    "@tinkoff/prettier-config": "^1.52.1",
+    "@types/react": "^18.2.7",
+    "@types/react-dom": "^18.2.4",
+    "jest": "^29.5.0",
+    "lint-staged": "^13.2.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "simple-git-hooks": "^2.8.1",
     "sort-package-json": "^2.4.1",
-    "typescript": "^4.9.5"
+    "typescript": "^5.0.4"
   },
   "peerDependencies": {
     "react": "^18.0.0",

package/server/{index.ts → development.ts}

@@ -1,4 +1,4 @@
-// This is the nerest server entrypoint
+// This is the nerest development server entrypoint
 import path from 'path';
 import type { ServerResponse } from 'http';
 
@@ -9,16 +9,16 @@ import type { RollupWatcher, RollupWatcherEvent } from 'rollup';
 import type { RouteShorthandOptions } from 'fastify';
 import fastify from 'fastify';
 import fastifyStatic from '@fastify/static';
+import fastifyGracefulShutdown from 'fastify-graceful-shutdown';
 
-import { loadApps } from './apps';
-import { renderApp } from './render';
-import { renderPreviewPage } from './preview';
-import { validator } from './validator';
-import { setupSwagger } from './swagger';
+import { loadApps } from './parts/apps';
+import { renderApp } from './parts/render';
+import { renderPreviewPage } from './parts/preview';
+import { validator } from './parts/validator';
+import { setupSwagger } from './parts/swagger';
+import { setupK8SProbes } from './parts/k8s-probes';
 
-// TODO: this turned out to be a dev server, production server
-// will most likely be implemented separately
-export async function createServer() {
+export async function runDevelopmentServer() {
   const root = process.cwd();
 
   // TODO: move build config into a separate file
@@ -27,6 +27,7 @@ export async function createServer() {
   const config: InlineConfig = {
     root,
     appType: 'custom',
+    envPrefix: 'NEREST_',
     server: { middlewareMode: true },
     build: {
       // Manifest is needed to report used assets in SSR handles
@@ -37,12 +38,18 @@ export async function createServer() {
       rollupOptions: {
         input: '/node_modules/@nerest/nerest/client/index.ts',
         output: {
-          entryFileNames: `assets/[name].js`,
-          chunkFileNames: `assets/[name].js`,
-          assetFileNames: `assets/[name].[ext]`,
+          dir: 'build',
+          entryFileNames: `client/assets/[name].js`,
+          chunkFileNames: `client/assets/[name].js`,
+          assetFileNames: `client/assets/[name].[ext]`,
         },
       },
     },
+    // TODO: this doesn't seem to work without the index.html file entry and
+    // produces warnings in dev mode. look into this maybe
+    optimizeDeps: {
+      disabled: true,
+    },
   };
 
   // Build the clientside assets and watch for changes
@@ -50,7 +57,8 @@ export async function createServer() {
   await startClientBuildWatcher(config);
 
   // Load app entries following the `apps/{name}/index.tsx` convention
-  const apps = await loadApps(root);
+  // TODO: remove hardcoded port
+  const apps = await loadApps(root, 'http://0.0.0.0:3000/');
 
   // Start vite server that will be rendering SSR components
   const viteSsr = await vite.createServer(config);
@@ -68,8 +76,7 @@ export async function createServer() {
 
     const routeOptions: RouteShorthandOptions = {};
 
-    // TODO: report error if schema is missing, unless this app is client-only.
-    // TODO: disallow apps without schemas in production build
+    // TODO: report error if schema is missing, unless this app is client-only
     if (schema) {
       routeOptions.schema = {
         // Use description as Swagger summary, since summary is visible
@@ -92,8 +99,11 @@ export async function createServer() {
         fixStacktrace: true,
       });
       return renderApp(
-        appEntry,
-        ssrComponent.default,
+        {
+          name,
+          assets: appEntry.assets,
+          component: ssrComponent.default,
+        },
         request.body as Record<string, unknown>
       );
     });
@@ -124,8 +134,11 @@ export async function createServer() {
             fixStacktrace: true,
           });
           const { html, assets } = renderApp(
-            appEntry,
-            ssrComponent.default,
+            {
+              name,
+              assets: appEntry.assets,
+              component: ssrComponent.default,
+            },
             example as Record<string, unknown>
           );
 
@@ -137,9 +150,16 @@ export async function createServer() {
     }
   }
 
+  // Add graceful shutdown handler to prevent requests errors
+  await app.register(fastifyGracefulShutdown);
+
+  if (process.env.ENABLE_K8S_PROBES) {
+    await setupK8SProbes(app);
+  }
+
   // TODO: only do this locally, load from CDN in production
   await app.register(fastifyStatic, {
-    root: path.join(root, 'dist'),
+    root: path.join(root, 'build'),
     // TODO: maybe use @fastify/cors instead
     setHeaders(res: ServerResponse) {
       res.setHeader('Access-Control-Allow-Origin', '*');
@@ -151,7 +171,13 @@ export async function createServer() {
     },
   });
 
-  return { app };
+  // TODO: remove hardcoded port
+  await app.listen({
+    host: '0.0.0.0',
+    port: 3000,
+  });
+
+  console.log('Nerest is listening on 0.0.0.0:3000');
 }
 
 // TODO: this should probably be moved from here

package/server/loaders/assets.ts

@@ -0,0 +1,19 @@
+import type { Manifest } from 'vite';
+
+// Extracts the list of assets for a given app from the manifest file
+export function loadAppAssets(
+  appName: string,
+  manifest: Manifest,
+  staticPath: string
+) {
+  // TODO: handling errors and potentially missing entries
+  // All apps share the same JS entry that dynamically imports the chunks of the apps
+  // that are used on the page based on their name
+  const clientEntryJs =
+    manifest['node_modules/@nerest/nerest/client/index.ts'].file;
+
+  // Each app has its own CSS bundles, if it imports any CSS
+  const appCss = manifest[`apps/${appName}/index.tsx`].css ?? [];
+
+  return [clientEntryJs, ...appCss].map((x) => staticPath + x);
+}

package/server/loaders/manifest.ts

@@ -0,0 +1,11 @@
+import path from 'path';
+import fs from 'fs/promises';
+
+// Manifest is used to provide assets list for every app
+// for use with SSR
+export async function loadAppManifest(root: string) {
+  // TODO: error handling
+  const manifestPath = path.join(root, 'build', 'manifest.json');
+  const manifestData = await fs.readFile(manifestPath, { encoding: 'utf8' });
+  return JSON.parse(manifestData);
+}

package/server/{apps.ts → parts/apps.ts}

@@ -2,9 +2,10 @@ import path from 'path';
 import fs from 'fs/promises';
 import type { Manifest } from 'vite';
 
-import { loadAppAssets } from './app-parts/assets';
-import { loadAppExamples } from './app-parts/examples';
-import { loadAppSchema } from './app-parts/schema';
+import { loadAppAssets } from '../loaders/assets';
+import { loadAppExamples } from '../loaders/examples';
+import { loadAppSchema } from '../loaders/schema';
+import { loadAppManifest } from '../loaders/manifest';
 
 export type AppEntry = {
   name: string;
@@ -18,9 +19,9 @@ export type AppEntry = {
 // Build the record of the available apps by convention
 // apps -> /apps/{name}/index.tsx
 // examples -> /apps/{name}/examples/{example}.json
-export async function loadApps(root: string) {
+export async function loadApps(root: string, deployedStaticPath: string) {
   const appsRoot = path.join(root, 'apps');
-  const manifest = await loadManifest(root);
+  const manifest = await loadAppManifest(root);
 
   const appsDirs = (await fs.readdir(appsRoot, { withFileTypes: true }))
     .filter((d) => d.isDirectory())
@@ -28,7 +29,7 @@ export async function loadApps(root: string) {
 
   const apps: Array<[name: string, entry: AppEntry]> = [];
   for (const appDir of appsDirs) {
-    apps.push(await loadApp(appsRoot, appDir, manifest));
+    apps.push(await loadApp(appsRoot, appDir, manifest, deployedStaticPath));
   }
 
   return Object.fromEntries(apps);
@@ -37,7 +38,8 @@ export async function loadApps(root: string) {
 async function loadApp(
   appsRoot: string,
   name: string,
-  manifest: Manifest
+  manifest: Manifest,
+  deployedStaticPath: string
 ): Promise<[name: string, entry: AppEntry]> {
   // TODO: report problems with loading entries, assets and/or examples
   const appRoot = path.join(appsRoot, name);
@@ -47,18 +49,9 @@ async function loadApp(
       name,
       root: appRoot,
       entry: path.join(appRoot, 'index.tsx'),
-      assets: loadAppAssets(manifest, name),
+      assets: loadAppAssets(name, manifest, deployedStaticPath),
       examples: await loadAppExamples(appRoot),
       schema: await loadAppSchema(appRoot),
     },
   ];
 }
-
-// Manifest is used to provide assets list for every app
-// for use with SSR
-async function loadManifest(root: string) {
-  // TODO: error handling
-  const manifestPath = path.join(root, 'dist', 'manifest.json');
-  const manifestData = await fs.readFile(manifestPath, { encoding: 'utf8' });
-  return JSON.parse(manifestData);
-}

package/server/parts/k8s-probes.ts

@@ -0,0 +1,30 @@
+import type { FastifyInstance } from 'fastify';
+
+// Setup routes for k8s probes to check if application is live
+export async function setupK8SProbes(app: FastifyInstance) {
+  // Handler for graceful shutdowns
+  // K8s can initiate shutdown at any moment: on pods restart or on deploy.
+  // So, if we receive shutdown request, we:
+  // - starts to send 503 response code on readiness probes to stop receiving requests
+  // - finishes all current requests
+  // - shuts down the server
+  let isShutdownInProgress = false;
+  app.gracefulShutdown((code, next) => {
+    // TODO: replace with nerest logger, when it'll be ready
+    console.log('Graceful shutdown in process...');
+    isShutdownInProgress = true;
+    next();
+  });
+
+  app.get('/livenessProbe', { logLevel: 'silent' }, (req, res) => {
+    res.status(200).send();
+  });
+
+  app.get('/readinessProbe', { logLevel: 'silent' }, (req, res) => {
+    if (isShutdownInProgress) {
+      res.status(503).send({ status: 'Shutdown in progress' });
+    } else {
+      res.status(200).send();
+    }
+  });
+}

package/server/{render.ts → parts/render.ts}

@@ -2,15 +2,17 @@ import React from 'react';
 import { renderToString } from 'react-dom/server';
 import { nanoid } from 'nanoid';
 
-import type { AppEntry } from './apps';
+type RenderProps = {
+  name: string;
+  assets: string[];
+  component: React.ComponentType;
+};
 
 export function renderApp(
-  appEntry: AppEntry,
-  appComponent: React.ComponentType,
+  { name, assets, component }: RenderProps,
   props: Record<string, unknown> = {}
 ) {
-  const { name, assets } = appEntry;
-  const html = renderSsrComponent(name, appComponent, props);
+  const html = renderSsrComponent(name, component, props);
   return { html, assets };
 }
 

package/server/production.ts

@@ -0,0 +1,115 @@
+// This is the nerest production server entrypoint
+import path from 'path';
+import fs from 'fs/promises';
+
+import fastify from 'fastify';
+import fastifyGracefulShutdown from 'fastify-graceful-shutdown';
+import type { RouteShorthandOptions } from 'fastify';
+
+import type { AppEntry } from './parts/apps';
+import { renderApp } from './parts/render';
+import { setupSwagger } from './parts/swagger';
+import { validator } from './parts/validator';
+import { renderPreviewPage } from './parts/preview';
+import { setupK8SProbes } from './parts/k8s-probes';
+
+// TODO: refactor to merge the similar parts between production and development server?
+async function runProductionServer() {
+  const root = process.cwd();
+
+  // TODO: error handling for file reading
+  const apps = JSON.parse(
+    await fs.readFile(path.join(root, 'build/nerest-manifest.json'), {
+      encoding: 'utf-8',
+    })
+  ) as Record<string, AppEntry>;
+
+  // TODO: fix client-side vite types
+  const components = import.meta.glob('/apps/*/index.tsx', {
+    import: 'default',
+    eager: true,
+  }) as Record<string, React.ComponentType>;
+
+  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, examples, schema, assets } = appEntry;
+    const component = components[`/apps/${name}/index.tsx`];
+
+    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,
+        // TODO: do we need to mix in examples like in the development server?
+        body: schema,
+      };
+    }
+
+    // POST /api/{name} -> render app with request.body as props
+    app.post(`/api/${name}`, routeOptions, (request) =>
+      renderApp(
+        { name, assets, component },
+        request.body as Record<string, unknown>
+      )
+    );
+
+    for (const [exampleName, example] of Object.entries(examples)) {
+      // 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 { html, assets: outAssets } = renderApp(
+            {
+              name,
+              assets,
+              component,
+            },
+            example as Record<string, unknown>
+          );
+
+          reply.type('text/html');
+
+          return renderPreviewPage(html, outAssets);
+        }
+      );
+    }
+  }
+
+  // Add graceful shutdown handler to prevent requests errors
+  await app.register(fastifyGracefulShutdown);
+
+  if (process.env.ENABLE_K8S_PROBES) {
+    await setupK8SProbes(app);
+  }
+
+  // TODO: remove hardcoded port
+  await app.listen({
+    host: '0.0.0.0',
+    port: 3000,
+  });
+
+  console.log('Nerest is listening on 0.0.0.0:3000');
+}
+
+runProductionServer();

package/dist/client/entry.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/client/entry.js

@@ -1,3 +0,0 @@
-const apps = import.meta.glob('/apps/*/index.tsx', { import: 'default' });
-console.log(apps);
-export {};

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

@@ -1,2 +0,0 @@
-import type { Manifest } from 'vite';
-export declare function loadAppAssets(manifest: Manifest, appName: string): string[];

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

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadAppAssets = void 0;
-// TODO: this is not as simple in the real world
-const publicPath = process.env.PUBLIC_PATH ?? 'http://0.0.0.0:3000/';
-// Extracts the list of assets for a given app from the manifest file
-function loadAppAssets(manifest, appName) {
-    const entries = Object.entries(manifest);
-    // TODO: handling errors and potentially missing entries
-    const clientEntryJs = entries.find(([_, entry]) => entry.isEntry)?.[1].file;
-    const appCss = entries.find(([name, _]) => name.includes(`/${appName}/index.tsx`))?.[1]
-        .css ?? [];
-    return [clientEntryJs, ...appCss].map((x) => publicPath + x);
-}
-exports.loadAppAssets = loadAppAssets;

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

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderPreviewPage = void 0;
-function renderPreviewPage(html, assets) {
-    const { scripts, styles } = mapAssets(assets);
-    return `
-  <html>
-  <head>
-    ${styles.join('\n')}
-  </head>
-  <body>
-    ${html}
-    ${scripts.join('\n')}
-  </body>
-  </html>
-  `;
-}
-exports.renderPreviewPage = renderPreviewPage;
-function mapAssets(assets) {
-    const scripts = assets
-        .filter((src) => src.endsWith('.js'))
-        .map((src) => `<script type="module" src="${src}"></script>`);
-    const styles = assets
-        .filter((src) => src.endsWith('.css'))
-        .map((src) => `<link rel="stylesheet" href="${src}">`);
-    return { scripts, styles };
-}

package/dist/server/assets.d.ts

@@ -1 +0,0 @@
-export declare function getAppAssets(appName: string, root: string): Promise<string[]>;

package/dist/server/assets.js

@@ -1,28 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAppAssets = void 0;
-const path_1 = __importDefault(require("path"));
-const promises_1 = __importDefault(require("fs/promises"));
-// TODO: way more complicated in the real world
-const publicPath = process.env.PUBLIC_PATH ?? 'http://127.0.0.1:3000/';
-async function getAppAssets(appName, root) {
-    const manifest = await loadManifest(root);
-    const assets = extractAssetsFromManifest(manifest, appName);
-    return assets.map((x) => publicPath + x);
-}
-exports.getAppAssets = getAppAssets;
-async function loadManifest(root) {
-    const manifestPath = path_1.default.join(root, 'dist', 'manifest.json');
-    const manifestData = await promises_1.default.readFile(manifestPath, { encoding: 'utf8' });
-    return JSON.parse(manifestData);
-}
-function extractAssetsFromManifest(manifest, appName) {
-    const entries = Object.entries(manifest);
-    const clientEntryJs = entries.find(([_, entry]) => entry.isEntry)?.[1].file;
-    const appCss = entries.find(([name, _]) => name.includes(`/${appName}/index.tsx`))?.[1]
-        .css ?? [];
-    return [clientEntryJs, ...appCss];
-}

package/dist/server/entry.d.ts

@@ -1,2 +0,0 @@
-import React from 'react';
-export declare function renderSsrComponent(appName: string, AppComponent: React.ComponentType, props?: Record<string, unknown>): string;

package/dist/server/entry.js

@@ -1,17 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderSsrComponent = void 0;
-const react_1 = __importDefault(require("react"));
-const server_1 = require("react-dom/server");
-const nanoid_1 = require("nanoid");
-function renderSsrComponent(appName, AppComponent, props = {}) {
-    const html = (0, server_1.renderToString)(react_1.default.createElement(AppComponent, { ...props }));
-    const appId = (0, nanoid_1.nanoid)();
-    const container = `<div data-app-name="${appName}" data-app-id="${appId}">${html}</div>`;
-    const script = `<script type="application/json" data-app-id="${appId}">${JSON.stringify(props)}</script>`;
-    return container + script;
-}
-exports.renderSsrComponent = renderSsrComponent;

package/dist/server/index.d.ts

@@ -1,5 +0,0 @@
-/// <reference types="node" />
-import type { ServerResponse } from 'http';
-export declare function createServer(): Promise<{
-    app: import("fastify").FastifyInstance<import("http").Server<typeof import("http").IncomingMessage, typeof ServerResponse>, import("http").IncomingMessage, ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault> & PromiseLike<import("fastify").FastifyInstance<import("http").Server<typeof import("http").IncomingMessage, typeof ServerResponse>, import("http").IncomingMessage, ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>>;
-}>;

package/dist/server/preview.d.ts

@@ -1 +0,0 @@
-export declare function renderPreviewPage(html: string, assets: string[]): string;

package/dist/server/render.d.ts

@@ -1,6 +0,0 @@
-import React from 'react';
-import type { AppEntry } from './apps';
-export declare function renderApp(appEntry: AppEntry, appComponent: React.ComponentType, props?: Record<string, unknown>): {
-    html: string;
-    assets: string[];
-};

package/server/app-parts/assets.ts

@@ -1,17 +0,0 @@
-import type { Manifest } from 'vite';
-
-// TODO: this is not as simple in the real world
-const publicPath = process.env.PUBLIC_PATH ?? 'http://0.0.0.0:3000/';
-
-// Extracts the list of assets for a given app from the manifest file
-export function loadAppAssets(manifest: Manifest, appName: string) {
-  const entries = Object.entries(manifest);
-
-  // TODO: handling errors and potentially missing entries
-  const clientEntryJs = entries.find(([_, entry]) => entry.isEntry)?.[1].file;
-  const appCss =
-    entries.find(([name, _]) => name.includes(`/${appName}/index.tsx`))?.[1]
-      .css ?? [];
-
-  return [clientEntryJs, ...appCss].map((x) => publicPath + x);
-}