catalyst-core 0.2.0-beta.2 → 0.3.0-beta.1

package/dist/otel.js

@@ -1,72 +1,401 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.default=void 0;exports.withObservability=withObservability;exports.withSyncObservability=withSyncObservability;function _interopRequireWildcard(e,t){if("function"==typeof WeakMap)var r=new WeakMap(),n=new WeakMap();return(_interopRequireWildcard=function(e,t){if(!t&&e&&e.__esModule)return e;var o,i,f={__proto__:null,default:e};if(null===e||"object"!=typeof e&&"function"!=typeof e)return f;if(o=t?n:r){if(o.has(e))return o.get(e);o.set(e,f);}for(const t in e)"default"!==t&&{}.hasOwnProperty.call(e,t)&&((i=(o=Object.defineProperty)&&Object.getOwnPropertyDescriptor(e,t))&&(i.get||i.set)?o(f,t,i):f[t]=e[t]);return f;})(e,t);}// OpenTelemetry is an OPT-IN feature. Nothing from "@opentelemetry/*" is
-// imported at module-eval time on purpose: the packages are declared as
-// (optional) peerDependencies and may not be installed in the consuming app.
-//
-// All OTel packages are loaded lazily via dynamic import() inside init(), and
-// only when OTEL_ENABLE === "true". Consequences:
-//   - Apps that keep OTEL disabled don't need the packages installed.
-//   - Bundlers don't pull the packages into the static import graph, so
-//     `import "catalyst-core/otel"` no longer forces them to resolve
-//     "@opentelemetry/exporter-trace-otlp-http" & friends at build time.
-//     (Pair this with marking "@opentelemetry/*" external in the bundler so the
-//     dynamic import() chunk isn't resolved at build time either — see the SSR
-//     webpack configs under src/webpack.)
-// Set once by init() (when enabled) to the loaded "@opentelemetry/api" module.
-// The wrappers below read it lazily so they never need a static OTel import.
-let _otelApi=null;const isOtelEnabled=()=>process.env.OTEL_ENABLE==="true";async function init(config={}){if(!isOtelEnabled()){return{sdk:null,meter:null};}const{serviceName="catalyst-server",serviceVersion="1.0.0",environment="development",traceUrl="http://localhost:4317",metricUrl="http://localhost:4317",traceProtocol="grpc",// "grpc" or "http"
-metricProtocol,// "grpc" or "http" - if not provided, metrics will be disabled
-traceHeaders={},metricHeaders={},batchProcessorConfig={},exportIntervalMillis=10000,instrumentations,samplingRate=1.0,grpcCredentials}=config;try{// Lazy-load every OpenTelemetry package. These dynamic imports run only
-// when OTEL_ENABLE=true, so the packages are required at runtime solely
-// for opted-in deployments.
-const[otelApi,{NodeSDK},{resourceFromAttributes},{BatchSpanProcessor,TraceIdRatioBasedSampler,ParentBasedSampler},{PeriodicExportingMetricReader},{OTLPTraceExporter},{OTLPMetricExporter},{getNodeAutoInstrumentations},{OTLPTraceExporter:OTLPTraceExporterHTTP},{OTLPMetricExporter:OTLPMetricExporterHTTP},{ATTR_SERVICE_NAME,ATTR_SERVICE_VERSION,ATTR_DEPLOYMENT_ENVIRONMENT}]=await Promise.all([Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/api"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/sdk-node"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/resources"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/sdk-trace-node"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/sdk-metrics"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/exporter-trace-otlp-grpc"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/exporter-metrics-otlp-grpc"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/auto-instrumentations-node"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/exporter-trace-otlp-http"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/exporter-metrics-otlp-http"))),Promise.resolve().then(()=>_interopRequireWildcard(require("@opentelemetry/semantic-conventions")))]);// Enables the withObservability / withSyncObservability wrappers.
-_otelApi=otelApi;const traceExporters={OTLPTraceExporter,OTLPTraceExporterHTTP};const metricExporters={OTLPMetricExporter,OTLPMetricExporterHTTP};const otlpTraceExporter=createTraceExporter(traceExporters,traceProtocol,traceUrl,traceHeaders,grpcCredentials);// Create metric exporter only if metricProtocol is specified
-let metricReader=null;if(metricProtocol){const otlpMetricExporter=createMetricExporter(metricExporters,metricProtocol,metricUrl,metricHeaders,grpcCredentials);metricReader=new PeriodicExportingMetricReader({exporter:otlpMetricExporter,exportIntervalMillis});}const sampler=new ParentBasedSampler({root:new TraceIdRatioBasedSampler(samplingRate)});const sdkConfig={resource:resourceFromAttributes({[ATTR_SERVICE_NAME]:serviceName,[ATTR_SERVICE_VERSION]:serviceVersion,[ATTR_DEPLOYMENT_ENVIRONMENT]:environment}),spanProcessor:new BatchSpanProcessor(otlpTraceExporter,batchProcessorConfig),instrumentations:instrumentations??[getNodeAutoInstrumentations()],sampler};// Add metric reader only if metrics are enabled
-if(metricReader){sdkConfig.metricReader=metricReader;}const sdk=new NodeSDK(sdkConfig);sdk.start();logger.info("✅ OpenTelemetry started successfully");// Initialize custom metrics only if metrics are enabled
-let meter=null;if(metricProtocol){meter=initializeCustomMetrics(otelApi,serviceName,serviceVersion);}const gracefulShutdown=signal=>{logger.info(`📡 Received ${signal}, shutting down OpenTelemetry gracefully...`);sdk.shutdown().then(()=>logger.info("✅ OpenTelemetry shutdown completed")).catch(error=>{logger.error("❌ Error terminating OpenTelemetry:",error);}).finally(()=>process.exit());};process.on("SIGTERM",()=>gracefulShutdown("SIGTERM"));process.on("SIGINT",()=>gracefulShutdown("SIGINT"));return{sdk,meter};}catch(error){logger.error("❌ Failed to initialize OpenTelemetry:",error);throw error;}}/**
+import { metrics } from "@opentelemetry/api"
+import { NodeSDK } from "@opentelemetry/sdk-node"
+import { resourceFromAttributes } from "@opentelemetry/resources"
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node"
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics"
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc"
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-grpc"
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node"
+import { TraceIdRatioBasedSampler, ParentBasedSampler } from "@opentelemetry/sdk-trace-node"
+import { OTLPTraceExporter as OTLPTraceExporterHTTP } from "@opentelemetry/exporter-trace-otlp-http"
+import { OTLPMetricExporter as OTLPMetricExporterHTTP } from "@opentelemetry/exporter-metrics-otlp-http"
+import { trace, context, createContextKey } from "@opentelemetry/api"
+
+export const IS_BOT_KEY = createContextKey("catalyst.is_bot")
+
+import semanticConventions from "@opentelemetry/semantic-conventions"
+const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, ATTR_DEPLOYMENT_ENVIRONMENT } = semanticConventions
+
+function init(config = {}) {
+    // OpenTelemetry is opt-in — bail out unless explicitly enabled. Mirrors the
+    // OTEL_ENABLE guard in server/expressServer.js and server/renderer/handler.jsx
+    // so the SDK, exporters, instrumentations and signal handlers are never set
+    // up when tracing is off. Returns the same shape so callers can destructure.
+    if (process.env.OTEL_ENABLE !== true) {
+        return { sdk: null, meter: null }
+    }
+
+    const {
+        serviceName = "catalyst-server",
+        serviceVersion = "1.0.0",
+        environment = "development",
+        traceUrl = "http://localhost:4317",
+        metricUrl = "http://localhost:4317",
+        traceProtocol = "grpc", // "grpc" or "http"
+        metricProtocol, // "grpc" or "http" - if not provided, metrics will be disabled
+        traceHeaders = {},
+        metricHeaders = {},
+        batchProcessorConfig = {},
+        exportIntervalMillis = 10000,
+        instrumentations,
+        samplingRate = 1.0,
+        grpcCredentials,
+    } = config
+
+    try {
+        const otlpTraceExporter = createTraceExporter(traceProtocol, traceUrl, traceHeaders, grpcCredentials)
+
+        // Create metric exporter only if metricProtocol is specified
+        let otlpMetricExporter = null
+        let metricReader = null
+        if (metricProtocol) {
+            otlpMetricExporter = createMetricExporter(
+                metricProtocol,
+                metricUrl,
+                metricHeaders,
+                grpcCredentials
+            )
+            metricReader = new PeriodicExportingMetricReader({
+                exporter: otlpMetricExporter,
+                exportIntervalMillis,
+            })
+        }
+
+        const sampler = new ParentBasedSampler({
+            root: new TraceIdRatioBasedSampler(samplingRate),
+        })
+
+        const sdkConfig = {
+            resource: resourceFromAttributes({
+                [ATTR_SERVICE_NAME]: serviceName,
+                [ATTR_SERVICE_VERSION]: serviceVersion,
+                [ATTR_DEPLOYMENT_ENVIRONMENT]: environment,
+            }),
+            spanProcessor: new BatchSpanProcessor(otlpTraceExporter, batchProcessorConfig),
+            instrumentations: instrumentations ?? [getNodeAutoInstrumentations()],
+            sampler,
+        }
+
+        // Add metric reader only if metrics are enabled
+        if (metricReader) {
+            sdkConfig.metricReader = metricReader
+        }
+
+        const sdk = new NodeSDK(sdkConfig)
+
+        sdk.start()
+        logger.info("✅ OpenTelemetry started successfully")
+
+        // Initialize custom metrics only if metrics are enabled
+        let meter = null
+        if (metricProtocol) {
+            meter = initializeCustomMetrics(serviceName, serviceVersion)
+        }
+
+        const gracefulShutdown = (signal) => {
+            logger.info(`📡 Received ${signal}, shutting down OpenTelemetry gracefully...`)
+            sdk.shutdown()
+                .then(() => logger.info("✅ OpenTelemetry shutdown completed"))
+                .catch((error) => {
+                    logger.error("❌ Error terminating OpenTelemetry:", error)
+                })
+                .finally(() => process.exit())
+        }
+
+        process.on("SIGTERM", () => gracefulShutdown("SIGTERM"))
+        process.on("SIGINT", () => gracefulShutdown("SIGINT"))
+
+        return { sdk, meter }
+    } catch (error) {
+        logger.error("❌ Failed to initialize OpenTelemetry:", error)
+        throw error
+    }
+}
+
+/**
  * Creates a trace exporter based on the specified protocol
- * @param {object} exporters - Lazily-loaded exporter constructors { OTLPTraceExporter, OTLPTraceExporterHTTP }
  * @param {string} protocol - "grpc" or "http"
  * @param {string} url - Exporter endpoint URL
  * @param {object} headers - Headers to include in requests
  * @param {Function} [grpcCredentials] - gRPC Credentials (optional)
- * @returns {object} Configured trace exporter
- */function createTraceExporter(exporters,protocol,url,headers={},grpcCredentials){const{OTLPTraceExporter,OTLPTraceExporterHTTP}=exporters;if(protocol.toLowerCase()==="http"){logger.info(`📡 Creating HTTP trace exporter for URL: ${url}`);return new OTLPTraceExporterHTTP({url:url,headers:headers});}else if(protocol.toLowerCase()==="grpc"){logger.info(`📡 Creating gRPC trace exporter for URL: ${url}`);return new OTLPTraceExporter({url:url,headers:headers,credentials:grpcCredentials});}else{throw new Error(`❌ Unsupported trace protocol: ${protocol}. Supported protocols are "grpc" and "http"`);}}/**
+ * @returns {OTLPTraceExporter|OTLPTraceExporterHTTP} Configured trace exporter
+ */
+function createTraceExporter(protocol, url, headers = {}, grpcCredentials) {
+    if (protocol.toLowerCase() === "http") {
+        logger.info(`📡 Creating HTTP trace exporter for URL: ${url}`)
+        return new OTLPTraceExporterHTTP({
+            url: url,
+            headers: headers,
+        })
+    } else if (protocol.toLowerCase() === "grpc") {
+        logger.info(`📡 Creating gRPC trace exporter for URL: ${url}`)
+        return new OTLPTraceExporter({
+            url: url,
+            headers: headers,
+            credentials: grpcCredentials,
+        })
+    } else {
+        throw new Error(
+            `❌ Unsupported trace protocol: ${protocol}. Supported protocols are "grpc" and "http"`
+        )
+    }
+}
+
+/**
  * Creates a metric exporter based on the specified protocol
- * @param {object} exporters - Lazily-loaded exporter constructors { OTLPMetricExporter, OTLPMetricExporterHTTP }
  * @param {string} protocol - "grpc" or "http"
  * @param {string} url - Exporter endpoint URL
  * @param {object} headers - Headers to include in requests
  * @param {Function} [grpcCredentials] - gRPC Credentials (optional)
- * @returns {object} Configured metric exporter
- */function createMetricExporter(exporters,protocol,url,headers={},grpcCredentials){const{OTLPMetricExporter,OTLPMetricExporterHTTP}=exporters;if(protocol.toLowerCase()==="http"){logger.info(`📊 Creating HTTP metric exporter for URL: ${url}`);return new OTLPMetricExporterHTTP({url:url,headers:headers});}else if(protocol.toLowerCase()==="grpc"){logger.info(`📊 Creating gRPC metric exporter for URL: ${url}`);return new OTLPMetricExporter({url:url,headers:headers,credentials:grpcCredentials});}else{throw new Error(`❌ Unsupported metric protocol: ${protocol}. Supported protocols are "grpc" and "http"`);}}/**
- * @param {object} otelApi - The loaded "@opentelemetry/api" module
- */function initializeCustomMetrics(otelApi,serviceName,serviceVersion){let customMetrics={};const meter=otelApi.metrics.getMeter(serviceName,serviceVersion);// CPU usage gauge
-customMetrics.cpuUsage=meter.createObservableGauge("process_cpu_usage_percent",{description:"Current CPU usage percentage"});// Memory usage gauges
-customMetrics.memoryUsage=meter.createObservableGauge("process_memory_usage_bytes",{description:"Current memory usage in bytes",unit:"bytes"});customMetrics.memoryHeapUsed=meter.createObservableGauge("process_memory_heap_used_bytes",{description:"Current heap memory used in bytes",unit:"bytes"});customMetrics.memoryHeapTotal=meter.createObservableGauge("process_memory_heap_total_bytes",{description:"Current heap memory total in bytes",unit:"bytes"});let lastCpuUsage=process.cpuUsage();let lastMeasureTime=process.hrtime.bigint();customMetrics.cpuUsage.addCallback(result=>{const currentCpuUsage=process.cpuUsage(lastCpuUsage);const currentTime=process.hrtime.bigint();const timeDiff=Number(currentTime-lastMeasureTime)/1000000;// Convert to milliseconds
-const cpuPercent=(currentCpuUsage.user+currentCpuUsage.system)/1000/timeDiff*100;result.observe(cpuPercent);lastCpuUsage=process.cpuUsage();lastMeasureTime=currentTime;});customMetrics.memoryUsage.addCallback(result=>{const memUsage=process.memoryUsage();result.observe(memUsage.rss,{type:"rss"});result.observe(memUsage.external,{type:"external"});result.observe(memUsage.arrayBuffers,{type:"arrayBuffers"});});customMetrics.memoryHeapUsed.addCallback(result=>{const memUsage=process.memoryUsage();result.observe(memUsage.heapUsed);});customMetrics.memoryHeapTotal.addCallback(result=>{const memUsage=process.memoryUsage();result.observe(memUsage.heapTotal);});return meter;}/**
+ * @returns {OTLPMetricExporter|OTLPMetricExporterHTTP} Configured metric exporter
+ */
+function createMetricExporter(protocol, url, headers = {}, grpcCredentials) {
+    if (protocol.toLowerCase() === "http") {
+        logger.info(`📊 Creating HTTP metric exporter for URL: ${url}`)
+        return new OTLPMetricExporterHTTP({
+            url: url,
+            headers: headers,
+        })
+    } else if (protocol.toLowerCase() === "grpc") {
+        logger.info(`📊 Creating gRPC metric exporter for URL: ${url}`)
+        return new OTLPMetricExporter({
+            url: url,
+            headers: headers,
+            credentials: grpcCredentials,
+        })
+    } else {
+        throw new Error(
+            `❌ Unsupported metric protocol: ${protocol}. Supported protocols are "grpc" and "http"`
+        )
+    }
+}
+
+function initializeCustomMetrics(serviceName, serviceVersion) {
+    let customMetrics = {}
+    const meter = metrics.getMeter(serviceName, serviceVersion)
+
+    // CPU usage gauge
+    customMetrics.cpuUsage = meter.createObservableGauge("process_cpu_usage_percent", {
+        description: "Current CPU usage percentage",
+    })
+
+    // Memory usage gauges
+    customMetrics.memoryUsage = meter.createObservableGauge("process_memory_usage_bytes", {
+        description: "Current memory usage in bytes",
+        unit: "bytes",
+    })
+
+    customMetrics.memoryHeapUsed = meter.createObservableGauge("process_memory_heap_used_bytes", {
+        description: "Current heap memory used in bytes",
+        unit: "bytes",
+    })
+
+    customMetrics.memoryHeapTotal = meter.createObservableGauge("process_memory_heap_total_bytes", {
+        description: "Current heap memory total in bytes",
+        unit: "bytes",
+    })
+
+    let lastCpuUsage = process.cpuUsage()
+    let lastMeasureTime = process.hrtime.bigint()
+
+    customMetrics.cpuUsage.addCallback((result) => {
+        const currentCpuUsage = process.cpuUsage(lastCpuUsage)
+        const currentTime = process.hrtime.bigint()
+        const timeDiff = Number(currentTime - lastMeasureTime) / 1000000 // Convert to milliseconds
+
+        const cpuPercent = ((currentCpuUsage.user + currentCpuUsage.system) / 1000 / timeDiff) * 100
+
+        result.observe(cpuPercent)
+
+        lastCpuUsage = process.cpuUsage()
+        lastMeasureTime = currentTime
+    })
+
+    customMetrics.memoryUsage.addCallback((result) => {
+        const memUsage = process.memoryUsage()
+        result.observe(memUsage.rss, { type: "rss" })
+        result.observe(memUsage.external, { type: "external" })
+        result.observe(memUsage.arrayBuffers, { type: "arrayBuffers" })
+    })
+
+    customMetrics.memoryHeapUsed.addCallback((result) => {
+        const memUsage = process.memoryUsage()
+        result.observe(memUsage.heapUsed)
+    })
+
+    customMetrics.memoryHeapTotal.addCallback((result) => {
+        const memUsage = process.memoryUsage()
+        result.observe(memUsage.heapTotal)
+    })
+
+    return meter
+}
+
+/**
  * Wraps a synchronous function and measures total execution time.
  * Creates a single OpenTelemetry span per function call.
  * Use this instead of withObservability when the wrapped function is synchronous,
  * so the return type and call sites remain unchanged.
  *
- * When OTEL is disabled the original function is returned unchanged, so there is
- * zero overhead and no dependency on any @opentelemetry/* package.
- *
  * @param {string} serviceName - The name of the service
  * @param {Function} fn - The synchronous function to wrap
  * @param {string} name - Span name (optional)
  * @returns {Function} Wrapped function (still synchronous)
- */function withSyncObservability(serviceName,fn,name){if(!isOtelEnabled())return fn;const spanName=name||fn.name||"anonymousFunction";return function(...args){// init() may not have populated the API yet — run untraced rather than throw.
-const api=_otelApi;if(!api)return fn(...args);const tracer=api.trace.getTracer(serviceName);return tracer.startActiveSpan(spanName,span=>{try{return fn(...args);}catch(err){span.recordException(err);span.setStatus({code:2,message:err.message});throw err;}finally{span.end();}});};}/**
+ */
+export function withSyncObservability(serviceName, fn, name) {
+    const tracer = trace.getTracer(serviceName)
+    const spanName = name || fn.name || "anonymousFunction"
+
+    return function (...args) {
+        const isBot = context.active().getValue(IS_BOT_KEY)
+        return tracer.startActiveSpan(spanName, (span) => {
+            if (isBot !== undefined) span.setAttribute("http.response.is_bot", isBot)
+            try {
+                return fn(...args)
+            } catch (err) {
+                span.recordException(err)
+                span.setStatus({ code: 2, message: err.message })
+                throw err
+            } finally {
+                span.end()
+            }
+        })
+    }
+}
+
+/**
  * Wraps a function (sync or async) and measures total execution time.
  * Creates a single OpenTelemetry span per function call.
  *
- * When OTEL is disabled the original function is returned unchanged, so there is
- * zero overhead and no dependency on any @opentelemetry/* package.
- *
  * @param {string} serviceName - The name of the service
  * @param {Function} fn - The function to wrap
  * @param {string} name - Span name (optional)
  * @returns {Function} Wrapped function
- */function withObservability(serviceName,fn,name){if(!isOtelEnabled())return fn;const spanName=name||fn.name||"anonymousFunction";return async function(...args){// init() may not have populated the API yet — run untraced rather than throw.
-const api=_otelApi;if(!api)return fn(...args);const tracer=api.trace.getTracer(serviceName);return tracer.startActiveSpan(spanName,async span=>{try{const result=await fn(...args);return result;}catch(err){span.recordException(err);span.setStatus({code:2,message:err.message});throw err;}finally{span.end();}});};}var _default=exports.default={init,withObservability,withSyncObservability};
+ */
+export function withObservability(serviceName, fn, name) {
+    const tracer = trace.getTracer(serviceName)
+    const spanName = name || fn.name || "anonymousFunction"
+
+    return async function (...args) {
+        const isBot = context.active().getValue(IS_BOT_KEY)
+        return tracer.startActiveSpan(spanName, async (span) => {
+            if (isBot !== undefined) span.setAttribute("http.response.is_bot", isBot)
+            try {
+                const result = await fn(...args)
+                return result
+            } catch (err) {
+                span.recordException(err)
+                span.setStatus({ code: 2, message: err.message })
+                throw err
+            } finally {
+                span.end()
+            }
+        })
+    }
+}
+
+/**
+ * Express middleware that emits two spans describing what happens to the
+ * response body AFTER the app calls res.end() — the work that lives past the
+ * `handler` span and makes the HTTP server span run longer:
+ *
+ *   • response.compress — gzip/brotli of the body. Starts when the app calls
+ *     res.end() (which returns immediately, since compression is async) and
+ *     ends when the compressed bytes are handed to the real socket end.
+ *   • response.flush — network egress. Starts when those bytes hit the socket
+ *     and ends on 'finish' (all bytes handed to the OS) or 'close' (connection
+ *     torn down first).
+ *
+ * Implementation: the gap is bounded by the *app's* res.end() call (outer) and
+ * the *real* socket end after compression (inner), so the middleware wraps
+ * res.end on BOTH sides of the compression middleware. It installs an inner
+ * hook before next() (which compression then wraps) to time the END of
+ * compression, and after next() — once compression has synchronously patched
+ * res.end — installs an outer hook on top to time the START.
+ *
+ * MOUNT THIS IMMEDIATELY BEFORE compression() so the post-next() outer hook
+ * reliably wraps compression's patch (no async middleware in between). If
+ * compression isn't present (or skips the response) only response.flush is
+ * emitted. Uses startSpan (not startActiveSpan), so the spans are siblings of
+ * `handler` under the same request span. No span is emitted if the app never
+ * writes (e.g. the client aborts first).
+ *
+ * @param {string} serviceName
+ * @param {string} [flushName] - egress span name
+ * @param {string} [compressName] - compression span name
+ * @returns {Function} Express middleware
+ */
+export function responseFlushMiddleware(
+    serviceName,
+    flushName = "response.flush",
+    compressName = "response.compress"
+) {
+    const tracer = trace.getTracer(serviceName)
+
+    return function (req, res, next) {
+        // Captured while the request span is active; both spans parent to it.
+        const parentContext = context.active()
+
+        let compressSpan = null
+        let flushSpan = null
+        let finished = false
+
+        const finalize = (endEvent) => {
+            if (finished) return
+            finished = true
+            // Whichever span is still open when the response ends gets tagged.
+            const open = flushSpan || compressSpan
+            if (open) {
+                open.setAttribute("http.response.end_event", endEvent) // "finish" | "close"
+                open.end()
+            }
+            compressSpan = null
+            flushSpan = null
+        }
+
+        // Inner hook: wraps the real res.end (installed before compression), so
+        // it fires once compression has produced the final bytes → close the
+        // compression span and open the egress span.
+        const realEnd = res.end
+        const innerEnd = function (...args) {
+            if (!finished && !flushSpan) {
+                if (compressSpan) {
+                    compressSpan.end()
+                    compressSpan = null
+                }
+                flushSpan = tracer.startSpan(
+                    flushName,
+                    { attributes: { "http.response.is_bot": res.locals.is_bot } },
+                    parentContext
+                )
+            }
+            return realEnd.apply(this, args)
+        }
+        res.end = innerEnd
+
+        res.once("finish", () => finalize("finish"))
+        res.once("close", () => finalize("close"))
+
+        next()
+
+        // After next(): compression has synchronously wrapped innerEnd. Install
+        // an outer hook on top to catch the app's res.end() call → open the
+        // compression span. Skipped if nothing wrapped innerEnd (no compression),
+        // in which case innerEnd alone times the flush from the app's res.end().
+        if (res.end !== innerEnd) {
+            const chainEnd = res.end
+            res.end = function (...args) {
+                if (!finished && !compressSpan && !flushSpan) {
+                    compressSpan = tracer.startSpan(
+                        compressName,
+                        { attributes: { "http.response.is_bot": res.locals.is_bot } },
+                        parentContext
+                    )
+                }
+                return chainEnd.apply(this, args)
+            }
+        }
+    }
+}
+
+export default { init, withObservability, withSyncObservability, responseFlushMiddleware }

package/dist/router/ClientRouter.js

@@ -1,3 +1,15 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.default=void 0;var _router=require("@tata1mg/router");var _registerServiceWorker=require("../offline/registerServiceWorker.js");const{preparedRoutes}=require(`${process.env.src_path}/src/js/routes/utils.js`);(0,_registerServiceWorker.registerCatalystServiceWorker)();/**
+import { createBrowserRouter } from "../index.jsx"
+import { preparedRoutes } from "@catalyst/template/src/js/routes/utils"
+import { registerCatalystServiceWorker } from "../offline/registerServiceWorker.js"
+
+registerCatalystServiceWorker()
+
+/**
  * @returns returns browsers routers (client routes)
- */const clientRouter=({store,routerInitialState})=>(0,_router.createBrowserRouter)(preparedRoutes({store,routerInitialState}));var _default=exports.default=clientRouter;
+ */
+const clientRouter = ({ routerInitialState }) => {
+    const browserRouter = createBrowserRouter(preparedRoutes({ routerInitialState }))
+    return browserRouter
+}
+
+export default clientRouter

package/dist/router/ServerRouter.js

@@ -1 +1,9 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.default=void 0;var _router=require("@tata1mg/router");const{preparedRoutes}=require(`${process.env.src_path}/src/js/routes/utils.js`);const ServerRouter=reduxData=>{const{store,intialData}=reduxData;return(0,_router.useRoutes)(preparedRoutes({store,routerInitialState:intialData}));};var _default=exports.default=ServerRouter;
+import { useRoutes } from "../index.jsx"
+import { preparedRoutes } from "@catalyst/template/src/js/routes/utils"
+
+const ServerRouter = (reduxData) => {
+    const { store, intialData } = reduxData
+    return useRoutes(preparedRoutes({ store, routerInitialState: intialData }))
+}
+
+export default ServerRouter

package/dist/router.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:true});var _router=require("@tata1mg/router");Object.keys(_router).forEach(function(key){if(key==="default"||key==="__esModule")return;if(key in exports&&exports[key]===_router[key])return;Object.defineProperty(exports,key,{enumerable:true,get:function(){return _router[key];}});});
+export * from "@tata1mg/router"

package/dist/scripts/build.js

@@ -1,3 +1,112 @@
-"use strict";const path=require("path");const{green,cyan,yellow}=require("picocolors");const{name}=require(`${process.cwd()}/package.json`);const{BUILD_OUTPUT_PATH}=require(`${process.cwd()}/config/config.json`);const{arrayToObject,printBundleInformation,runBuildCommands}=require("./scriptUtils.js");/**
- * @description - creates a production build of the application.
- */function build(){const isWindows=process.platform==="win32";const commandLineArguments=process.argv.slice(2);const argumentsObject=arrayToObject(commandLineArguments);const dirname=path.resolve(__dirname,"../../");const commands=["node ./dist/scripts/checkVersion",`${isWindows?"rd -r -fo":"rm -rf"} ${process.cwd()}/${BUILD_OUTPUT_PATH} & node ./dist/scripts/loadScriptsBeforeServerStarts.js`,`cross-env APPLICATION=${name||"catalyst_app"} webpack --config ./dist/webpack/production.client.babel.js --progress`,`cross-env APPLICATION=${name||"catalyst_app"} SSR=true webpack --config ./dist/webpack/production.ssr.babel.js`,`cross-env APPLICATION=${name||"catalyst_app"} node ./dist/scripts/generateOfflineManifest.js`,`cross-env APPLICATION=${name||"catalyst_app"} npx babel ./dist/server --out-dir ${process.cwd()}/${BUILD_OUTPUT_PATH} --extensions .js,.ts,.jsx,.tsx --ignore '**/*.test.js,./dist/server/renderer/handler.js' --quiet`,`cross-env APPLICATION=${name||"catalyst_app"} npx babel ${process.cwd()}/server --out-dir ${process.cwd()}/${BUILD_OUTPUT_PATH} --extensions .js,.ts,.jsx,.tsx --quiet`];console.log("Creating an optimized production build...");runBuildCommands({commands,cwd:dirname,env:{...process.env,src_path:process.cwd(),BUILD_OUTPUT_PATH:BUILD_OUTPUT_PATH,NODE_ENV:"production",IS_DEV_COMMAND:false,...argumentsObject}});console.log(green("Compiled successfully."));console.log("\nFile sizes after gzip:\n");printBundleInformation();console.log(`\nThe ${cyan(BUILD_OUTPUT_PATH)} folder is ready to be deployed.`);console.log("You may serve it with a serve command:");console.log(cyan("\n npm run serve"));console.log("\nFind out more about deployment here:");console.log(yellow("\n https://catalyst.1mg.com/public_docs/content/Deployment%20and%20Production/deployment\n"));}build();
+import path from "path"
+import { spawn } from "child_process"
+import { arrayToObject } from "./scriptUtils.js"
+import { fileURLToPath } from "url"
+import { dirname } from "path"
+import { readFileSync, existsSync, rmSync } from "fs"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const loaderPath = path.resolve(__dirname, "../../dist/vite/node-loader.mjs")
+const configPath = path.join(process.env.PWD, "config/config.json")
+const configJSON = JSON.parse(readFileSync(configPath), "utf-8")
+
+/**
+ * @param {string} command
+ * @param {import('child_process').SpawnOptions} options
+ */
+function runBuildStep(command, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, [], {
+            ...options,
+            shell: true,
+        })
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve()
+            } else {
+                reject(Object.assign(new Error(`Build step failed with exit code ${code}`), { code }))
+            }
+        })
+        child.on("error", reject)
+    })
+}
+
+/**
+ * @description - builds the application for production
+ */
+async function build() {
+    const commandLineArguments = process.argv.slice(2)
+    const argumentsObject = arrayToObject(commandLineArguments)
+    const dirname = path.resolve(__dirname, "../../")
+
+    // Read package.json
+    const packageJson = JSON.parse(readFileSync(path.join(process.env.PWD, "package.json"), "utf-8"))
+    const { name } = packageJson
+
+    const buildOutputPath = path.join(process.env.PWD, configJSON.BUILD_OUTPUT_PATH || "build")
+    if (existsSync(buildOutputPath)) {
+        console.log("🧹 Clearing previous build output...")
+        rmSync(buildOutputPath, { recursive: true, force: true })
+    }
+
+    console.log("🏗️  Building application for production...")
+
+    const baseEnv = {
+        ...process.env,
+        src_path: process.env.PWD,
+        NODE_ENV: "production",
+        VITE_BUILD_MODE: "true",
+        APPLICATION: name || "catalyst_app",
+        NODE_OPTIONS: `--loader ${loaderPath}`,
+        ...argumentsObject,
+        filterKeys: JSON.stringify([
+            "src_path",
+            "NODE_ENV",
+            "VITE_BUILD_MODE",
+            "APPLICATION",
+            ...Object.keys(argumentsObject),
+        ]),
+    }
+
+    const serverBuildCommand = `vite build --config ./dist/vite/vite.config.server.js --ssr`
+    const clientBuildCommand = `vite build --config ./dist/vite/vite.config.client.js`
+    const spawnBase = {
+        cwd: dirname,
+        stdio: "inherit",
+    }
+
+    console.log("🔧📦 Building server and client bundles in parallel...")
+
+    try {
+        await Promise.all([
+            runBuildStep(serverBuildCommand, {
+                ...spawnBase,
+                env: { ...baseEnv, CATALYST_VITE_CACHE_ID: "ssr" },
+            }),
+            runBuildStep(clientBuildCommand, {
+                ...spawnBase,
+                env: { ...baseEnv, CATALYST_VITE_CACHE_ID: "client" },
+            }),
+        ])
+    } catch {
+        console.error("❌ Build failed!")
+        process.exit(1)
+    }
+
+    console.log("✅ Server and client builds completed!")
+
+    await runBuildStep("node ./dist/scripts/generateOfflineManifest.js", {
+        ...spawnBase,
+        env: baseEnv,
+    })
+
+    console.log("🎉 Build completed successfully!")
+    console.log("📁 Built files are located in the 'build' directory")
+    console.log("🚀 Run 'npm run serve' to start the production server")
+}
+
+build().catch((err) => {
+    console.error(err)
+    process.exit(1)
+})

package/dist/scripts/checkVersion.js

@@ -1 +1,3 @@
-"use strict";if(process.versions.node.split(".")[0]<20){console.error("\x1b[31m%s\x1b[0m","use node version >=20");}
+if (process.versions.node.split(".")[0] < 20) {
+    console.error("\x1b[31m%s\x1b[0m", "use node version >=20")
+}

package/dist/scripts/cleanCache.js

@@ -1 +1,30 @@
-"use strict";const fs=require("fs");const path=require("path");function cleanCache(){const catalystCacheDir=path.join(process.cwd(),"node_modules/catalyst-core");const webpackCacheDir=path.join(catalystCacheDir,".cache/webpack");const loadableStats=path.join(catalystCacheDir,"loadable-stats.json");let cleaned=false;if(fs.existsSync(webpackCacheDir)){fs.rmSync(webpackCacheDir,{recursive:true,force:true});console.log("[Catalyst] Removed webpack filesystem cache.");cleaned=true;}if(fs.existsSync(loadableStats)){fs.rmSync(loadableStats);console.log("[Catalyst] Removed loadable-stats.json.");cleaned=true;}if(!cleaned){console.log("[Catalyst] Nothing to clean — cache is already empty.");}else{console.log("[Catalyst] Clean complete. Next dev start will be a full rebuild.");}}cleanCache();
+const fs = require("fs")
+const path = require("path")
+
+function cleanCache() {
+    const catalystCacheDir = path.join(process.cwd(), "node_modules/catalyst-core")
+    const webpackCacheDir = path.join(catalystCacheDir, ".cache/webpack")
+    const loadableStats = path.join(catalystCacheDir, "loadable-stats.json")
+
+    let cleaned = false
+
+    if (fs.existsSync(webpackCacheDir)) {
+        fs.rmSync(webpackCacheDir, { recursive: true, force: true })
+        console.log("[Catalyst] Removed webpack filesystem cache.")
+        cleaned = true
+    }
+
+    if (fs.existsSync(loadableStats)) {
+        fs.rmSync(loadableStats)
+        console.log("[Catalyst] Removed loadable-stats.json.")
+        cleaned = true
+    }
+
+    if (!cleaned) {
+        console.log("[Catalyst] Nothing to clean — cache is already empty.")
+    } else {
+        console.log("[Catalyst] Clean complete. Next dev start will be a full rebuild.")
+    }
+}
+
+cleanCache()