@bigcommerce/stencil-cli 10.0.0 → 10.1.1

package/README.md

@@ -47,6 +47,18 @@ Run with `-o` or `--open` to automatically open up a browser.
 -   While stencil is running, you can type "rs" and then hit enter to auto-reload all browsers. This is similar to
     Nodemon's rs option.
 
+#### Makeswift preview
+
+If Makeswift is enabled for the storefront, `stencil start` opens a Cloudflare quick tunnel with
+[cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).
+If `cloudflared` is not on your PATH (or is too old), Stencil CLI asks if it can download a pinned, checksum-verified
+release. If you agree, it caches the release in `<cache dir>/stencil-cli/cloudflared/<version>/`. If you decline, or
+the terminal is not interactive, `stencil start` continues without Makeswift preview. The cache dir is `~/Library/Caches` on
+macOS, `%LOCALAPPDATA%` on Windows, and `$XDG_CACHE_HOME` or `~/.cache` on other systems.
+
+To use your own binary and turn off the download (for example, offline), set `STENCIL_CLOUDFLARED_PATH` to the path
+of `cloudflared`.
+
 Run `stencil bundle` to validate your code and create a zip bundle file that can be uploaded to BigCommerce.
 
 Run `stencil release` to tag a new version of your theme, create a [GitHub release](https://help.github.com/articles/about-releases/)

package/lib/MakeswiftPreview.js

@@ -0,0 +1,253 @@
+import 'colors';
+import makeswiftProxyHealthModule from './makeswift-proxy-health.js';
+import tunnelManagerModule from './TunnelManager.js';
+import previewSessionClientModule from './PreviewSessionClient.js';
+import PreviewSessionHeartbeat from './PreviewSessionHeartbeat.js';
+import { createPreviewProxy } from './preview-proxy.js';
+import { createStorefrontLinkRewriteRule } from './storefront-link-rewrite.js';
+
+const PREVIEW_LISTEN_HOST = 'localhost';
+// Ctrl-C must not be slow. A session that is not revoked expires with its TTL.
+const SHUTDOWN_TIMEOUT_MS = 3000;
+
+/**
+ * Makeswift preview for `stencil start`: the tunnel, the preview session and its heartbeat,
+ * the signing front door, and the cleanup on exit.
+ */
+class MakeswiftPreview {
+    constructor({
+        makeswiftProxyHealth = makeswiftProxyHealthModule,
+        tunnelManager = tunnelManagerModule,
+        previewSessionClient = previewSessionClientModule,
+        previewProxyFactory = createPreviewProxy,
+        previewSessionHeartbeatFactory = (options) => new PreviewSessionHeartbeat(options),
+        processObj = process,
+        logger = console,
+        shutdownTimeout = SHUTDOWN_TIMEOUT_MS,
+    } = {}) {
+        this._makeswiftProxyHealth = makeswiftProxyHealth;
+        this._tunnelManager = tunnelManager;
+        this._previewSessionClient = previewSessionClient;
+        this._previewProxyFactory = previewProxyFactory;
+        this._previewSessionHeartbeatFactory = previewSessionHeartbeatFactory;
+        this._process = processObj;
+        this._logger = logger;
+        this._shutdownTimeout = shutdownTimeout;
+        this._tunnel = null;
+        this._session = null;
+        this._accessToken = null;
+        this._heartbeat = null;
+        this._shutdownPromise = null;
+    }
+
+    /**
+     * The registered preview session, or null when preview is off.
+     *
+     * @returns {{ storeUrl: string, tunnelUrl: string, secret: string, sessionId: string, accessKey: string, expiresIn: number } | null}
+     */
+    get session() {
+        return this._session;
+    }
+
+    /**
+     * Preview mode turns on when the storefront host is routed through the Makeswift proxy.
+     * A failed check never stops `stencil start`; it only turns preview mode off.
+     *
+     * @param {object} options
+     * @param {string} options.storeUrl
+     * @param {boolean | string} [options.tunnel] - the `--tunnel` CLI option
+     * @returns {Promise<boolean>}
+     */
+    async isEnabled({ storeUrl, tunnel }) {
+        const enabled = await this._makeswiftProxyHealth.isMakeswiftProxyActive({ storeUrl });
+        if (enabled && tunnel) {
+            this._logger.log(
+                `${'Notice'.yellow}: Makeswift preview is off because --tunnel is set. ` +
+                    'Remove --tunnel to use Makeswift preview.',
+            );
+            return false;
+        }
+        return enabled;
+    }
+
+    /**
+     * Starts the Cloudflare tunnel to the renderer port (not the local front door) and registers
+     * the preview session. If either fails, `stencil start` continues without Makeswift preview.
+     * Call it before the renderer starts, so the renderer requires the secret only when a
+     * session exists.
+     *
+     * @param {object} options
+     * @param {number} options.localPort - BrowserSync port, the local front door
+     * @param {number} options.rendererPort
+     * @param {string} options.storeUrl
+     * @param {string} [options.accessToken]
+     * @throws {Error} when there is no access token
+     */
+    async start({ localPort, rendererPort, storeUrl, accessToken }) {
+        if (!accessToken) {
+            throw new Error(
+                'Makeswift preview requires an access token. Add accessToken to your .stencil file.'.red,
+            );
+        }
+        this._logger.log('Makeswift is enabled for this storefront. Starting Makeswift preview...');
+        try {
+            this._tunnel = await this._tunnelManager.start(rendererPort);
+        } catch (err) {
+            this._warnUnavailable(err);
+            return;
+        }
+        this._registerShutdownHandlers();
+        const secret = this._previewSessionClient.createSecret();
+        try {
+            const tunnelUrl = this._tunnel.url;
+            const registration = await this._previewSessionClient.register({
+                storeUrl,
+                accessToken,
+                tunnelUrl,
+                secret,
+            });
+            this._session = { storeUrl, tunnelUrl, secret, ...registration };
+            this._accessToken = accessToken;
+        } catch (err) {
+            await this.stop();
+            this._warnUnavailable(err);
+            return;
+        }
+        this._heartbeat = this._previewSessionHeartbeatFactory({
+            client: this._previewSessionClient,
+            session: this._session,
+            accessToken,
+            logger: this._logger,
+        });
+        this._heartbeat.start();
+        // Watch only after the session exists, so an exit during registration also revokes it.
+        this._watchTunnel(this._tunnel);
+        const localUrl = `http://${PREVIEW_LISTEN_HOST}:${localPort}`;
+        this._logger.log(
+            `Makeswift preview is active. Open ${localUrl.cyan}\n` +
+                'The Makeswift preview session ends when you stop stencil start.',
+        );
+    }
+
+    /**
+     * The local front door proxies to the storefront (not the renderer) and signs each request.
+     * The worker sends the request back to the renderer through the tunnel. It listens on
+     * localhost (a loopback address) only, so other devices cannot send signed requests.
+     *
+     * @param {number} localPort - BrowserSync port, the local front door
+     * @returns {object} BrowserSync options
+     */
+    getBrowserSyncOptions(localPort) {
+        return {
+            listen: PREVIEW_LISTEN_HOST,
+            // No static files. BrowserSync's own routes and HTML snippet injection still run
+            // first; the proxy middleware handles all other requests.
+            server: { baseDir: [] },
+            middleware: [
+                this._previewProxyFactory({
+                    previewSession: this._session,
+                    localPort,
+                    logger: this._logger,
+                }),
+            ],
+            rewriteRules: [createStorefrontLinkRewriteRule(this._session.storeUrl)],
+            tunnel: false,
+        };
+    }
+
+    /**
+     * Stops the heartbeat and the tunnel, and revokes the session. Safe to call more than once.
+     * It does not fail and it takes at most the shutdown timeout. A failed revoke is not shown:
+     * the session expires with its TTL.
+     *
+     * @returns {Promise<void>}
+     */
+    shutdown() {
+        this._shutdownPromise ??= this._shutdown();
+        return this._shutdownPromise;
+    }
+
+    /**
+     * Stops the heartbeat and the tunnel. It does not revoke the session.
+     *
+     * @returns {Promise<void>}
+     */
+    stop() {
+        this._heartbeat?.stop();
+        this._heartbeat = null;
+        const tunnel = this._tunnel;
+        this._tunnel = null;
+        return tunnel ? tunnel.stop() : Promise.resolve();
+    }
+
+    async _shutdown() {
+        const session = this._session;
+        const accessToken = this._accessToken;
+        this._accessToken = null;
+        // Stop the heartbeat first, so it cannot change or renew the session that is revoked.
+        const stopped = this.stop();
+        const revoked = session
+            ? this._previewSessionClient.revoke({
+                  storeUrl: session.storeUrl,
+                  accessToken,
+                  sessionId: session.sessionId,
+              })
+            : undefined;
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(resolve, this._shutdownTimeout);
+            timer.unref();
+        });
+        await Promise.race([Promise.allSettled([stopped, revoked]), timedOut]);
+        clearTimeout(timer);
+    }
+
+    _registerShutdownHandlers() {
+        let shuttingDown = false;
+        const onSignal = async (signal) => {
+            if (shuttingDown) {
+                this._process.exit(1);
+                return;
+            }
+            shuttingDown = true;
+            try {
+                await this.shutdown();
+            } finally {
+                this._process.exit(signal === 'SIGINT' ? 130 : 143);
+            }
+        };
+        this._process.on('SIGINT', onSignal);
+        this._process.on('SIGTERM', onSignal);
+        // Other exits must not leave cloudflared running. This handler must be synchronous, so it
+        // cannot revoke the session; the session TTL ends it.
+        this._process.once('exit', () => this.stop());
+    }
+
+    /**
+     * If cloudflared exits while preview is active, the tunnel URL is dead. Stop the heartbeat and
+     * revoke the session, so the session does not stay alive for a tunnel that is gone.
+     */
+    _watchTunnel(tunnel) {
+        tunnel.exited.then(async ({ reason, output }) => {
+            // stop() clears this._tunnel first, so an exit that we started is not an error.
+            if (this._tunnel !== tunnel) {
+                return;
+            }
+            this._logger.error(
+                `${'Error'.red}: cloudflared stopped unexpectedly (${reason}). ` +
+                    'Makeswift preview no longer works. Restart stencil start.' +
+                    (output ? `\ncloudflared output:\n${output}` : ''),
+            );
+            await this.shutdown();
+        });
+    }
+
+    _warnUnavailable(err) {
+        this._logger.error(
+            `${'Warning'.yellow}: Makeswift preview is not available. ${err.message}\n` +
+                'The local server continues without Makeswift preview.',
+        );
+    }
+}
+
+export default MakeswiftPreview;

package/lib/PreviewSessionClient.js

@@ -0,0 +1,158 @@
+import crypto from 'crypto';
+
+const SESSIONS_PATH = '/api/makeswift/preview-sessions';
+const ACCESS_TOKEN_HEADER = 'x-stencil-access-token';
+const REQUEST_TIMEOUT_MS = 10000;
+
+/**
+ * @param {string} message
+ * @param {{ status?: number, retryable?: boolean }} [options]
+ * @returns {Error & { status?: number, retryable: boolean }}
+ */
+function previewSessionError(message, { status, retryable = false } = {}) {
+    return Object.assign(new Error(message), { status, retryable });
+}
+
+const isNonEmptyString = (value) => typeof value === 'string' && value !== '';
+
+const isValidExpiresIn = (data) => Number.isFinite(data?.expiresIn) && data.expiresIn > 0;
+
+function isValidRegistration(data) {
+    return (
+        isNonEmptyString(data?.sessionId) &&
+        isNonEmptyString(data?.accessKey) &&
+        isValidExpiresIn(data)
+    );
+}
+
+/**
+ * Registers, renews, and revokes Makeswift preview sessions.
+ */
+class PreviewSessionClient {
+    constructor({ fetch = globalThis.fetch, timeout = REQUEST_TIMEOUT_MS } = {}) {
+        this._fetch = fetch;
+        this._timeout = timeout;
+    }
+
+    /**
+     * The worker sends this secret to the local renderer on each tunnel request.
+     *
+     * @returns {string}
+     */
+    createSecret() {
+        return crypto.randomBytes(32).toString('hex');
+    }
+
+    /**
+     * @param {object} options
+     * @param {string} options.storeUrl - channel URL, or the store URL when there is no channel URL
+     * @param {string} options.accessToken
+     * @param {string} options.tunnelUrl
+     * @param {string} options.secret
+     * @returns {Promise<{ sessionId: string, accessKey: string, expiresIn: number }>}
+     */
+    async register({ storeUrl, accessToken, tunnelUrl, secret }) {
+        const data = await this._request({
+            method: 'POST',
+            storeUrl,
+            path: SESSIONS_PATH,
+            accessToken,
+            body: { tunnelUrl, secret },
+            action: 'register',
+            isValid: isValidRegistration,
+        });
+        const { sessionId, accessKey, expiresIn } = data;
+        return { sessionId, accessKey, expiresIn };
+    }
+
+    /**
+     * Renews the session TTL. The access key does not change.
+     * A 404 error means the session is gone and must be registered again.
+     *
+     * @param {object} options
+     * @param {string} options.storeUrl
+     * @param {string} options.accessToken
+     * @param {string} options.sessionId
+     * @returns {Promise<{ expiresIn: number }>}
+     */
+    async heartbeat({ storeUrl, accessToken, sessionId }) {
+        const { expiresIn } = await this._request({
+            method: 'POST',
+            storeUrl,
+            path: `${SESSIONS_PATH}/${encodeURIComponent(sessionId)}/heartbeat`,
+            accessToken,
+            action: 'renew',
+            isValid: isValidExpiresIn,
+        });
+        return { expiresIn };
+    }
+
+    /**
+     * Ends the session immediately. The worker responds 204 also when the session is already gone.
+     *
+     * @param {object} options
+     * @param {string} options.storeUrl
+     * @param {string} options.accessToken
+     * @param {string} options.sessionId
+     * @returns {Promise<void>}
+     */
+    async revoke({ storeUrl, accessToken, sessionId }) {
+        await this._request({
+            method: 'DELETE',
+            storeUrl,
+            path: `${SESSIONS_PATH}/${encodeURIComponent(sessionId)}`,
+            accessToken,
+            action: 'revoke',
+        });
+    }
+
+    /**
+     * @returns {Promise<object | undefined>} the validated JSON body, or undefined without `isValid`
+     */
+    async _request({ method, storeUrl, path, accessToken, body, action, isValid }) {
+        const url = new URL(path, storeUrl);
+        if (url.protocol !== 'https:') {
+            throw previewSessionError('Makeswift preview requires an HTTPS store URL.');
+        }
+        const failure = `Could not ${action} the Makeswift preview session`;
+
+        let response;
+        try {
+            response = await this._fetch(url, {
+                method,
+                headers: {
+                    ...(body && { 'content-type': 'application/json' }),
+                    [ACCESS_TOKEN_HEADER]: accessToken,
+                },
+                body: body && JSON.stringify(body),
+                redirect: 'manual',
+                signal: AbortSignal.timeout(this._timeout),
+            });
+        } catch {
+            throw previewSessionError(`${failure}: the request failed.`, { retryable: true });
+        }
+
+        const { status } = response;
+        if (!response.ok) {
+            const hint = status === 401 ? ' Make sure the access token in .stencil is valid.' : '';
+            throw previewSessionError(`${failure} (HTTP ${status}).${hint}`, {
+                status,
+                retryable: status === 429 || status >= 500,
+            });
+        }
+
+        if (!isValid) {
+            return undefined;
+        }
+        const data = await response.json().catch(() => null);
+        if (!isValid(data)) {
+            throw previewSessionError(`${failure}: the response (HTTP ${status}) is not valid.`, {
+                status,
+            });
+        }
+        return data;
+    }
+}
+
+export { PreviewSessionClient };
+export default new PreviewSessionClient();

package/lib/PreviewSessionHeartbeat.js

@@ -0,0 +1,117 @@
+import 'colors';
+
+// The worker TTL is 300s, so 4 heartbeats in a row can fail before the session expires.
+const INTERVAL_MS = 60000;
+const WARN_AFTER_FAILURES = 2;
+
+/**
+ * Keeps a Makeswift preview session alive with a heartbeat every 60s. A failed heartbeat is
+ * retried on the next tick. When the session is gone (404), it registers a new one and updates
+ * the live session object, so the preview proxy uses it on the next request.
+ */
+class PreviewSessionHeartbeat {
+    /**
+     * @param {object} options
+     * @param {{ heartbeat: Function, register: Function }} options.client - PreviewSessionClient
+     * @param {{ storeUrl: string, tunnelUrl: string, secret: string, sessionId: string, accessKey: string, expiresIn: number }} options.session -
+     *   the live session object; changed in place
+     * @param {string} options.accessToken
+     * @param {{ log: Function, error: Function }} [options.logger]
+     */
+    constructor({ client, session, accessToken, logger = console }) {
+        this._client = client;
+        this._session = session;
+        this._accessToken = accessToken;
+        this._logger = logger;
+        this._timer = null;
+        this._busy = false;
+        this._failures = 0;
+    }
+
+    start() {
+        this.stop();
+        this._failures = 0;
+        const timer = setInterval(() => this._beat(timer), INTERVAL_MS);
+        timer.unref();
+        this._timer = timer;
+    }
+
+    stop() {
+        clearInterval(this._timer);
+        this._timer = null;
+    }
+
+    async _beat(timer) {
+        // The client times out after 10s, so this only skips a tick in unusual cases.
+        if (this._busy) {
+            return;
+        }
+        this._busy = true;
+        const stopped = () => this._timer !== timer;
+        try {
+            await this._keepAlive(stopped);
+            if (stopped()) {
+                return;
+            }
+            if (this._failures >= WARN_AFTER_FAILURES) {
+                this._logger.log('The Makeswift preview session is renewed.');
+            }
+            this._failures = 0;
+        } catch (err) {
+            if (!stopped()) {
+                this._onFailure(err);
+            }
+        } finally {
+            this._busy = false;
+        }
+    }
+
+    /**
+     * @param {() => boolean} stopped - true after stop(); then the session must not change
+     */
+    async _keepAlive(stopped) {
+        const { storeUrl, tunnelUrl, secret, sessionId } = this._session;
+        const accessToken = this._accessToken;
+        try {
+            await this._client.heartbeat({ storeUrl, accessToken, sessionId });
+            return;
+        } catch (err) {
+            if (err.status !== 404 || stopped()) {
+                throw err;
+            }
+        }
+        const registration = await this._client.register({
+            storeUrl,
+            accessToken,
+            tunnelUrl,
+            secret,
+        });
+        if (stopped()) {
+            return;
+        }
+        const { sessionId: newSessionId, accessKey, expiresIn } = registration;
+        Object.assign(this._session, { sessionId: newSessionId, accessKey, expiresIn });
+        this._logger.log('The Makeswift preview session expired. A new session is registered.');
+    }
+
+    _onFailure(err) {
+        if (!err.retryable) {
+            this.stop();
+            this._logger.error(
+                `${'Error'.red}: ${err.message}\n` +
+                    'Makeswift preview stops when the session expires. ' +
+                    'Correct the problem, then restart stencil start.',
+            );
+            return;
+        }
+        this._failures += 1;
+        if (this._failures === WARN_AFTER_FAILURES) {
+            this._logger.error(
+                `${'Warning'.yellow}: ${err.message} Retrying in ${INTERVAL_MS / 1000}s.\n` +
+                    'Makeswift preview can stop working until the session is renewed.',
+            );
+        }
+    }
+}
+
+export default PreviewSessionHeartbeat;

package/lib/TunnelManager.js

@@ -0,0 +1,134 @@
+import { spawn as nodeSpawn } from 'child_process';
+import { once } from 'events';
+import cloudflaredBinaryModule, { INSTALL_URL, PATH_ENV } from './cloudflared-binary.js';
+
+const TUNNEL_URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+const INSTALL_HINT = `Install cloudflared, or set ${PATH_ENV} to the path of cloudflared: ${INSTALL_URL}`;
+// Keep only the end of the cloudflared log, for error messages.
+const LOG_TAIL_LENGTH = 16 * 1024;
+const LOG_TAIL_LINES = 5;
+
+/**
+ * Starts a Cloudflare Quick Tunnel (no Cloudflare account needed) to a local port.
+ */
+class TunnelManager {
+    constructor({
+        spawn = nodeSpawn,
+        cloudflaredBinary = cloudflaredBinaryModule,
+        startTimeout = 30000,
+        killTimeout = 2000,
+    } = {}) {
+        this._spawn = spawn;
+        this._cloudflaredBinary = cloudflaredBinary;
+        this._startTimeout = startTimeout;
+        this._killTimeout = killTimeout;
+    }
+
+    /**
+     * `exited` resolves when cloudflared exits for any reason, including stop(). It does not
+     * reject. `reason` is the exit code or signal; `output` is the last lines of the log.
+     *
+     * @param {number} port
+     * @returns {Promise<{ url: string, stop: () => Promise<void>, exited: Promise<{ reason: string, output: string }> }>}
+     */
+    async start(port) {
+        const binaryPath = await this._cloudflaredBinary.resolve();
+        const child = this._spawn(
+            binaryPath,
+            // --grace-period: on SIGTERM, exit after 1s instead of the default 30s.
+            [
+                'tunnel',
+                '--url',
+                `http://localhost:${port}`,
+                '--no-autoupdate',
+                '--grace-period',
+                '1s',
+            ],
+            // cloudflared writes its log, including the tunnel URL, to stderr.
+            { stdio: ['ignore', 'ignore', 'pipe'] },
+        );
+        // Rejects on a spawn error, for example ENOENT when cloudflared is not installed.
+        const exited = once(child, 'exit');
+        let log = '';
+        const onLog = (chunk) => {
+            log = (log + chunk).slice(-LOG_TAIL_LENGTH);
+        };
+        // This listener also keeps reading stderr, so cloudflared does not block on a full pipe.
+        child.stderr.on('data', onLog);
+        const lastLines = () => log.trim().split('\n').slice(-LOG_TAIL_LINES).join('\n');
+        const exitInfo = exited.then(
+            ([code, signal]) => ({ reason: signal || `code ${code}`, output: lastLines() }),
+            (err) => ({ reason: err.message, output: lastLines() }),
+        );
+        let stopPromise;
+        const stop = () => {
+            stopPromise ??= (async () => {
+                let killTimer;
+                if (child.exitCode === null && child.signalCode === null) {
+                    child.kill('SIGTERM');
+                    killTimer = setTimeout(() => child.kill('SIGKILL'), this._killTimeout);
+                    killTimer.unref();
+                }
+                await exited.catch(() => {});
+                clearTimeout(killTimer);
+            })();
+            return stopPromise;
+        };
+
+        let onUrl;
+        let timer;
+        try {
+            const url = await new Promise((resolve, reject) => {
+                onUrl = () => {
+                    const match = log.match(TUNNEL_URL_PATTERN);
+                    if (match) {
+                        resolve(match[0]);
+                    }
+                };
+                // Added after onLog, so `log` already has the chunk.
+                child.stderr.on('data', onUrl);
+                exited.then(
+                    ([code, signal]) =>
+                        reject(
+                            new Error(
+                                `cloudflared exited (${
+                                    signal || `code ${code}`
+                                }) before it returned a tunnel URL.`,
+                            ),
+                        ),
+                    (err) =>
+                        reject(
+                            err.code === 'ENOENT'
+                                ? new Error(
+                                      `cloudflared was not found at ${binaryPath}. ${INSTALL_HINT}`,
+                                  )
+                                : err,
+                        ),
+                );
+                timer = setTimeout(
+                    () =>
+                        reject(
+                            new Error(
+                                `cloudflared did not return a tunnel URL after ${
+                                    this._startTimeout / 1000
+                                }s. Check your network connection.`,
+                            ),
+                        ),
+                    this._startTimeout,
+                );
+            });
+            return { url, stop, exited: exitInfo };
+        } catch (err) {
+            await stop();
+            const output = lastLines();
+            err.message += output ? `\ncloudflared output:\n${output}` : '';
+            throw err;
+        } finally {
+            clearTimeout(timer);
+            child.stderr.off('data', onUrl);
+        }
+    }
+}
+
+export { TunnelManager };
+export default new TunnelManager();