// @ts-check import fs from "fs"; import path from "path"; import { performance } from "perf_hooks"; import { fileURLToPath, URL } from "url"; import chokidar from "chokidar"; import compression from "compression"; import express from "express"; import yargs from "yargs"; import ContextCache from "./scripts/ContextCache.js"; import createRoute from "./scripts/createRoute.js"; import { glslToJavaScript, createIndexJs, getWorkspaces, } from "./scripts/build-utilities.js"; import { createCesiumJs, createCombinedSpecList, buildCesium, } from "./scripts/build.js"; /** @import {BuildContext} from "esbuild"; */ /** @import {CesiumBundles, Workspace} from "./scripts/build-utilities.js"; */ const argv = await yargs(process.argv) .options({ port: { default: 8080, description: "Port to listen on.", }, public: { type: "boolean", description: "Run a public server that listens on all interfaces.", }, production: { type: "boolean", description: "If true, skip build step and serve existing built files.", }, embeddings: { type: "boolean", default: true, description: "Generate Sandcastle semantic search embeddings. Pass --no-embeddings to skip. Can also be set via SANDCASTLE_NO_EMBEDDINGS=1.", }, }) .help().argv; // These functions will not exist in the production zip file but they also won't be run const { getSandcastleConfig, buildSandcastleGallery, buildSandcastleApp } = argv.production ? {} : await import("./scripts/buildSandcastle.js"); const outputDirectory = path.join("Build", "CesiumDev"); /** * Formats the time elapsed since the given start time in seconds. * @private * @param {number} start The start time in milliseconds. * @returns {number} The time since the start in seconds, rounded to the nearest tenth. */ function formatTimeSinceInSeconds(start) { return Math.ceil((performance.now() - start) / 100) / 10; } /** * Bundles for the CesiumJS development build. Fields are narrowed to BuildContext since * incremental:true guarantees live contexts here rather than one-off BuildResults. * @typedef {object} DevelopmentBuildContexts * @property {BuildContext} esm * @property {BuildContext} iife * @property {BuildContext} [iifeWorkers] * @property {BuildContext} workers * @property {BuildContext} specs * @property {BuildContext} testWorkers * @property {Record} packages Bundles for each published workspace package, keyed by workspace name. * @property {Record} packageSourceGlobs Each published workspace's Source globs, keyed by workspace name. */ /** * Returns CesiumJS bundles configured for development. * * @returns {Promise} The bundles. */ async function generateDevelopmentBuild() { const startTime = performance.now(); const workspaces = getWorkspaces(true); /** @type {Record} */ const packageContexts = {}; /** @type {Record} */ const packageSourceGlobs = {}; for (let i = 0; i < workspaces.length; i++) { const workspace = workspaces[i]; console.log( `[${i + 1}/${workspaces.length + 1}] Building @cesium/${workspace}...`, ); const buildName = `build${workspace.charAt(0).toUpperCase()}${workspace.slice(1)}`; const packageModule = await import( `./packages/${workspace}/scripts/build.js` ); packageSourceGlobs[workspace] = packageModule.sourceGlobs; packageContexts[workspace] = await packageModule[buildName]({ incremental: true, minify: false, write: false, }); } // Build CesiumJS and save returned contexts for rebuilding upon request console.log( `[${workspaces.length + 1}/${workspaces.length + 1}] Building CesiumJS...`, ); const contexts = await buildCesium({ iife: true, incremental: true, minify: false, node: false, outputDirectory: outputDirectory, removePragmas: false, sourcemap: true, write: false, }); console.log( `Cesium built in ${formatTimeSinceInSeconds(startTime)} seconds.`, ); // Cast needed because the upstream build functions type their bundles loosely, // but passing incremental:true above guarantees BuildContext instances here. return /** @type {DevelopmentBuildContexts} */ ({ ...contexts, packages: packageContexts, packageSourceGlobs: packageSourceGlobs, }); } // Delay execution of the callback until a short time has elapsed since it was last invoked, preventing // calls to the same function in quick succession from triggering multiple builds. const throttleDelay = 500; /** @param {() => Promise} callback */ const throttle = (callback) => { /** @type {NodeJS.Timeout|undefined} */ let timeout; return () => new Promise((resolve) => { if (timeout) { clearTimeout(timeout); } timeout = setTimeout(() => { resolve(callback()); }, throttleDelay); }); }; (async function () { const gzipHeader = Buffer.from("1F8B08", "hex"); const production = argv.production; /** @type {DevelopmentBuildContexts|undefined} */ let contexts; if (!production) { contexts = await generateDevelopmentBuild(); const __dirname = path.dirname(fileURLToPath(import.meta.url)); if ( buildSandcastleApp && !fs.existsSync(path.join(__dirname, "/Apps/Sandcastle2/index.html")) ) { // Sandcastle takes a bit of time to build and is unlikely to change often // Only build it when we detect it doesn't exist to save on dev time console.log("Building Sandcastle..."); const startTime = performance.now(); const noEmbeddings = !argv.embeddings || !!process.env.SANDCASTLE_NO_EMBEDDINGS; await buildSandcastleApp({ outputToBuildDir: false, includeDevelopment: true, outerOrigin: "http://localhost:8080", innerOrigin: "http://localhost:8081", generateEmbeddings: noEmbeddings ? false : undefined, }); console.log( `Sandcastle built in ${formatTimeSinceInSeconds(startTime)} seconds.`, ); } } const app = express(); app.use(function (req, res, next) { // *NOTE* Any changes you make here must be mirrored in web.config. /** @type {Record} */ const extensionToMimeType = { ".czml": "application/json", ".json": "application/json", ".geojson": "application/json", ".topojson": "application/json", ".wasm": "application/wasm", ".ktx2": "image/ktx2", ".gltf": "model/gltf+json", ".bgltf": "model/gltf-binary", ".glb": "model/gltf-binary", ".b3dm": "application/octet-stream", ".pnts": "application/octet-stream", ".i3dm": "application/octet-stream", ".cmpt": "application/octet-stream", ".geom": "application/octet-stream", ".vctr": "application/octet-stream", ".glsl": "text/plain", }; const extension = path.extname(req.url); if (extensionToMimeType[extension]) { res.contentType(extensionToMimeType[extension]); } next(); }); app.use(compression()); //eslint-disable-next-line no-unused-vars app.use(function (req, res, next) { res.header("Access-Control-Allow-Origin", "*"); res.header( "Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept", ); next(); }); /** * Checks whether the requested file is gzip-compressed and sets the Content-Encoding header accordingly. * @param {express.Request} req The incoming request. * @param {express.Response} res The outgoing response. * @param {express.NextFunction} next Callback to pass control to the next handler. */ function checkGzipAndNext(req, res, next) { const baseURL = `${req.protocol}://${req.headers.host}/`; const reqUrl = new URL(req.url, baseURL); const filePath = reqUrl.pathname.substring(1); const readStream = fs.createReadStream(filePath, { start: 0, end: 2 }); //eslint-disable-next-line no-unused-vars readStream.on("error", function (err) { next(); }); readStream.on("data", function (/** @type {Buffer} */ chunk) { if (chunk.equals(gzipHeader)) { res.header("Content-Encoding", "gzip"); } next(); }); } const knownTilesetFormats = [ /\.b3dm/, /\.pnts/, /\.i3dm/, /\.cmpt/, /\.glb/, /\.geom/, /\.vctr/, /\.subtree/, /tileset.*\.json$/, ]; app.get(knownTilesetFormats, checkGzipAndNext); if (!production) { if (!contexts) { throw new Error("Development build contexts were not initialized."); } // iife:true was passed to buildCesium above, so iifeWorkers is always built. if (!contexts.iifeWorkers) { throw new Error("Development build did not produce iifeWorkers."); } const iifeWorkersCache = new ContextCache(contexts.iifeWorkers); const iifeCache = createRoute( app, "Build/CesiumUnminified/Cesium.js", "/Build/CesiumUnminified/Cesium.js{.map}", contexts.iife, [iifeWorkersCache], ); const esmCache = createRoute( app, "Build/CesiumUnminified/index.js", "/Build/CesiumUnminified/index.js{.map}", contexts.esm, ); const workersCache = createRoute( app, "Build/CesiumUnminified/Workers/*", "/Build/CesiumUnminified/Workers/*file.js", contexts.workers, ); function clearTopLevelCaches() { esmCache.clear(); iifeCache.clear(); workersCache.clear(); iifeWorkersCache.clear(); } const workspaces = getWorkspaces(true); /** @type {Record} */ const packageBundleCaches = {}; for (const workspace of workspaces) { packageBundleCaches[workspace] = createRoute( app, `packages/${workspace}/Build/Unminified/index.js`, `/packages/${workspace}/Build/Unminified/index.js{.map}`, contexts.packages[workspace].esm, ); } for (const workspace of workspaces) { if (fs.existsSync(`packages/${workspace}/Source/Shaders`)) { const glslWatcher = chokidar.watch( `packages/${workspace}/Source/Shaders`, { ignored: (path, stats) => { return !!stats?.isFile() && !path.endsWith(".glsl"); }, ignoreInitial: true, }, ); glslWatcher.on("all", async () => { await glslToJavaScript( false, "Build/minifyShaders.state", /** @type {Workspace} */ (workspace), ); clearTopLevelCaches(); packageBundleCaches[workspace].clear(); }); } const sourceWatcher = chokidar.watch([`packages/${workspace}/Source`], { ignored: [ `packages/${workspace}/Source/Shaders`, `packages/${workspace}/Source/ThirdParty`, (path, stats) => { return !!stats?.isFile() && !path.endsWith(".js"); }, ], ignoreInitial: true, }); sourceWatcher.on("all", async () => { clearTopLevelCaches(); packageBundleCaches[workspace].clear(); await createIndexJs( /** @type {Workspace} */ (workspace), contexts.packageSourceGlobs[workspace], ); await createCesiumJs(); }); } const testWorkersCache = createRoute( app, "TestWorkers/*", "/Build/Specs/TestWorkers/*file", contexts.testWorkers, ); chokidar .watch(["Specs/TestWorkers/*.js"], { ignoreInitial: true }) .on("all", testWorkersCache.clear); const specsCache = createRoute( app, "Specs/*", "/Build/Specs/*file", contexts.specs, ); const specWatcher = chokidar.watch( [ ...workspaces.map((workspace) => `packages/${workspace}/Specs`), "Specs", ], { ignored: [ ...workspaces.map( (workspace) => `packages/${workspace}/Specs/SpecList.js`, ), "Specs/SpecList.js", "Specs/e2e", (path, stats) => { return !!stats?.isFile() && !path.endsWith("Spec.js"); }, ], ignoreInitial: true, }, ); specWatcher.on("all", async (event) => { if (event === "add" || event === "unlink") { await createCombinedSpecList(); } specsCache.clear(); }); if (!production && getSandcastleConfig && buildSandcastleGallery) { const { configPath, root, gallery } = await getSandcastleConfig(); const baseDirectory = path.relative(root, path.dirname(configPath)); const galleryFiles = gallery.files.map((/** @type {string} */ pattern) => path.join(baseDirectory, pattern), ); const galleryWatcher = chokidar.watch(galleryFiles, { ignoreInitial: true, }); galleryWatcher.on( "all", throttle(async () => { const startTime = performance.now(); const noEmbeddings = !argv.embeddings || !!process.env.SANDCASTLE_NO_EMBEDDINGS; try { await buildSandcastleGallery({ includeDevelopment: true, generateEmbeddings: noEmbeddings ? false : undefined, }); console.log( `Gallery built in ${formatTimeSinceInSeconds(startTime)} seconds.`, ); } catch (e) { console.error(e); } }), ); } // Serve any static files starting with "Build/CesiumUnminified" from the // development build instead. That way, previous build output is preserved // while the latest is being served app.use("/Build/CesiumUnminified", express.static("Build/CesiumDev")); } app.use(express.static(path.resolve("."))); const server = argv.public ? app.listen(argv.port) : app.listen(argv.port, "localhost"); server.on("listening", function () { const address = server.address(); const port = typeof address === "string" ? undefined : address?.port; if (argv.public) { console.log( `Cesium development server running publicly. Connect to http://localhost:${port}/`, ); } else { console.log( `Cesium development server running locally. Connect to http://localhost:${port}/`, ); } }); server.on("error", function (/** @type {NodeJS.ErrnoException} */ e) { if (e.code === "EADDRINUSE") { console.log( `Error: Port ${argv.port} is already in use, select a different port.`, ); console.log(`Example: node server.js --port ${argv.port + 1}`); } else if (e.code === "EACCES") { console.log( `Error: This process does not have permission to listen on port ${argv.port}.`, ); if (argv.port < 1024) { console.log("Try a port number higher than 1024."); } } throw e; }); server.on("close", function () { console.log("Cesium development server stopped."); }); const sandcastleServer = app.listen(8081, "localhost", function () { // This "mirror" server runs on a separate port to create origin separation between // the main Sandcastle app and the viewer page for security // We use the same express `app` to reuse the auto re-building of assets when the source changes console.log("Sandcastle mirror server running on port 8081"); }); sandcastleServer.on( "error", function (/** @type {NodeJS.ErrnoException} */ e) { if (e.code === "EADDRINUSE") { console.log( "Error: Port 8081 is already in use, please free it and try again", ); } else if (e.code === "EACCES") { console.log( "Error: This process does not have permission to listen on port 8081.", ); } throw e; }, ); sandcastleServer.on("close", function () { console.log("Sandcastle mirror server stopped."); }); let isFirstSig = true; process.on("SIGINT", function () { if (isFirstSig) { console.log("\nCesium development servers shutting down."); if (!production) { if (!contexts) { throw new Error("Development build contexts were not initialized."); } contexts.esm.dispose(); contexts.iife.dispose(); contexts.workers.dispose(); contexts.specs.dispose(); contexts.testWorkers.dispose(); } server.close(() => { sandcastleServer.close(() => process.exit(0)); }); isFirstSig = false; } else { throw new Error("Cesium development server force kill."); } }); })();