Architecture

Project Structure

JenkinsAsService/
├── src/
│   └── JenkinsAsService/
│       ├── JenkinsAsService.csproj    # .NET 10 Worker Service
│       ├── Program.cs                 # Host builder, Serilog config, DI, OTel
│       ├── Properties/AssemblyInfo.cs # Explicit assembly attributes (for Codacy)
│       ├── ServiceSettings.cs         # Jenkins config POCO
│       ├── TelemetrySettings.cs       # OpenTelemetry config POCO
│       ├── SecretMode.cs              # Enum: Unprotected, Dpapi, EnvironmentVariable, CredentialManager
│       ├── ISecretResolver.cs         # Secret resolution abstraction
│       ├── SecretResolver.cs          # DPAPI / CredMgr / EnvVar / plaintext resolver
│       ├── SecretWriter.cs            # Writes appsettings.json; stores secret per mode
│       ├── UpdateSecretCommand.cs     # CLI subcommand: update-secret
│       ├── JenkinsAgentWorker.cs      # BackgroundService — validation, process, watchdog, OTel
│       ├── IJarDownloader.cs          # Jar download abstraction
│       ├── HttpJarDownloader.cs       # HTTP jar downloader with ETag caching
│       ├── IConnectivityChecker.cs    # Connectivity check abstraction
│       ├── TcpConnectivityChecker.cs  # TCP connectivity implementation
│       ├── appsettings.json           # Configuration file
│       └── packages.lock.json         # Locked NuGet restore
├── src/
│   └── JenkinsAsService.Installer/    # WiX v5 MSI installer project
├── tests/
│   └── JenkinsAsService.Tests/        # 59 xUnit unit tests
├── .github/
│   └── workflows/                     # CI/CD: build, test, 6 security scans, release
├── ReadMe.md
├── Security.md
└── LICENSE                            # BSD 3-Clause

Runtime File Layout (Installed)

C:\Program Files\Jenkins\
├── JenkinsAsService.exe     # Self-contained .NET 10 executable
├── appsettings.json         # Configuration
├── agent.jar                # Downloaded from Jenkins (ETag cached)
├── agent.jar.etag           # Stored ETag for conditional GET
├── agent.log                # Serilog rolling log file
├── agent_001.log            # Rolled log (size-based)
├── agent_002.log            # Older rolled log
├── agent_003.log            # Oldest kept log
└── remoting/                # Jenkins remoting work directory

Service Lifecycle

ExecuteAsync (Start)

JenkinsAgentWorker.ExecuteAsync() is the BackgroundService entry point:

1. Log session banner — === SERVICE STARTING (PID: ...) ===
2. ValidateSettings() — Checks mandatory fields, rejects default-port URLs
3. ResolveJavaPath() — Checks JavaPath config → JAVA_HOME → JAVA_HOME\bin
4. TestConnectivityAsync() — Delegates to IConnectivityChecker (TCP with 2s timeout)
5. IJarDownloader.DownloadAsync() — Conditional GET with Polly resilience
6. StartAgentProcess() — Launches Java via Process with async output parsing
7. RunWatchdogAsync() — Enters monitoring loop

StopAsync

1. Logs the stop request
2. Kills the Java process tree (Process.Kill(entireProcessTree: true))
3. Logs confirmation

Execution Model

The Java process is managed directly via System.Diagnostics.Process:

• ProcessStartInfo.ArgumentList for safe argument passing (no shell interpretation)
• RedirectStandardOutput + RedirectStandardError with async event handlers
• OutputDataReceived / ErrorDataReceived → ParseAgentOutput():
  • INFO: ... → LogInformation
  • WARNING: ... → LogWarning
  • SEVERE: ... → LogError
  • Everything else → LogInformation (or LogDebug in debug mode)

Watchdog & Auto-Recovery

RunWatchdogAsync() is event-driven — it awaits Task.WhenAny(exitTask, Task.Delay(StabilityMs)) where exitTask is a TaskCompletionSource completed by the process.Exited event. No polling.

flowchart TD
    A[Watchdog Loop] -->|Await exit signal OR 60s stability timer| B{exitTask completed?}
    B -->|No — 60s elapsed, agent still alive| C{retryCount > 0?}
    C -->|Yes| D[Reset retry counter, log stability]
    C -->|No| A
    D --> A
    B -->|Yes — process exited| E[Log SEVERE count, capture exit code, KillAgent]
    E --> F{MaxRetries exceeded?}
    F -->|Yes| G[Log error and stop]
    F -->|No| H["Wait with exponential backoff (10s to 300s)"]
    H --> I[Test TCP connectivity]
    I -->|Unreachable| J[Log warning, reset TCS, loop]
    J --> A
    I -->|OK| K["ETag conditional GET agent.jar"]
    K --> L[Start new process, subscribe Exited before Start]
    L --> M["_restartCounter.Add(1)"]
    M --> A

• Exit detection: instant via process.Exited → TCS.TrySetResult(), subscribed before process.Start()
• Fast-crash guard: After Start(), if process.HasExited is already true, TCS.TrySetResult() is called defensively
• Failed recovery: If connectivity check or download fails, a fresh uncompleted TCS is assigned so the loop waits properly instead of spinning
• Backoff: 10s → 20s → 40s → 80s → ... capped at 300s
• Retry reset: After 60s of stability, retry counter resets to 0
• MaxRetries: 0 = infinite (default)
• SEVERE counter: _severeCount is Interlocked.Increment-ed per SEVERE line; read and reset via Interlocked.Exchange on each exit

Logging (Serilog)

Enrichers: ProcessId, MachineName, EnvironmentName.

Output format: <PID> | <datetime> | <Level> | <message>

HTTP Resilience

The HttpClient used by HttpJarDownloader is registered as a named client ("JarDownloader") with AddStandardResilienceHandler() from Microsoft.Extensions.Http.Resilience. This provides automatic retry, circuit breaker, and timeout. Separate from the watchdog's recovery loop.

Constants

Dependency Injection

Testing

59 unit tests in tests/JenkinsAsService.Tests/:

Test Stack