@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.2

package/dist/utility/logging/harper_logger.js

@@ -73,6 +73,8 @@ const packageUtils_js_1 = require("../../utility/packageUtils.js");
 const globals_js_1 = require("../../globals.js");
 const console_1 = require("console");
 const node_util_1 = require("node:util");
+const logRotation_ts_1 = require("./logRotation.js");
+const logGenerationCoordinator_ts_1 = require("./logGenerationCoordinator.js");
 const { isNativeError } = node_util_1.types;
 // store the native write function so we can call it after we write to the log file (and store it on process.stdout
 // because unit tests will create multiple instances of this module)
@@ -101,6 +103,17 @@ exports.OUTPUTS = {
 // Location of default config YAML.
 const DEFAULT_CONFIG_FILE = join(packageUtils_js_1.PACKAGE_ROOT, 'static', hdbTerms.HDB_DEFAULT_CONFIG_FILE);
 const CLOSE_LOG_FD_TIMEOUT = 10000;
+// Above the module-scope initLogSettings() call below, which reaches getFileLogger: a const
+// declared after it is still in its temporal dead zone when the file sink first reads one.
+const LOG_TIME_USAGE_THRESHOLD = 100;
+// How long to write straight to stdio after the log file refuses an append.
+const APPEND_RETRY_COOLDOWN = 5000;
+// Ceiling on how often a failing rotation may report itself; the failure repeats every check point.
+const ROTATION_REPORT_INTERVAL = 60000;
+const SET_ROTATION_POLICY = Symbol('setRotationPolicy');
+const GET_ROTATION_POLICY = Symbol('getRotationPolicy');
+const FILE_ROTATION_SOURCE = Symbol('fileRotationSource');
+const SERVICE_NAME = worker_threads_1.workerData?.name?.replace(/ /g, '-') || 'main';
 let logConsole;
 let log_to_file;
 let logToStdstreams;
@@ -159,7 +172,24 @@ function updateLogger(logger, logOptions, name, mainLoggerRef = mainLogger) {
     // rotation entirely (#1877). Excluded when `logger` IS mainLoggerRef: the fallback would just
     // reassign mainLogger.rotation to itself, making it impossible to ever clear main's rotation.
     const inheritedRotation = logOptions.rotation ?? (logger === mainLoggerRef ? undefined : mainLoggerRef?.rotation);
-    if (inheritedRotation && inheritedRotation === mainLoggerRef?.rotation) {
+    const loggerPolicy = logger[GET_ROTATION_POLICY]?.();
+    const mainPolicy = mainLoggerRef?.[GET_ROTATION_POLICY]?.();
+    const inheritsRotation = logOptions.rotation == null && logger !== mainLoggerRef;
+    const rotationSource = inheritsRotation ? mainPolicy?.source : loggerPolicy?.ownSource;
+    let path = logOptions.path;
+    if (path) {
+        if (!logOptions.root)
+            logOptions.root = pathModule.dirname(path);
+    }
+    else if (logOptions.root) {
+        path = join(logOptions.root, logName);
+    }
+    else {
+        path = mainLoggerRef.path;
+        if (!logOptions.root)
+            logOptions.root = pathModule.dirname(path);
+    }
+    if (inheritedRotation && inheritedRotation === mainLoggerRef?.rotation && path !== mainLoggerRef?.path) {
         // This logger has no rotation block of its own and is inheriting main's wholesale — but
         // inheriting `rotation.path` too would point this logger's archives at wherever main
         // archives to. If this logger's file lives on a different filesystem/volume than that
@@ -170,25 +200,18 @@ function updateLogger(logger, logOptions, name, mainLoggerRef = mainLogger) {
         // goes through `logOptions.rotation` above, not this fallback. Clone rather than mutate:
         // `inheritedRotation` is the literal object shared by mainLogger.rotation and every other
         // component that inherited it.
+        //
+        // Only when the paths differ. A logger writing to main's own file shares main's rotation
+        // state — file loggers are cached per path — so stripping there discards the operator's
+        // configured rotation.path for the main log itself, which no EXDEV risk justifies.
         const { path: _inheritedPath, ...rotationWithoutPath } = inheritedRotation;
-        logger.rotation = rotationWithoutPath;
+        setRotationPolicy(rotationWithoutPath);
     }
     else {
-        logger.rotation = inheritedRotation;
-    }
-    let path = logOptions.path;
-    if (path) {
-        if (!logOptions.root)
-            logOptions.root = pathModule.dirname(path);
-    }
-    else if (logOptions.root) {
-        path = join(logOptions.root, logName);
-    }
-    else {
-        path = mainLoggerRef.path;
-        if (!logOptions.root)
-            logOptions.root = pathModule.dirname(path);
+        setRotationPolicy(inheritedRotation);
     }
+    // After the rotation above: assigning `path` goes through the setter that rebuilds this path's
+    // file logger, and it reads `logger.rotation` as it stands at that moment.
     if (path)
         logger.path = path;
     else
@@ -199,6 +222,12 @@ function updateLogger(logger, logOptions, name, mainLoggerRef = mainLogger) {
     // if there is a configured tag or if a component is logging to default/main log path, use the component name as the tag
     // to differentiate it
     logger.tag = logOptions.tag ?? ((mainLoggerRef.path === logger.path || exports.externalLogger.path === logger.path) && name);
+    function setRotationPolicy(rotation) {
+        if (logger[SET_ROTATION_POLICY])
+            logger[SET_ROTATION_POLICY](rotation, rotationSource, inheritsRotation);
+        else
+            logger.rotation = rotation;
+    }
 }
 // creates a logger where the methods are only defined if they are within the log level.
 // Using this conditional logger means that every method call must be optional like log.trace?.('message),
@@ -233,7 +262,19 @@ async function updateLogSettings() {
         // TODO: Any way to differentiate changes that we can and can't handle?
         rootConfig.on('change', updateLogSettings);
     }
-    let rootConfigObject = rootConfig.config;
+    applyLogSettings(rootConfig.config);
+}
+// Separate from the watcher wiring above because the watcher it builds reads a process-wide path,
+// which leaves no way to exercise these settings against a given config.
+function applyLogSettings(rootConfigObject) {
+    // `ready` settles on every terminal read outcome, including ones that carry no config at all —
+    // see DESIGN.md, "Every terminal read outcome settles the barrier". Applying that as settings
+    // would not be "the defaults": `updateLogger` reads an absent `rotation` as rotation off and an
+    // absent `console` as console off, so an unreadable config would silently disable logging.
+    // What `initLogSettings()` established at startup stands until a real config arrives, which
+    // is why the watcher settles those outcomes with no config rather than an empty one.
+    if (!rootConfigObject || typeof rootConfigObject !== 'object')
+        return;
     const logOptions = rootConfigObject.logging ?? {};
     // Resolve relative paths against rootPath from the same config
     const rootPath = rootConfigObject.rootPath;
@@ -256,7 +297,9 @@ async function updateLogSettings() {
     for (const name in rootConfigObject) {
         // we now scan each component to see if it has logging individual configured
         const component = rootConfigObject[name];
-        if (component.logging) {
+        // `myComponent:` with nothing under it parses to null, and an async listener's TypeError
+        // escapes the watcher's emit guard as an unhandled rejection.
+        if (component?.logging) {
             updateLogger(mainLogger.forComponent(name), component.logging, name);
         }
         else if (mainLogger.hasComponent(name)) {
@@ -456,6 +499,8 @@ module.exports = {
     // we can start using the RootConfigWatcher
     start: updateLogSettings,
     startOnMainThread: updateLogSettings,
+    // Test-only: applies a config without the process-wide watcher `updateLogSettings` builds.
+    _applyLogSettingsForTests: applyLogSettings,
     errorToString,
     errorForLog,
     inspectForLog,
@@ -516,6 +561,14 @@ function logsAtLevel(level) {
 function initLogSettings(forceInit = false) {
     try {
         if (hdbProperties === undefined || forceInit) {
+            if (forceInit && mainLogger?.[SET_ROTATION_POLICY]) {
+                const currentPath = mainLogger.path;
+                if (currentPath) {
+                    const { ownSource } = mainLogger[GET_ROTATION_POLICY]();
+                    mainLogger[SET_ROTATION_POLICY](undefined, ownSource, false);
+                    mainLogger.path = currentPath;
+                }
+            }
             closeLogFile();
             const bootPropsFilePath = getPropsFilePath();
             let properties = (0, assignCmdEnvVariables_ts_1.default)(['ROOTPATH']);
@@ -692,14 +745,18 @@ function suppressLogging(callback) {
         loggingEnabled = true;
     }
 }
-const SERVICE_NAME = worker_threads_1.workerData?.name?.replace(/ /g, '-') || 'main';
 // these are used to store information about the current service and tag so we can prepend them to the log during
 // the writes, without having to pass the information through the Console instance
 let currentLevel = 'info'; // default is info
 let currentServiceName;
 let currentTag;
 function createLogger(options = {}) {
-    let { path: logFilePath, level: logLevel, stdStreams: logToStdstreams, rotation, isExternalInstance, writeToLog, component, } = options;
+    let { path: logFilePath, level: logLevel, stdStreams: logToStdstreams, rotation, isExternalInstance, writeToLog, component, rotationSource, rotationInherited = false, } = options;
+    const ownRotationSource = Symbol('rotationPolicySource');
+    let currentRotationSource = rotationSource ?? ownRotationSource;
+    let previousRotationSource;
+    let currentRotationInherited = rotationInherited;
+    let rotationChangeIsAuthoritative = rotation !== undefined;
     if (!logLevel)
         logLevel = 'info';
     let level = typeof logLevel === 'number' ? logLevel : LOG_LEVEL_HIERARCHY[logLevel];
@@ -750,7 +807,8 @@ function createLogger(options = {}) {
         else if (logToStdstreams)
             process.stderr.write(log);
     }
-    let logToFile = logFilePath && getFileLogger(logFilePath, rotation, isExternalInstance);
+    let logToFile = logFilePath && getFileLogger(logFilePath, rotation, isExternalInstance, rotationPolicy());
+    rotationPolicyApplied();
     function logPrepend(write) {
         return {
             write(log) {
@@ -772,6 +830,14 @@ function createLogger(options = {}) {
         stderr: logPrepend(writeToLog ?? logStdErr),
         colorMode: (logToStdstreams && colorMode) || false,
     }, level);
+    logger[SET_ROTATION_POLICY] = function (newRotation, source = ownRotationSource, inherited = false) {
+        previousRotationSource = currentRotationSource;
+        currentRotationSource = source ?? ownRotationSource;
+        currentRotationInherited = inherited;
+        rotationChangeIsAuthoritative = true;
+        logger.rotation = newRotation;
+    };
+    logger[GET_ROTATION_POLICY] = () => ({ ownSource: ownRotationSource, source: currentRotationSource });
     updateConditional(logger);
     logger.path = logFilePath;
     Object.defineProperty(logger, 'path', {
@@ -780,7 +846,11 @@ function createLogger(options = {}) {
         },
         set(path) {
             logFilePath = path;
-            logToFile = getFileLogger(logFilePath, logger.rotation, isExternalInstance);
+            if (!logFilePath)
+                return;
+            logToFile = getFileLogger(logFilePath, logger.rotation, isExternalInstance, rotationPolicy());
+            logger.closeLogFile = logToFile.closeLogFile;
+            rotationPolicyApplied();
             if (isExternalInstance)
                 writeToLogFile = logToFile;
         },
@@ -794,12 +864,15 @@ function createLogger(options = {}) {
             let componentLogger = components.get(name);
             if (!componentLogger) {
                 const protoLogger = isExternal ? exports.externalLogger : logger;
+                const protoRotationPolicy = protoLogger[GET_ROTATION_POLICY]?.();
                 componentLogger = createLogger({
                     path: protoLogger.path,
                     level: protoLogger.level,
                     stdStreams: protoLogger.logToStdstreams,
                     isExternalInstance: isExternal || name === 'external',
                     rotation: protoLogger.rotation,
+                    rotationSource: protoRotationPolicy?.source,
+                    rotationInherited: true,
                     writeToLog,
                     component: true,
                 });
@@ -816,35 +889,80 @@ function createLogger(options = {}) {
         logger.components = components;
     }
     return logger;
+    function rotationPolicy() {
+        return {
+            source: currentRotationSource,
+            previousSource: previousRotationSource,
+            inherited: currentRotationInherited,
+            authoritative: rotationChangeIsAuthoritative,
+        };
+    }
+    function rotationPolicyApplied() {
+        previousRotationSource = currentRotationSource;
+        rotationChangeIsAuthoritative = false;
+    }
 }
-const LOG_TIME_USAGE_THRESHOLD = 100;
-// How long to write straight to stdio after the log file refuses an append.
-const APPEND_RETRY_COOLDOWN = 5000;
 /**
  * Get the file logger for the given path. If it doesn't exist, create it.
  * @param path
  * @param isExternalInstance
  * @return {any}
  */
-function getFileLogger(path, rotation, isExternalInstance) {
+function getFileLogger(path, rotation, isExternalInstance, rotationPolicy) {
     let logger = fileLoggers.get(path);
     let logFD, loggedFDError, loggedAppendError, logTimer, retryAppendAfter;
     let logBuffer;
+    let rotationProblemNotice;
     let logTimeUsage = 0;
+    let rotationGuard, logFDIdentity, nextRotationReport = 0;
     if (!logger) {
         logger = logToFile;
         logger.closeLogFile = closeLogFile;
+        // The guard has to be installed through the live closure: later calls for this path get the
+        // cached logger back, and their own logFD/logBuffer are dead.
+        logger.installRotationGuard = installRotationGuard;
         logger.path = path;
         fileLoggers.set(path, logger);
-    }
-    if (worker_threads_1.isMainThread && JSON.stringify(rotation) !== JSON.stringify(logger.rotation)) {
+        // Registered by the sink, not by the size guard: a thread that writes this file but has no
+        // guard (no maxSize, or rotation driven only by interval) still holds a descriptor, and an
+        // answer from it has to mean "released" rather than only "handler ran".
+        (0, logGenerationCoordinator_ts_1.registerLogSink)(path, { identity: () => logFDIdentity, close: closeLogFile });
+    }
+    const currentSource = logger[FILE_ROTATION_SOURCE];
+    const sameSource = currentSource === rotationPolicy.source;
+    const replacesPreviousSource = currentSource !== undefined && currentSource === rotationPolicy.previousSource;
+    const canInstall = rotation !== undefined &&
+        (!rotationPolicy.inherited || currentSource === undefined || sameSource || replacesPreviousSource);
+    const canClear = rotation === undefined && rotationPolicy.authoritative && (sameSource || replacesPreviousSource);
+    let reconfigured = false;
+    if (canInstall) {
+        logger[FILE_ROTATION_SOURCE] = rotationPolicy.source;
+        reconfigured = JSON.stringify(rotation) !== JSON.stringify(logger.rotation);
+    }
+    if (reconfigured) {
         logger.rotation = rotation;
+        // Every writing thread, and synchronously: request logging is produced by the HTTP workers, and
+        // at the rates that make maxSize matter a deferred guard misses megabytes before it exists.
+        logger.installRotationGuard(rotation);
+    }
+    else if (canClear) {
+        logger.rotation = undefined;
+        logger[FILE_ROTATION_SOURCE] = undefined;
+        logger.installRotationGuard(undefined);
+        reconfigured = true;
+    }
+    if (worker_threads_1.isMainThread && reconfigured) {
         setTimeout(() => {
-            logger.rotator?.end();
-            if (!rotation)
-                return;
-            const { logRotator } = require('./logRotator');
+            // Everything inside the try: a throw from a timer callback is unhandled, and neither
+            // require('./logRotator') (which reaches environmentManager's synchronous init) nor a
+            // rotator teardown may take the process down over log rotation (#847).
             try {
+                const previousRotator = logger.rotator;
+                logger.rotator = undefined;
+                previousRotator?.end();
+                if (!rotation)
+                    return;
+                const { logRotator } = require('./logRotator');
                 logger.rotator = logRotator({
                     logger,
                     ...rotation,
@@ -856,6 +974,50 @@ function getFileLogger(path, rotation, isExternalInstance) {
         }, 100);
     }
     return logger;
+    function installRotationGuard(newRotation) {
+        rotationGuard = undefined;
+        if (!newRotation || newRotation.enabled === false)
+            return;
+        const maxBytes = (0, logRotation_ts_1.parseMaxSize)(newRotation.maxSize);
+        if (!maxBytes) {
+            if (newRotation.maxSize != null)
+                reportRotationProblem(`logging.rotation.maxSize: ${logRotation_ts_1.INVALID_MAX_SIZE_MSG}`);
+            return;
+        }
+        try {
+            rotationGuard = (0, logRotation_ts_1.createRotationGuard)({
+                logPath: path,
+                maxBytes,
+                rotatedLogDir: (0, logRotation_ts_1.resolveRotatedLogDir)(path, newRotation.path),
+                // From the rotation block rather than environmentManager (which logRotator still reads):
+                // environmentManager imports this module, so it cannot be reached from the write path.
+                compress: newRotation.compress,
+                getLogIdentity: () => logFDIdentity,
+                closeLogFile,
+                report: reportRotationProblem,
+                onRotated(archivePath) {
+                    // Same shape as every other line in the file: written straight to the sink, this
+                    // bypasses the prefix createLogger's logPrepend adds, and readLog parses by level.
+                    logToFile(`[${SERVICE_NAME}/${worker_threads_1.threadId}] [notify]: hdb.log rotated, old log moved to ${archivePath}`);
+                },
+            });
+        }
+        catch (error) {
+            reportRotationProblem(`log rotation is disabled for ${path}: ${error}`);
+        }
+    }
+    function reportRotationProblem(text) {
+        // Straight to stdio, never back through this sink: the sink is what rotation is failing on.
+        // Rate-limited rather than once-only, so a later, different failure is still reported.
+        if (nextRotationReport > performance.now())
+            return;
+        nextRotationReport = performance.now() + ROTATION_REPORT_INTERVAL;
+        const message = `Harper log rotation problem — ${text}`;
+        // Scripted services discard stdio. Preserve the warning in the active file on the next
+        // successful append as well, without recursing through the rotation guard.
+        rotationProblemNotice = `${new Date().toISOString()} [${SERVICE_NAME}/${worker_threads_1.threadId}] [error]: ${message}\n`;
+        writeToStdioDirectly(process.stderr, `${message}\n`);
+    }
     function logToFile(log) {
         let entry = `${new Date().toISOString()} ${log}${log.endsWith('\n') ? '' : '\n'}`;
         if (logBuffer) {
@@ -885,18 +1047,29 @@ function getFileLogger(path, rotation, isExternalInstance) {
     }
     // this is called on a timer, and will write the log buffer to the file
     function logQueuedData(entry) {
-        openLogFile(undefined);
         const payload = logBuffer ? logBuffer.join('') : entry;
+        // Released before anything can re-enter: the rotation notice is written from inside the append
+        // below, and a re-entrant flush still holding this batch would write it twice.
+        logBuffer = null;
+        if (payload === undefined)
+            return;
         // A file that just refused a write will refuse the next one too, and every attempt costs a
         // failed syscall plus a thrown error on whatever path is logging - which, on a full volume,
         // is the request path at full rate. Go straight to stdio until the cooldown expires.
-        if (logFD && !(retryAppendAfter > performance.now())) {
+        // Opened after the guard: a guard recovering by rotation closes this descriptor first.
+        const mayAppend = !(retryAppendAfter > performance.now()) && (rotationGuard?.beforeAppend() ?? true);
+        openLogFile(undefined);
+        if (logFD && mayAppend) {
             let startTime = performance.now();
             try {
-                fs.appendFileSync(logFD, payload);
+                const appendPayload = rotationProblemNotice ? rotationProblemNotice + payload : payload;
+                const appendBuffer = Buffer.from(appendPayload);
+                fs.appendFileSync(logFD, appendBuffer);
+                rotationProblemNotice = undefined;
                 // Both cleared, so a volume that fills again months later reports itself again
                 retryAppendAfter = undefined;
                 loggedAppendError = false;
+                rotationGuard?.recordWrite(appendBuffer.length);
             }
             catch (error) {
                 retryAppendAfter = performance.now() + APPEND_RETRY_COOLDOWN;
@@ -910,7 +1083,6 @@ function getFileLogger(path, rotation, isExternalInstance) {
                     writeToStdioDirectly(process.stderr, `Harper cannot write to its log file: ${error}\n`);
                 }
                 writeToStdioDirectly(process.stdout, payload);
-                logBuffer = null;
                 return;
             }
             let endTime = performance.now();
@@ -920,8 +1092,6 @@ function getFileLogger(path, rotation, isExternalInstance) {
         }
         else
             writeToStdioDirectly(process.stdout, payload);
-        if (logBuffer)
-            logBuffer = null;
     }
     function closeLogFile(_unused) {
         try {
@@ -929,6 +1099,7 @@ function getFileLogger(path, rotation, isExternalInstance) {
         }
         catch { }
         logFD = null;
+        logFDIdentity = null;
         if (isExternalInstance)
             mainLogFd = null;
     }
@@ -936,6 +1107,15 @@ function getFileLogger(path, rotation, isExternalInstance) {
         if (!logFD) {
             try {
                 logFD = fs.openSync(path, 'a');
+                // Which generation this descriptor belongs to, recorded once here so the size guard's
+                // checkpoint needs a single pathname stat to tell whether the file has moved under it.
+                try {
+                    const opened = fs.fstatSync(logFD);
+                    logFDIdentity = { ino: opened.ino, dev: opened.dev };
+                }
+                catch {
+                    logFDIdentity = null;
+                }
                 if (isExternalInstance)
                     mainLogFd = logFD;
             }