Agent: system SQLite (glibc fix) + fail-soft store + PATH on linux/macOS #13

Merged
gsadmin merged 2 commits from dev into main 2026-08-10 17:56:08 +00:00
5 changed files with 191 additions and 37 deletions
+5
View File
@@ -46,6 +46,11 @@
<PackageVersion Include="System.Management" Version="10.0.10" />
<PackageVersion Include="System.Security.Cryptography.ProtectedData" Version="10.0.10" />
<PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.10" />
<!-- Portable agent uses the host's system SQLite (no bundled e_sqlite3
native, which otherwise floors glibc at 2.33 — breaks Ubuntu 20.04 /
Debian 11). Windows/server keep the bundled e_sqlite3. -->
<PackageVersion Include="Microsoft.Data.Sqlite.Core" Version="10.0.10" />
<PackageVersion Include="SQLitePCLRaw.bundle_sqlite3" Version="2.1.11" />
<!-- Installer -->
<PackageVersion Include="WixToolset.Util.wixext" Version="5.0.2" />
+4 -2
View File
@@ -544,8 +544,10 @@ the Windows service APIs (`advapi32` / `ServiceController`) — never `sc.exe`.
**Linux and macOS**: the same commands work with the portable `executer-agent`
binary (`install` writes a systemd unit `executer-agent` or a launchd daemon
`info.executer.agent`). Configuration lives in `/etc/executer/agent.json`
instead of the registry, credentials under `/var/lib/executer` (mode 600).
`info.executer.agent`, and symlinks the binary into `/usr/local/bin` so
`executer-agent` is on `PATH`; `remove` deletes both). Configuration lives in
`/etc/executer/agent.json` instead of the registry, credentials under
`/var/lib/executer` (mode 600).
On startup the agent idempotently installs PowerShell 7 when missing (Homebrew
on macOS, the official install script on Linux) — scripts run via the embedded
PowerShell SDK either way, so this only matters for operator convenience.
+7 -1
View File
@@ -35,7 +35,6 @@
<PackageReference Include="Microsoft.PowerShell.SDK" />
<PackageReference Include="NATS.Net" />
<PackageReference Include="NATS.NKeys" />
<PackageReference Include="Microsoft.Data.Sqlite" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net10.0-windows'">
@@ -43,10 +42,17 @@
<PackageReference Include="System.ServiceProcess.ServiceController" />
<PackageReference Include="System.Management" />
<PackageReference Include="System.Security.Cryptography.ProtectedData" />
<!-- Bundled e_sqlite3: fine on Windows (no glibc floor). -->
<PackageReference Include="Microsoft.Data.Sqlite" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
<PackageReference Include="Microsoft.Extensions.Hosting.Systemd" />
<!-- linux/macOS: bind to the host's own libsqlite3 rather than shipping a
bundled native, so we never floor glibc (Ubuntu 20.04 / Debian 11
carry glibc 2.31 < the 2.33 the bundled e_sqlite3 requires). -->
<PackageReference Include="Microsoft.Data.Sqlite.Core" />
<PackageReference Include="SQLitePCLRaw.bundle_sqlite3" />
</ItemGroup>
<ItemGroup>
+68 -2
View File
@@ -14,14 +14,80 @@ public static class UnixServiceLifecycle
private const string SystemdUnit = "executer-agent";
private const string LaunchdLabel = "info.executer.agent";
// On the default PATH on both linux and macOS, and writable (unlike /usr/bin
// on macOS under SIP). Mirrors the Windows installer's PATH entry so
// `executer-agent` / `which executer-agent` work from any shell.
private const string PathLink = "/usr/local/bin/executer-agent";
private static string ExePath =>
Environment.ProcessPath ?? throw new InvalidOperationException("Cannot determine the executable path.");
public static int Install()
=> OperatingSystem.IsMacOS() ? InstallLaunchd() : InstallSystemd();
{
var code = OperatingSystem.IsMacOS() ? InstallLaunchd() : InstallSystemd();
if (code == 0)
{
LinkOnPath();
}
return code;
}
public static int Remove()
=> OperatingSystem.IsMacOS() ? RemoveLaunchd() : RemoveSystemd();
{
UnlinkFromPath();
return OperatingSystem.IsMacOS() ? RemoveLaunchd() : RemoveSystemd();
}
/// <summary>
/// Symlink the agent onto PATH. Best-effort: a failure here (e.g. not root,
/// read-only /usr/local) never fails the install. Replaces only a prior
/// symlink of ours — never an unrelated real file at that path.
/// </summary>
private static void LinkOnPath()
{
try
{
Directory.CreateDirectory("/usr/local/bin");
var existing = new FileInfo(PathLink);
if (existing.Exists || existing.LinkTarget is not null)
{
if (existing.LinkTarget is null)
{
Console.Error.WriteLine($"warning: {PathLink} exists and is not a symlink; leaving it in place.");
return;
}
File.Delete(PathLink);
}
File.CreateSymbolicLink(PathLink, ExePath);
Console.WriteLine($"Linked {PathLink} -> {ExePath}");
}
catch (Exception ex)
{
Console.Error.WriteLine($"warning: could not add executer-agent to PATH ({ex.Message}).");
}
}
private static void UnlinkFromPath()
{
try
{
// Remove only a symlink that points at our install, so an unrelated
// /usr/local/bin/executer-agent is left untouched.
if (new FileInfo(PathLink).LinkTarget is { } target
&& (target == ExePath || target.Contains("/executer/", StringComparison.Ordinal)))
{
File.Delete(PathLink);
}
}
catch (Exception ex)
{
Console.Error.WriteLine($"warning: could not remove executer-agent from PATH ({ex.Message}).");
}
}
public static int Start()
=> OperatingSystem.IsMacOS()
+107 -32
View File
@@ -1,4 +1,5 @@
using Microsoft.Data.Sqlite;
using Microsoft.Extensions.Logging;
using Shared.Infrastructure.Constants;
namespace Agent.Storage;
@@ -7,47 +8,77 @@ namespace Agent.Storage;
/// Durable local record of handled job ids so JetStream redelivery or agent
/// restart never executes the same script twice. Retains the most recent
/// completed entries (bounded) in a lightweight SQLite database.
///
/// If SQLite cannot initialize (e.g. the host lacks a usable system libsqlite3),
/// the store falls back to an in-memory record so the agent still runs — job
/// idempotency then holds within the process lifetime but not across restarts.
/// The failure is logged once at startup rather than crashing the service.
/// </summary>
public sealed class JobHistoryStore : IDisposable
{
private readonly SqliteConnection connection;
private readonly SqliteConnection? connection;
private readonly Lock writeLock = new();
public JobHistoryStore()
: this(Path.Combine(Branding.AgentProgramDataDirectory, Branding.JobHistoryFileName))
// In-memory fallback (used only when connection is null). handledOrder keeps
// insertion order for bounded pruning; handledSet backs membership tests.
private readonly HashSet<Guid>? handledSet;
private readonly Queue<Guid>? handledOrder;
private readonly Dictionary<string, DownloadCacheEntry>? downloadCacheMem;
public JobHistoryStore(ILogger<JobHistoryStore> logger)
: this(Path.Combine(Branding.AgentProgramDataDirectory, Branding.JobHistoryFileName), logger)
{
}
public JobHistoryStore(string databasePath)
public JobHistoryStore(string databasePath, ILogger<JobHistoryStore>? logger = null)
{
var directory = Path.GetDirectoryName(databasePath);
if (!string.IsNullOrEmpty(directory))
try
{
Directory.CreateDirectory(directory);
var directory = Path.GetDirectoryName(databasePath);
if (!string.IsNullOrEmpty(directory))
{
Directory.CreateDirectory(directory);
}
var sqlite = new SqliteConnection($"Data Source={databasePath}");
sqlite.Open();
using var command = sqlite.CreateCommand();
command.CommandText = """
CREATE TABLE IF NOT EXISTS HandledJobs (
JobId TEXT PRIMARY KEY,
AcceptedUtc TEXT NOT NULL,
CompletedUtc TEXT NULL,
State TEXT NULL
);
CREATE TABLE IF NOT EXISTS DownloadCache (
DestinationPath TEXT PRIMARY KEY,
ObjectKey TEXT NULL,
ETag TEXT NULL,
Sha256 TEXT NULL,
SizeBytes INTEGER NULL,
DownloadedUtc TEXT NOT NULL
);
""";
command.ExecuteNonQuery();
connection = sqlite;
}
catch (Exception ex)
{
// Any storage failure — a missing/incompatible native SQLite, an
// unwritable path — must not take the agent down. Degrade to
// in-memory idempotency and carry on.
logger?.LogWarning(
ex,
"Local job store unavailable ({Path}); using in-memory idempotency (not persisted across restarts).",
databasePath);
connection = null;
handledSet = [];
handledOrder = new Queue<Guid>();
downloadCacheMem = [];
}
connection = new SqliteConnection($"Data Source={databasePath}");
connection.Open();
using var command = connection.CreateCommand();
command.CommandText = """
CREATE TABLE IF NOT EXISTS HandledJobs (
JobId TEXT PRIMARY KEY,
AcceptedUtc TEXT NOT NULL,
CompletedUtc TEXT NULL,
State TEXT NULL
);
CREATE TABLE IF NOT EXISTS DownloadCache (
DestinationPath TEXT PRIMARY KEY,
ObjectKey TEXT NULL,
ETag TEXT NULL,
Sha256 TEXT NULL,
SizeBytes INTEGER NULL,
DownloadedUtc TEXT NOT NULL
);
""";
command.ExecuteNonQuery();
}
/// <summary>What the agent knows about a previously downloaded file.</summary>
@@ -55,6 +86,14 @@ public sealed class JobHistoryStore : IDisposable
public DownloadCacheEntry? GetDownloadCache(string destinationPath)
{
if (connection is null)
{
lock (writeLock)
{
return downloadCacheMem!.GetValueOrDefault(destinationPath);
}
}
using var command = connection.CreateCommand();
command.CommandText =
"SELECT ETag, Sha256, SizeBytes FROM DownloadCache WHERE DestinationPath = $path;";
@@ -76,6 +115,12 @@ public sealed class JobHistoryStore : IDisposable
{
lock (writeLock)
{
if (connection is null)
{
downloadCacheMem![destinationPath] = new DownloadCacheEntry(etag, sha256, sizeBytes);
return;
}
using var command = connection.CreateCommand();
command.CommandText = """
INSERT INTO DownloadCache (DestinationPath, ObjectKey, ETag, Sha256, SizeBytes, DownloadedUtc)
@@ -105,6 +150,22 @@ public sealed class JobHistoryStore : IDisposable
{
lock (writeLock)
{
if (connection is null)
{
if (!handledSet!.Add(jobId))
{
return false;
}
handledOrder!.Enqueue(jobId);
while (handledSet.Count > ProtocolDefaults.JobIdempotencyRetention && handledOrder.Count > 0)
{
handledSet.Remove(handledOrder.Dequeue());
}
return true;
}
using var command = connection.CreateCommand();
command.CommandText = "INSERT OR IGNORE INTO HandledJobs (JobId, AcceptedUtc) VALUES ($id, $utc);";
command.Parameters.AddWithValue("$id", jobId.ToString("D"));
@@ -117,6 +178,12 @@ public sealed class JobHistoryStore : IDisposable
{
lock (writeLock)
{
if (connection is null)
{
// Membership already recorded on accept; nothing else to track.
return;
}
using var command = connection.CreateCommand();
command.CommandText = "UPDATE HandledJobs SET CompletedUtc = $utc, State = $state WHERE JobId = $id;";
command.Parameters.AddWithValue("$utc", DateTimeOffset.UtcNow.ToString("O"));
@@ -130,6 +197,14 @@ public sealed class JobHistoryStore : IDisposable
public bool IsHandled(Guid jobId)
{
if (connection is null)
{
lock (writeLock)
{
return handledSet!.Contains(jobId);
}
}
using var command = connection.CreateCommand();
command.CommandText = "SELECT 1 FROM HandledJobs WHERE JobId = $id;";
command.Parameters.AddWithValue("$id", jobId.ToString("D"));
@@ -138,7 +213,7 @@ public sealed class JobHistoryStore : IDisposable
private void Prune()
{
using var command = connection.CreateCommand();
using var command = connection!.CreateCommand();
command.CommandText = """
DELETE FROM HandledJobs WHERE JobId NOT IN (
SELECT JobId FROM HandledJobs ORDER BY AcceptedUtc DESC LIMIT $keep
@@ -148,5 +223,5 @@ public sealed class JobHistoryStore : IDisposable
command.ExecuteNonQuery();
}
public void Dispose() => connection.Dispose();
public void Dispose() => connection?.Dispose();
}