Windows Native Service — Live E2E¶
Status summary
| Evidence | Value |
|---|---|
| IMPLEMENTED | YES |
| AUTOMATED TESTED | YES |
| LIVE E2E VALIDATED | YES |
Evidence note: Windows lab, August 2026. The PASS results on this page were actually executed in that lab environment and accepted as successful. Unit/script AUTOMATED PASS results do not substitute for live E2E; the items listed here are live.
Operations reference: Windows service installation, Update and rollback, Installer validation matrix.
Live E2E results (45 PASS)¶
| # | Scenario | Status | Notes |
|---|---|---|---|
| 1 | Clean install | PASS | |
| 2 | Administrator validation | PASS | |
| 3 | Windows AMD64 validation | PASS | |
| 4 | Repository root detection | PASS | |
| 5 | .env detection/validation |
PASS | |
| 6 | Git prerequisite | PASS | |
| 7 | Go prerequisite | PASS | |
| 8 | MongoDB Windows service Running | PASS | MongoDB is not installed by the installer |
| 9 | MongoDB TCP 27017 | PASS | |
| 10 | HTTP port availability | PASS | |
| 11 | go mod download / verify | PASS | |
| 12 | go vet | PASS | |
| 13 | go test ./... -count=1 | PASS | |
| 14 | Windows binary build | PASS | |
| 15 | Application check |
PASS | |
| 16 | Runtime backup | PASS | |
| 17 | Runtime binary deployment | PASS | |
| 18 | Runtime config deployment | PASS | |
| 19 | MongoDB migrations | PASS | Migration is not rolled back |
| 20 | Native Windows Service registration | PASS | |
| 21 | Correct exe/argv ImagePath registration | PASS | |
| 22 | LocalService account | PASS | |
| 23 | Automatic Delayed Start | PASS | |
| 24 | MongoDB service dependency | PASS | |
| 25 | Recovery: 5s / 10s / 30s; reset 86400 | PASS | |
| 26 | Windows Firewall Domain/Private | PASS | |
| 27 | Service start | PASS | |
| 28 | health/live | PASS | |
| 29 | health/ready | PASS | |
| 30 | Deployment metadata | PASS | |
| 31 | Build metadata: version, commit, build UTC, Go version, OS, arch | PASS | |
| 32 | Windows reboot | PASS | After reboot without manual Start-Service: MongoDB=Running, IQVIntegrationAPI=Running, Port=Listening, health/live=alive, health/ready=ready |
| 33 | NO-OP update | PASS | Same deployed/target commit: no backup, no build, no migration, no restart. Measurement: Before backups=2, After backups=2 |
| 34 | ForceRedeploy | PASS | Real deployment; backup +1; service restarted; health passed |
| 35 | Runtime config preservation during update | PASS | SHA256 unchanged |
| 36 | Automatic update rollback | PASS | LAB-only TestFailAt=AfterBinarySwap: Service stopped → Binary swap → Injected failure → Automatic rollback → Binary restored → Config restored → Service automatically restarted → health/live OK → health/ready OK |
| 37 | Rollback process exit code | PASS | Failed deployment + successful rollback → Process ExitCode = 11 (EXIT_SERVICE_UPDATE). Even when rollback succeeds, update does not return success exit code 0 |
| 38 | Failed deployment metadata preservation | PASS | Failed deployment was not written as successful metadata |
| 39 | status.ps1 | PASS | Service Running, Delayed Auto Start, LocalService, PID, Version, Commit, Port, MongoDB, health/live, health/ready, Firewall, recent error log; ExitCode = 0 |
| 40 | Safe uninstall | PASS | Service removed, Firewall removed, Port closed; Runtime/Binary/Config/Logs/Backups/Metadata preserved; MongoDB untouched |
| 41 | Preserved Runtime Reinstall | PASS | Scenario=PreservedRuntimeReinstall; Config Preserved=True, Copied=False; SHA256 before/after unchanged; Service re-registered; Health passed |
| 42 | ServiceRepair / install idempotency | PASS | Re-run install.ps1 while service Running; Scenario=ServiceRepair; Port ownership: OwningProcess == Win32_Service.ProcessId; Own listener is not a false conflict; Service stopped → Port released → Binary deployed → Config preserved → Existing service detected → No duplicate service → No duplicate firewall → Service restarted → Health passed |
| 43 | Firewall idempotency | PASS | Before rules=1, After rules=1 |
| 44 | Config hash preservation ServiceRepair | PASS | Before SHA256 == After SHA256 |
| 45 | Step counter | PASS | Installer [1/29] … [29/29] consistent |
Issues Found During Validation¶
Real defects detected and fixed during Windows lab E2E.
| ID | Problem | Detected | Fixed | Automated regression | Live E2E retest |
|---|---|---|---|---|---|
| A | Untagged repository: git describe fatal → PowerShell NativeCommandError. Fix: tag optional; dev-<sha> fallback |
Yes | Yes | Yes (GitMetadata.Tests.ps1) |
PASS |
| B | Windows ImagePath whole-command quoting: exe+args in a single quote. Fix: separate CreateService exe and argv parameters | Yes | Yes | Yes (imagepath_test.go / related) |
PASS |
| C | Runtime config self-copy: config\.env Copy-Item onto itself. Fix: update config preserve + path equality protection |
Yes | Yes | Yes (Install/Update script tests) | PASS |
| D | After update failure service Stopped; no transactional rollback. Fix: automatic rollback | Yes | Yes | Yes (UpdateRollback.Tests.ps1) |
PASS (TestFailAt) |
| E | Duplicate dirty warning. Fix: single centralized warning | Yes | Yes | Partial / script coverage | PASS |
| F | status.ps1 $PID: PowerShell built-in PID is read-only. Fix: ServiceProcessId |
Yes | Yes | Yes (Status.Tests.ps1) |
PASS |
| G | Preserved-runtime reinstall ImagePath ERROR_INVALID_PARAMETER: redundant UpdateConfig after CreateService. Fix: removed duplicate ImagePath mutation |
Yes | Yes | Yes (Install.Tests.ps1) |
PASS |
| H | Reinstall config overwrite. Fix: preserve by default; -ReplaceRuntimeConfig explicit |
Yes | Yes | Yes (Install.Tests.ps1) |
PASS |
| I | ServiceRepair own-port false conflict: treated as “port occupied” only. Fix: SCM ProcessId == TCP OwningProcess | Yes | Yes | Yes (PortOwnership.Tests.ps1) |
PASS |
| J | Step counter mismatch. Fix: 29 Write-Step / 29 denominator |
Yes | Yes | Install script review | PASS |
Exit codes (Windows service scripts)¶
Source: scripts/windows/service/Common.ps1
| Code | Constant | Meaning |
|---|---|---|
| 0 | EXIT_SUCCESS |
Success |
| 1 | EXIT_ADMIN_REQUIRED |
Administrator required |
| 2 | EXIT_ENV_INVALID |
Invalid environment |
| 3 | EXIT_PREREQUISITE |
Prerequisite |
| 4 | EXIT_REPO_DIRTY |
Dirty repo / git error |
| 5 | EXIT_DEP_DOWNLOAD |
Dependency download |
| 6 | EXIT_VET_TEST |
Vet/test |
| 7 | EXIT_BUILD |
Build |
| 8 | EXIT_CHECK_FAILED |
Application check |
| 9 | EXIT_BACKUP |
Backup |
| 10 | EXIT_MIGRATION |
Migration |
| 11 | EXIT_SERVICE_UPDATE |
Service update / status unhealthy install state |
| 12 | EXIT_FIREWALL |
Firewall |
| 13 | EXIT_HEALTH |
Health |
| 14 | EXIT_ROLLBACK |
Rollback failed |
| 15 | EXIT_PORT_CONFLICT |
Port conflict |
| 16 | EXIT_DOCKER_NA |
Docker N/A |
| 17 | EXIT_SYSTEMD_NA |
systemd N/A |