@redocly/cli 1.0.0-beta.96

package/src/commands/preview-docs/index.ts

@@ -0,0 +1,188 @@
+import * as colorette from 'colorette';
+import * as chockidar from 'chokidar';
+import {
+  bundle,
+  loadConfig,
+  ResolveError,
+  YamlParseError,
+  RedoclyClient,
+  getTotals,
+  getMergedConfig,
+} from '@redocly/openapi-core';
+import { getFallbackEntryPointsOrExit } from '../../utils';
+import startPreviewServer from './preview-server/preview-server';
+
+export async function previewDocs(argv: {
+  port: number;
+  host: string;
+  'use-community-edition'?: boolean;
+  config?: string;
+  entrypoint?: string;
+  'skip-rule'?: string[];
+  'skip-decorator'?: string[];
+  'skip-preprocessor'?: string[];
+  force?: boolean;
+}) {
+  let isAuthorizedWithRedocly: boolean = false;
+  let redocOptions: any = {};
+  let config = await reloadConfig();
+
+  const entrypoints = await getFallbackEntryPointsOrExit(
+    argv.entrypoint ? [argv.entrypoint] : [],
+    config,
+  );
+  const entrypoint = entrypoints[0];
+
+  let cachedBundle: any;
+  const deps = new Set<string>();
+
+  async function getBundle() {
+    return cachedBundle;
+  }
+
+  async function updateBundle() {
+    process.stdout.write('\nBundling...\n\n');
+    try {
+      const {
+        bundle: openapiBundle,
+        problems,
+        fileDependencies,
+      } = await bundle({
+        ref: entrypoint.path,
+        config,
+      });
+      const removed = [...deps].filter((x) => !fileDependencies.has(x));
+      watcher.unwatch(removed);
+      watcher.add([...fileDependencies]);
+      deps.clear();
+      fileDependencies.forEach(deps.add, deps);
+
+      const fileTotals = getTotals(problems);
+
+      if (fileTotals.errors === 0) {
+        process.stdout.write(
+          fileTotals.errors === 0
+            ? `Created a bundle for ${entrypoint.alias || entrypoint.path} ${
+                fileTotals.warnings > 0 ? 'with warnings' : 'successfully'
+              }\n`
+            : colorette.yellow(
+                `Created a bundle for ${
+                  entrypoint.alias || entrypoint.path
+                } with errors. Docs may be broken or not accurate\n`,
+              ),
+        );
+      }
+
+      return openapiBundle.parsed;
+    } catch (e) {
+      handleError(e, entrypoint.path);
+    }
+  }
+
+  setImmediate(() => {
+    cachedBundle = updateBundle();
+  }); // initial cache
+
+  const isAuthorized = isAuthorizedWithRedocly || redocOptions.licenseKey;
+  if (!isAuthorized) {
+    process.stderr.write(
+      `Using Redoc community edition.\nLogin with redocly ${colorette.blue(
+        'login',
+      )} or use an enterprise license key to preview with the premium docs.\n\n`,
+    );
+  }
+
+  const hotClients = await startPreviewServer(argv.port, argv.host, {
+    getBundle,
+    getOptions: () => redocOptions,
+    useRedocPro: isAuthorized && !redocOptions.useCommunityEdition,
+  });
+
+  const watchPaths = [entrypoint.path, config.configFile!].filter((e) => !!e);
+  const watcher = chockidar.watch(watchPaths, {
+    disableGlobbing: true,
+    ignoreInitial: true,
+  });
+
+  const debouncedUpdatedBundle = debounce(async () => {
+    cachedBundle = updateBundle();
+    await cachedBundle;
+    hotClients.broadcast('{"type": "reload", "bundle": true}');
+  }, 2000);
+
+  const changeHandler = async (type: string, file: string) => {
+    process.stdout.write(`${colorette.green('watch')} ${type} ${colorette.blue(file)}\n`);
+    if (file === config.configFile) {
+      config = await reloadConfig();
+      hotClients.broadcast(JSON.stringify({ type: 'reload' }));
+      return;
+    }
+
+    debouncedUpdatedBundle();
+  };
+
+  watcher.on('change', changeHandler.bind(undefined, 'changed'));
+  watcher.on('add', changeHandler.bind(undefined, 'added'));
+  watcher.on('unlink', changeHandler.bind(undefined, 'removed'));
+
+  watcher.on('ready', () => {
+    process.stdout.write(
+      `\n  👀  Watching ${colorette.blue(
+        entrypoint.path,
+      )} and all related resources for changes\n\n`,
+    );
+  });
+
+  async function reloadConfig() {
+    let config = await loadConfig(argv.config);
+    const redoclyClient = new RedoclyClient();
+    isAuthorizedWithRedocly = await redoclyClient.isAuthorizedWithRedocly();
+    const resolvedConfig = getMergedConfig(config, argv.entrypoint);
+    resolvedConfig.lint.skipRules(argv['skip-rule']);
+    resolvedConfig.lint.skipPreprocessors(argv['skip-preprocessor']);
+    resolvedConfig.lint.skipDecorators(argv['skip-decorator']);
+    const referenceDocs = resolvedConfig['features.openapi'];
+    redocOptions = {
+      ...referenceDocs,
+      useCommunityEdition: argv['use-community-edition'] || referenceDocs.useCommunityEdition,
+      licenseKey: process.env.REDOCLY_LICENSE_KEY || referenceDocs.licenseKey,
+    };
+    return resolvedConfig;
+  }
+}
+
+export function debounce(func: Function, wait: number, immediate?: boolean) {
+  let timeout: NodeJS.Timeout | null;
+
+  return function executedFunction(...args: any[]) {
+    // @ts-ignore
+    const context = this;
+
+    const later = () => {
+      timeout = null;
+      if (!immediate) func.apply(context, args);
+    };
+
+    const callNow = immediate && !timeout;
+
+    if (timeout) clearTimeout(timeout);
+
+    timeout = setTimeout(later, wait);
+
+    if (callNow) func.apply(context, args);
+  };
+}
+
+function handleError(e: Error, ref: string) {
+  if (e instanceof ResolveError) {
+    process.stderr.write(
+      `Failed to resolve entrypoint definition at ${ref}:\n\n  - ${e.message}.\n\n`,
+    );
+  } else if (e instanceof YamlParseError) {
+    process.stderr.write(
+      `Failed to parse entrypoint definition at ${ref}:\n\n  - ${e.message}.\n\n`,
+    );
+  } else {
+    process.stderr.write(`Something went wrong when processing ${ref}:\n\n  - ${e.message}.\n\n`);
+  }
+}

package/src/commands/preview-docs/preview-server/default.hbs

@@ -0,0 +1,24 @@
+
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf8" />
+  <title>{{title}}</title>
+  <!-- needed for adaptive design -->
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body {
+      padding: 0;
+      margin: 0;
+    }
+  </style>
+  {{{redocHead}}}
+  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+</head>
+
+<body>
+  {{{redocHTML}}}
+</body>
+
+</html>

package/src/commands/preview-docs/preview-server/hot.js

@@ -0,0 +1,42 @@
+(function run() {
+  const Socket = window.SimpleWebsocket;
+  const port = window.__OPENAPI_CLI_WS_PORT;
+
+  let socket;
+
+  reconnect();
+
+  function reconnect() {
+    socket = new Socket(`ws://127.0.0.1:${port}`);
+    socket.on('connect', () => {
+      socket.send('{"type": "ping"}');
+    });
+
+    socket.on('data', (data) => {
+      const message = JSON.parse(data);
+      switch (message.type) {
+        case 'pong':
+          console.log('[hot] hot reloading connected');
+          break;
+        case 'reload':
+          console.log('[hot] full page reload');
+          window.location.reload();
+          break;
+        default:
+          console.log(`[hot] ${message.type} received`);
+      }
+    });
+
+    socket.on('close', () => {
+      socket.destroy();
+      console.log('Connection lost, trying to reconnect in 4s');
+      setTimeout(() => {
+        reconnect();
+      }, 4000);
+    });
+
+    socket.on('error', () => {
+      socket.destroy();
+    });
+  }
+})();

package/src/commands/preview-docs/preview-server/oauth2-redirect.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no" />
+    <title>Redocly Reference Docs: OAuth2 Redirect</title>
+    <style>
+      .user-info {
+        margin: 150px auto auto;
+        width: 50%;
+        background-color: whitesmoke;
+        padding: 20px;
+        text-align: center;
+      }
+    </style>
+  </head>
+  <body>
+    <script src="https://cdn.jsdelivr.net/npm/@redocly/reference-docs@latest/dist/oauth2-redirect.js"></script>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+  </body>
+</html>

package/src/commands/preview-docs/preview-server/preview-server.ts

@@ -0,0 +1,150 @@
+import { compile } from 'handlebars';
+import * as colorette from 'colorette';
+import * as portfinder from 'portfinder';
+import { readFileSync, promises as fsPromises } from 'fs';
+import * as path from 'path';
+
+import { startHttpServer, startWsServer, respondWithGzip, mimeTypes } from './server';
+import type { IncomingMessage } from 'http';
+import { isSubdir } from '../../../utils';
+
+function getPageHTML(
+  htmlTemplate: string,
+  redocOptions: object = {},
+  useRedocPro: boolean,
+  wsPort: number,
+) {
+  let templateSrc = readFileSync(htmlTemplate, 'utf-8');
+
+  // fix template for backward compatibility
+  templateSrc = templateSrc
+    .replace(/{?{{redocHead}}}?/, '{{{redocHead}}}')
+    .replace('{{redocBody}}', '{{{redocHTML}}}');
+
+  const template = compile(templateSrc);
+
+  return template({
+    redocHead: `
+  <script>
+    window.__REDOC_EXPORT = '${useRedocPro ? 'RedoclyReferenceDocs' : 'Redoc'}';
+    window.__OPENAPI_CLI_WS_PORT = ${wsPort};
+  </script>
+  <script src="/simplewebsocket.min.js"></script>
+  <script src="/hot.js"></script>
+  <script src="${
+    useRedocPro
+      ? 'https://cdn.jsdelivr.net/npm/@redocly/reference-docs@latest/dist/redocly-reference-docs.min.js'
+      : 'https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js'
+  }"></script>
+`,
+    redocHTML: `
+  <div id="redoc"></div>
+  <script>
+    var container = document.getElementById('redoc');
+    ${
+      useRedocPro
+        ? "window[window.__REDOC_EXPORT].setPublicPath('https://cdn.jsdelivr.net/npm/@redocly/reference-docs@latest/dist/');"
+        : ''
+    }
+    window[window.__REDOC_EXPORT].init("/openapi.json", ${JSON.stringify(redocOptions)}, container)
+  </script>`,
+  });
+}
+
+export default async function startPreviewServer(
+  port: number,
+  host: string,
+  {
+    getBundle,
+    getOptions,
+    useRedocPro,
+  }: { getBundle: Function; getOptions: Function; useRedocPro: boolean },
+) {
+  const defaultTemplate = path.join(__dirname, 'default.hbs');
+  const handler = async (request: IncomingMessage, response: any) => {
+    console.time(colorette.dim(`GET ${request.url}`));
+    const { htmlTemplate } = getOptions() || {};
+
+    if (request.url?.endsWith('/') || path.extname(request.url!) === '') {
+      respondWithGzip(
+        getPageHTML(htmlTemplate || defaultTemplate, getOptions(), useRedocPro, wsPort),
+        request,
+        response,
+        {
+          'Content-Type': 'text/html',
+        },
+      );
+    } else if (request.url === '/openapi.json') {
+      const bundle = await getBundle();
+      if (bundle === undefined) {
+        respondWithGzip(
+          JSON.stringify({
+            openapi: '3.0.0',
+            info: {
+              description:
+                '<code> Failed to generate bundle: check out console output for more details </code>',
+            },
+            paths: {},
+          }),
+          request,
+          response,
+          {
+            'Content-Type': 'application/json',
+          },
+        );
+      } else {
+        respondWithGzip(JSON.stringify(bundle), request, response, {
+          'Content-Type': 'application/json',
+        });
+      }
+    } else {
+      const filePath =
+        // @ts-ignore
+        {
+          '/hot.js': path.join(__dirname, 'hot.js'),
+          '/oauth2-redirect.html': path.join(__dirname, 'oauth2-redirect.html'),
+          '/simplewebsocket.min.js': require.resolve('simple-websocket/simplewebsocket.min.js'),
+        }[request.url || ''] ||
+        path.resolve(htmlTemplate ? path.dirname(htmlTemplate) : process.cwd(), `.${request.url}`);
+
+      if (!isSubdir(process.cwd(), filePath)) {
+        respondWithGzip('404 Not Found', request, response, { 'Content-Type': 'text/html' }, 404);
+        console.timeEnd(colorette.dim(`GET ${request.url}`));
+        return;
+      }
+
+      const extname = String(path.extname(filePath)).toLowerCase() as keyof typeof mimeTypes;
+
+      const contentType = mimeTypes[extname] || 'application/octet-stream';
+      try {
+        respondWithGzip(await fsPromises.readFile(filePath), request, response, {
+          'Content-Type': contentType,
+        });
+      } catch (e) {
+        if (e.code === 'ENOENT') {
+          respondWithGzip('404 Not Found', request, response, { 'Content-Type': 'text/html' }, 404);
+        } else {
+          respondWithGzip(
+            `Something went wrong: ${e.code || e.message}...\n`,
+            request,
+            response,
+            {},
+            500,
+          );
+        }
+      }
+    }
+    console.timeEnd(colorette.dim(`GET ${request.url}`));
+  };
+
+  let wsPort = await portfinder.getPortPromise({ port: 32201 });
+
+  const server = startHttpServer(port, host, handler);
+  server.on('listening', () => {
+    process.stdout.write(
+      `\n  🔎  Preview server running at ${colorette.blue(`http://${host}:${port}\n`)}`,
+    );
+  });
+
+  return startWsServer(wsPort);
+}

package/src/commands/preview-docs/preview-server/server.ts

@@ -0,0 +1,91 @@
+import * as http from 'http';
+import * as zlib from 'zlib';
+import { ReadStream } from 'fs';
+
+const SocketServer = require('simple-websocket/server.js');
+
+export const mimeTypes = {
+  '.html': 'text/html',
+  '.js': 'text/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.wav': 'audio/wav',
+  '.mp4': 'video/mp4',
+  '.woff': 'application/font-woff',
+  '.ttf': 'application/font-ttf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.otf': 'application/font-otf',
+  '.wasm': 'application/wasm',
+};
+
+// credits: https://stackoverflow.com/a/9238214/1749888
+export function respondWithGzip(
+  contents: string | Buffer | ReadStream,
+  request: http.IncomingMessage,
+  response: http.ServerResponse,
+  headers = {},
+  code = 200,
+) {
+  let compressedStream;
+  const acceptEncoding = (request.headers['accept-encoding'] as string) || '';
+  if (acceptEncoding.match(/\bdeflate\b/)) {
+    response.writeHead(code, { ...headers, 'content-encoding': 'deflate' });
+    compressedStream = zlib.createDeflate();
+  } else if (acceptEncoding.match(/\bgzip\b/)) {
+    response.writeHead(code, { ...headers, 'content-encoding': 'gzip' });
+    compressedStream = zlib.createGzip();
+  } else {
+    response.writeHead(code, headers);
+    if (typeof contents === 'string' || Buffer.isBuffer(contents)) {
+      response.write(contents);
+      response.end();
+    } else if (response !== undefined) {
+      contents.pipe(response);
+    }
+    return;
+  }
+
+  if (typeof contents === 'string' || Buffer.isBuffer(contents)) {
+    compressedStream.write(contents);
+    compressedStream.pipe(response);
+    compressedStream.end();
+  } else {
+    contents.pipe(compressedStream).pipe(response);
+  }
+}
+
+export function startHttpServer(port: number, host: string, handler: http.RequestListener) {
+  return http.createServer(handler).listen(port, host);
+}
+
+export function startWsServer(port: number) {
+  const socketServer = new SocketServer({ port, clientTracking: true });
+
+  socketServer.on('connection', (socket: any) => {
+    socket.on('data', (data: string) => {
+      const message = JSON.parse(data);
+      switch (message.type) {
+        case 'ping':
+          socket.send('{"type": "pong"}');
+          break;
+        default:
+        // nope
+      }
+    });
+  });
+
+  socketServer.broadcast = (message: string) => {
+    socketServer._server.clients.forEach((client: any) => {
+      if (client.readyState === 1) {
+        // OPEN
+        client.send(message);
+      }
+    });
+  };
+
+  return socketServer;
+}