Files
mxaccessgw/src/ZB.MOM.WW.MxGateway.Worker/WorkerApplication.cs
T
Joseph Doherty d9c60a78eb feat(worker): log exception messages and per-command start/end (mxaccessgw#184)
R21-O3: WorkerApplication.Run's failure lines logged only the exception
type. Each now also carries exception_message, scrubbed by the new
WorkerLogRedactor.RedactMessage: the value of any name=value / name: value
pair whose name looks sensitive and any mxgw_ API key token are replaced,
line breaks are flattened and the text is capped at 512 characters. The
AppDomain unhandled-exception hook stays type-only, since an exception
from an arbitrary thread can carry command values.

R21-O7: StaCommandDispatcher.ExecuteQueuedCommandAsync logs
WorkerCommandStarted (correlation id, method, queued_ms) and
WorkerCommandCompleted (status, HRESULT, elapsed_ms) when a CommandLogger
is set. IWorkerLogger has no Debug level, so the lines are opt-in through
MXGATEWAY_WORKER_LOG_COMMANDS=1|true (WorkerCommandLogging), which the
worker inherits from the gateway process environment. No payloads or
diagnostic messages are logged. Docs updated. (mxaccessgw#184)

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 13:01:58 -05:00

231 lines
9.2 KiB
C#

using System;
using System.Collections.Generic;
using System.IO;
using ZB.MOM.WW.MxGateway.Contracts.Proto;
using ZB.MOM.WW.MxGateway.Worker.Bootstrap;
using ZB.MOM.WW.MxGateway.Worker.Ipc;
namespace ZB.MOM.WW.MxGateway.Worker;
/// <summary>Entry point for the worker process.</summary>
public static class WorkerApplication
{
/// <summary>Initializes and runs the worker with default environment and logging.</summary>
/// <param name="args">Command-line arguments.</param>
/// <returns>The process exit code.</returns>
public static int Run(string[] args)
{
WorkerConsoleLogger logger = new(Console.Error);
// WRK-09: installed only on the production entry point (not the
// injectable overloads tests call) because the hook is process-global.
AppDomain.CurrentDomain.UnhandledException += (_, eventArgs) =>
HandleUnhandledException(
logger,
eventArgs.ExceptionObject,
eventArgs.IsTerminating,
Environment.Exit);
return Run(
args,
new EnvironmentVariableWorkerEnvironment(),
logger);
}
/// <summary>
/// Body of the worker's <c>AppDomain.CurrentDomain.UnhandledException</c>
/// hook. Logs one <c>WorkerUnhandledException</c> line and exits the
/// process with <see cref="WorkerExitCode.UnhandledException"/>, so the
/// gateway's launcher sees a defined worker exit code rather than the
/// CLR's crash code.
/// </summary>
/// <remarks>
/// Logs the exception type only — never its message or stack. An
/// exception reaching this hook can come from any thread, including a
/// COM callback or a command path whose message can carry tag values
/// or credentials, so it gets none of the content that
/// <see cref="Run(string[], IWorkerEnvironment, IWorkerLogger, IWorkerPipeClient)"/>'s
/// own catch blocks log through <see cref="WorkerLogRedactor.RedactMessage"/>
/// (those see only pipe-session failures). A logging failure is
/// swallowed so the exit always happens.
/// </remarks>
/// <param name="logger">Worker logger.</param>
/// <param name="exceptionObject">The unhandled exception object (not necessarily an <see cref="Exception"/>).</param>
/// <param name="isTerminating">Whether the CLR is terminating the process.</param>
/// <param name="exit">Process-exit action; <see cref="Environment.Exit"/> in production.</param>
internal static void HandleUnhandledException(
IWorkerLogger logger,
object? exceptionObject,
bool isTerminating,
Action<int> exit)
{
try
{
logger.Error("WorkerUnhandledException", new Dictionary<string, object?>
{
["exit_code"] = WorkerExitCode.UnhandledException,
["exception_type"] = exceptionObject?.GetType().FullName ?? "null",
["is_terminating"] = isTerminating,
});
}
catch
{
// Never let a logging failure skip the defined exit.
}
exit((int)WorkerExitCode.UnhandledException);
}
/// <summary>Initializes and runs the worker with custom environment and logging.</summary>
/// <param name="args">Command-line arguments.</param>
/// <param name="environment">Worker environment for resolving configuration.</param>
/// <param name="logger">Worker logger for diagnostics.</param>
/// <returns>The process exit code.</returns>
public static int Run(
string[] args,
IWorkerEnvironment environment,
IWorkerLogger logger)
{
return Run(
args,
environment,
logger,
new WorkerPipeClient(logger));
}
/// <summary>Parses arguments, bootstraps the handshake, and runs the worker until shutdown.</summary>
/// <param name="args">Command-line arguments.</param>
/// <param name="environment">Worker environment for resolving configuration.</param>
/// <param name="logger">Worker logger for diagnostics.</param>
/// <param name="pipeClient">Named pipe client for gateway communication.</param>
/// <returns>The process exit code.</returns>
public static int Run(
string[] args,
IWorkerEnvironment environment,
IWorkerLogger logger,
IWorkerPipeClient pipeClient)
{
if (args is null)
{
throw new ArgumentNullException(nameof(args));
}
if (environment is null)
{
throw new ArgumentNullException(nameof(environment));
}
if (logger is null)
{
throw new ArgumentNullException(nameof(logger));
}
if (pipeClient is null)
{
throw new ArgumentNullException(nameof(pipeClient));
}
try
{
WorkerOptionsParser parser = new(environment);
WorkerBootstrapResult result = parser.Parse(args);
if (!result.Succeeded)
{
logger.Error("WorkerBootstrapFailed", new Dictionary<string, object?>
{
["exit_code"] = result.ExitCode,
["errors"] = string.Join(";", result.Errors),
});
return (int)result.ExitCode;
}
WorkerOptions options = result.Options
?? throw new InvalidOperationException("Successful bootstrap result did not include worker options.");
logger.Information("WorkerBootstrapSucceeded", new Dictionary<string, object?>
{
["session_id"] = options.SessionId,
["pipe_name"] = options.PipeName,
["protocol_version"] = options.ProtocolVersion,
["nonce"] = options.Nonce,
});
pipeClient.RunAsync(options).GetAwaiter().GetResult();
logger.Information("WorkerPipeSessionCompleted", new Dictionary<string, object?>
{
["session_id"] = options.SessionId,
["pipe_name"] = options.PipeName,
["protocol_version"] = options.ProtocolVersion,
});
return (int)WorkerExitCode.Success;
}
catch (WorkerFrameProtocolException exception)
when (exception.ErrorCode == WorkerFrameProtocolErrorCode.EndOfStream)
{
// A read that hits end of stream means the gateway closed its end of the pipe — most
// often because the gateway process died. That is a lost connection, not a malformed
// frame, so it exits as PipeConnectionFailed alongside the IOException a broken pipe
// raises, rather than as ProtocolViolation.
logger.Error("WorkerPipeConnectionFailed", new Dictionary<string, object?>
{
["exit_code"] = WorkerExitCode.PipeConnectionFailed,
["error_code"] = exception.ErrorCode,
["exception_type"] = exception.GetType().FullName,
["exception_message"] = WorkerLogRedactor.RedactMessage(exception.Message),
});
return (int)WorkerExitCode.PipeConnectionFailed;
}
catch (WorkerFrameProtocolException exception)
{
logger.Error("WorkerPipeProtocolFailure", new Dictionary<string, object?>
{
["exit_code"] = WorkerExitCode.ProtocolViolation,
["error_code"] = exception.ErrorCode,
["exception_type"] = exception.GetType().FullName,
["exception_message"] = WorkerLogRedactor.RedactMessage(exception.Message),
});
return (int)WorkerExitCode.ProtocolViolation;
}
catch (WorkerEventQueueFaultException exception)
when (exception.Category == WorkerFaultCategory.QueueOverflow)
{
logger.Error("WorkerEventQueueOverflow", new Dictionary<string, object?>
{
["exit_code"] = WorkerExitCode.EventQueueOverflow,
["exception_type"] = exception.GetType().FullName,
["exception_message"] = WorkerLogRedactor.RedactMessage(exception.Message),
});
return (int)WorkerExitCode.EventQueueOverflow;
}
catch (Exception exception) when (exception is IOException or TimeoutException)
{
logger.Error("WorkerPipeConnectionFailed", new Dictionary<string, object?>
{
["exit_code"] = WorkerExitCode.PipeConnectionFailed,
["exception_type"] = exception.GetType().FullName,
["exception_message"] = WorkerLogRedactor.RedactMessage(exception.Message),
});
return (int)WorkerExitCode.PipeConnectionFailed;
}
catch (Exception exception)
{
logger.Error("WorkerBootstrapUnexpectedFailure", new Dictionary<string, object?>
{
["exit_code"] = WorkerExitCode.UnexpectedFailure,
["exception_type"] = exception.GetType().FullName,
["exception_message"] = WorkerLogRedactor.RedactMessage(exception.Message),
});
return (int)WorkerExitCode.UnexpectedFailure;
}
}
}