diff --git a/docs/common/README.md b/docs/common/README.md
index 0836f82b..8dae0697 100644
--- a/docs/common/README.md
+++ b/docs/common/README.md
@@ -10,7 +10,7 @@ The library owns reusable implementations. It does not own application topology,
- Cloudflare DNS API client and A/AAAA reconciliation (`VectorNNTPD.Common.Cloudflare`)
- Authoritative DNS queries for DNS-01: NS discovery and UDP/TCP TXT lookup (`VectorNNTPD.Common.Dns`)
- Bind-address expansion and eligibility (`VectorNNTPD.Common.Networking`)
-- Options types those hosts adapt into (`VectorNNTPD.Common.Configuration`), including `ApplicationFqdn`, `ServerIdRules`, `VectorEnvironment`, `ApplicationLocalPath`, and `ApplicationJsonConfiguration`. Relative paths must stay inside the application base after `Path.GetFullPath` normalization. Rooted paths stay rooted. The check does not follow symlinks or junctions. The JSON helper removes Generic Host `appsettings` sources and registers `{entry assembly}.json`. The RabbitMQ filename is an explicit argument. BackFiller passes `VectorNNTPD.RabbitMQ.json`.
+- Options types those hosts adapt into (`VectorNNTPD.Common.Configuration`), including `ApplicationFqdn`, `ServerIdRules`, `VectorEnvironment`, `ApplicationLocalPath`, and `ApplicationJsonConfiguration`. Relative paths must stay inside the application base after `Path.GetFullPath` normalization. Rooted paths stay rooted. The check does not follow symlinks or junctions. StorageService keeps a separate `StorageRelativePath` helper for joining validated leaf segments under spool/sysfs bases; that is not a substitute for `ApplicationLocalPath`. See [configuration.md](configuration.md#application-local-and-storage-relative-paths). The JSON helper removes Generic Host `appsettings` sources and registers `{entry assembly}.json`. The RabbitMQ filename is an explicit argument. BackFiller passes `VectorNNTPD.RabbitMQ.json`.
- NntpDB connection options and MySQL session (`VectorNNTPD.Common.NntpDb`)
- Article content primitives: parser, `ArticleRecord`, `ArticleId`, classification, yEnc validation, and OverviewDB protobuf codec (`VectorNNTPD.Common.Articles`)
- Vector Article Transfer Protocol framing (`VectorNNTPD.Common.Transport.ArticleTransfer`)
@@ -28,6 +28,7 @@ RabbitMQ exchange, queue, and binding declaration stays with the application. Ar
| [vatp.md](vatp.md) | `docs/vatp.md` |
| [architecture.md](architecture.md) | Common-owned passages in `docs/architecture.md` |
| [configuration.md](configuration.md) | Common-owned passages in `docs/configuration.md` |
+| [systemd-host-abstraction.md](systemd-host-abstraction.md) | Design proposal only (not implemented); compares Storage and BackFiller systemd stacks |
Paths inside the copied articles point at `src/VectorNNTPD.Common` and `tests/VectorNNTPD.Common.Tests`. References to NNTPD or StorageServer projects name those repositories; they are not projects in BackFiller.
diff --git a/docs/common/configuration.md b/docs/common/configuration.md
index 6af693be..97e6c293 100644
--- a/docs/common/configuration.md
+++ b/docs/common/configuration.md
@@ -84,3 +84,36 @@ A connection string rejected by `MySqlConnectionStringBuilder`, an authenticatio
| Explicit IP | That address, if it is assigned and eligible |
Eligible addresses may be public or private. They must not be multicast, unspecified, loopback, or link-local. An empty resolved set fails startup. Explicit addresses that are syntactically valid but not assigned to a local NIC are rejected.
+
+## Application-local and storage-relative paths
+
+Two helpers deal with filesystem paths. They look related but are not interchangeable.
+
+### `ApplicationLocalPath` (Common)
+
+`VectorNNTPD.Common.Configuration.ApplicationLocalPath` resolves a **configured** path against the application binary directory (`AppContext.BaseDirectory`, or an explicit base passed by tests).
+
+| Input | Result |
+|-------|--------|
+| Relative path | Fully qualified path under the application base, or rejected when lexical canonicalization leaves that base |
+| Rooted path | Stays rooted; not forced under the application base |
+
+Use it for host options such as `AcmeStateDir`, `LogDir`, and StorageServer `DbDir` / spool roots when the operator supplies a configured location. The process working directory and IDE content root are never implicit fallbacks. Containment is lexical (`Path.GetFullPath`); it does not follow symlinks, junctions, or other reparse points.
+
+### `StorageRelativePath` (StorageService)
+
+`VectorNNTPD.StorageService.Storage.StorageRelativePath` joins **validated leaf segments** under a base the caller already chose (spool directory, log directory, sysfs node, and so on). Each segment must be a single relative name: no roots, no directory separators, and no `.` / `..`. After `Path.Join`, the fully qualified result must stay under the base. `CombineUnderCheckedSegment` additionally allows characters illegal as Win32 file names (Linux `major:minor` device ids) after the caller has constrained the alphabet.
+
+Use it when building `base/leaf` paths for article-index files, write probes, and Linux sysfs nodes. Do not use it to resolve operator-configured paths against the binary directory.
+
+### Why they stay separate
+
+| Concern | `ApplicationLocalPath` | `StorageRelativePath` |
+|---------|------------------------|------------------------|
+| Typical input | One configured string (relative or absolute) | One or more leaf segments under a known base |
+| Base | Application binary directory | Caller-supplied directory |
+| Rooted input | Allowed (stays rooted) | Rejected as a segment |
+| Linux `major:minor` leaves | Not applicable | Supported via `CombineUnderCheckedSegment` |
+| Symlink / reparse safety | Lexical only | Lexical only |
+
+Neither helper claims filesystem-level containment against concurrent renames or symlink swaps after the check.
diff --git a/docs/common/systemd-host-abstraction.md b/docs/common/systemd-host-abstraction.md
new file mode 100644
index 00000000..6e55d489
--- /dev/null
+++ b/docs/common/systemd-host-abstraction.md
@@ -0,0 +1,86 @@
+# Systemd host abstraction (design proposal)
+
+**Status:** proposal only — not implemented. Readiness semantics differ between hosts; do not extract a shared library until those contracts are agreed explicitly.
+
+This note compares the systemd stacks in `VectorNNTPD.StorageService` and `VectorNNTPD.BackFillerService` after the StorageService merge. It identifies genuine duplication, blocking differences, and the smallest Common surface that could support both hosts without accidental behaviour change.
+
+## Current locations
+
+| Concern | StorageService | BackFiller |
+|---------|----------------|------------|
+| Lifecycle notifier | `Hosting/Systemd/SystemdLifecycleNotifier.cs` | `Hosting/Systemd/SystemdLifecycleNotifier.cs` |
+| Notify bridge | `SystemdNotifyBridge` | `SystemdNotifyBridge` |
+| Runtime / env detection | `SystemdRuntime` | `SystemdRuntime` |
+| Watchdog interval math | `SystemdWatchdogInterval` | `SystemdWatchdogInterval` |
+| Watchdog loop | `SystemdWatchdogService` | `SystemdWatchdogService` |
+| Health gate | `ApplicationHealth` / `IApplicationHealth` | `BackFillerApplicationHealth` / `IApplicationHealth` |
+
+## Genuinely duplicated functionality
+
+These pieces are near-copies and are the safe candidates for a shared kit **after** contracts converge:
+
+1. **`ISystemdNotifyBridge` + `SystemdNotifyBridge`** — wrap `ISystemdNotifier` for `READY=1`, `STOPPING=1`, `STATUS=`, `WATCHDOG=1`.
+2. **`ISystemdRuntime` + `SystemdRuntime`** — Linux / systemd-service detection and `WATCHDOG_USEC` parsing.
+3. **`SystemdWatchdogInterval.Calculate`** — fraction of the systemd deadline with a 1 ms floor and 1 ms margin before the deadline.
+4. **Watchdog keep-alive loop shape** — `BackgroundService` + `PeriodicTimer`, skip ticks when unhealthy, link host stopping.
+
+## Blocking readiness and failure differences
+
+Do not merge the notifiers until these are decided:
+
+| Topic | StorageService | BackFiller |
+|-------|----------------|------------|
+| Ready trigger | `ApplicationLifecycle` transition to `ApplicationState.Running` | `IHostApplicationLifetime.ApplicationStarted` |
+| Ready retry | None — one attempt gated by `Interlocked` | Retries on unhealthy or handled notify failure (`ReadyRetryInterval` = 1 s) until success, shutdown, or dispose |
+| Ready options | `NotifyReadyOnApplicationRunning` | Options under `BackFiller:Systemd` (ready tied to ApplicationStarted) |
+| Stopping | On `Stopping` / `Stopped` lifecycle states | On host `ApplicationStopping` |
+| Notify failure | **Rethrows** after logging | **Logged and swallowed** (broken notify must not crash the process) |
+| Watchdog health | `IApplicationHealth.IsHealthyForWatchdog` | Same interface; richer sticky unhealthy (unexpected service termination, TLS material expiry) |
+| Interval validation | Positive timeout accepted | Requires at least 2 ms (`MinimumTimeout`) |
+
+Storage readiness is application-service completion. BackFiller readiness is Generic Host started, with retry until watchdog health and notify succeed. Unifying without an explicit product decision would change when systemd considers the unit ready and whether a notify socket fault fails the process.
+
+## What could safely live in Common
+
+Smallest shared abstraction that preserves host-specific policy:
+
+```
+VectorNNTPD.Common.Hosting.Systemd
+ ISystemdNotifyBridge / SystemdNotifyBridge // failure policy injected or strategy
+ ISystemdRuntime / SystemdRuntime
+ SystemdWatchdogInterval
+ (optional) SystemdWatchdogServiceBase // interval + loop; health + options from host
+```
+
+Hosts would keep:
+
+- Their own `SystemdLifecycleNotifier` (or a thin adapter) wired to either `ApplicationLifecycle` or `IHostApplicationLifetime`.
+- Host-specific `IApplicationHealth` implementations and options sections.
+- Ready-retry policy (BackFiller) versus single-shot ready (Storage), unless both deliberately adopt one model.
+
+## Required host changes (when approved)
+
+1. Agree failure policy for notify (rethrow vs swallow) and document it once in Common.
+2. Agree ready signal source (`ApplicationLifecycle.Running` vs `ApplicationStarted`) and whether retry is required for Storage.
+3. Move bridge / runtime / interval (and optionally the watchdog loop) into Common; leave notifiers in each host or parameterise a shared notifier with a readiness strategy interface.
+4. Point both hosts’ DI registration at the Common types; delete the duplicate host copies.
+5. Align `SystemdWatchdogInterval` minimum-timeout rules before sharing.
+
+## Failure modes and platform notes
+
+- Outside Linux or without `NOTIFY_SOCKET`, bridges no-op when the notifier is disabled.
+- Watchdog activates only when `WATCHDOG_USEC` is present and options enable it.
+- BackFiller’s swallowed notify failures mean missing `READY=1` / keep-alives can still trip systemd timeouts without crashing the process.
+- Storage’s rethrowing bridge can fail startup or watchdog ticks if notify throws; that must not be silently changed to BackFiller’s swallow policy.
+
+## Test coverage needed before extraction
+
+- Existing BackFiller tests under `tests/VectorNNTPD.BackFillerService.Tests/Hosting/Systemd/` (notifier, bridge, runtime, interval, watchdog, host integration).
+- Equivalent StorageService lifecycle notifier / watchdog tests for `ApplicationLifecycle`-driven ready and for notify failure propagation.
+- After extraction: Common unit tests for interval math and bridge behaviour; both hosts keep integration tests proving their readiness contract unchanged (byte-for-byte timing is not required; observable ready / stopping / retry / swallow-or-throw must match today’s host).
+
+## Explicit non-goals for a first extraction
+
+- Do not move `ApplicationLifecycle` or BackFiller’s host-lifetime readiness into each other as a side effect.
+- Do not merge `BackFillerApplicationHealth` certificate / termination sticky state into Storage’s simpler health without a design pass.
+- Do not change production ready timing as part of a mechanical file move.
diff --git a/src/VectorNNTPD.Common/Configuration/ApplicationLocalPath.cs b/src/VectorNNTPD.Common/Configuration/ApplicationLocalPath.cs
index 3a537f17..231f65e4 100644
--- a/src/VectorNNTPD.Common/Configuration/ApplicationLocalPath.cs
+++ b/src/VectorNNTPD.Common/Configuration/ApplicationLocalPath.cs
@@ -10,10 +10,17 @@ namespace VectorNNTPD.Common.Configuration
/// host content root are never used as an implicit fallback. This method does not create directories.
///
///
+ /// Use this helper for configured host paths such as ACME state directories and log directories.
+ /// Do not use it to join storage spool/sysfs leaf segments under an arbitrary base; that is the
+ /// StorageService StorageRelativePath contract (validated single segments, optional
+ /// Linux major:minor leaves). The helpers are related only in that both apply lexical
+ /// containment checks; they are not interchangeable.
+ ///
+ ///
/// Containment is lexical. normalizes . and ..
/// and does not resolve symlinks, junctions, or other reparse points. A relative path that stays inside
/// the base after that normalization is accepted even when a directory component later points elsewhere
- /// on the filesystem.
+ /// on the filesystem. Rooted configured paths stay rooted and are not forced under the application base.
///
///
internal static class ApplicationLocalPath
diff --git a/src/VectorNNTPD.StorageService/Listener/StorageVatpListenerService.cs b/src/VectorNNTPD.StorageService/Listener/StorageVatpListenerService.cs
index 0e228ee1..65542733 100644
--- a/src/VectorNNTPD.StorageService/Listener/StorageVatpListenerService.cs
+++ b/src/VectorNNTPD.StorageService/Listener/StorageVatpListenerService.cs
@@ -322,27 +322,21 @@ private void BindEndpoints(IReadOnlyList bindings)
private static Socket CreateBoundListenSocket(ListenBinding binding)
{
var endpoint = binding.EndPoint;
- var socket = new Socket(endpoint.AddressFamily, SocketType.Stream, ProtocolType.Tcp)
- {
- NoDelay = true,
- };
+ using var ownership = new DisposableOwnership(
+ new Socket(endpoint.AddressFamily, SocketType.Stream, ProtocolType.Tcp)
+ {
+ NoDelay = true,
+ });
+ var socket = ownership.Resource;
if (endpoint.AddressFamily == AddressFamily.InterNetworkV6)
{
socket.DualMode = binding.DualMode;
}
- try
- {
- socket.Bind(endpoint);
- socket.Listen(512);
- return socket;
- }
- catch
- {
- socket.Dispose();
- throw;
- }
+ socket.Bind(endpoint);
+ socket.Listen(512);
+ return ownership.Transfer();
}
private bool IsImplicitWildcard(IPEndPoint endpoint)
diff --git a/src/VectorNNTPD.StorageService/Storage/ArticleIndex/ArticleIndexDatabase.cs b/src/VectorNNTPD.StorageService/Storage/ArticleIndex/ArticleIndexDatabase.cs
index 61cc8eeb..1e6abc21 100644
--- a/src/VectorNNTPD.StorageService/Storage/ArticleIndex/ArticleIndexDatabase.cs
+++ b/src/VectorNNTPD.StorageService/Storage/ArticleIndex/ArticleIndexDatabase.cs
@@ -94,22 +94,17 @@ internal void Initialize(CancellationToken cancellationToken)
Cache = SqliteCacheMode.Private,
Pooling = false,
};
- var connection = new SqliteConnection(builder.ConnectionString);
- try
- {
- connection.Open();
- ApplyWriterPragmas(connection, pageSizeFirst: true);
- Migrate(connection);
- ApplyWriterPragmas(connection, pageSizeFirst: false);
- PrepareWriter(connection);
- _writer = connection;
- OpenReaders();
- }
- catch
- {
- connection.Dispose();
- throw;
- }
+ using var ownership = new DisposableOwnership(
+ new SqliteConnection(builder.ConnectionString));
+ var connection = ownership.Resource;
+ connection.Open();
+ ApplyWriterPragmas(connection, pageSizeFirst: true);
+ Migrate(connection);
+ ApplyWriterPragmas(connection, pageSizeFirst: false);
+ PrepareWriter(connection);
+ // Readers open before Transfer so a reader-pool failure still disposes the writer.
+ OpenReaders();
+ _writer = ownership.Transfer();
}
///
diff --git a/src/VectorNNTPD.StorageService/Storage/ArticleIndex/ArticleIndexService.cs b/src/VectorNNTPD.StorageService/Storage/ArticleIndex/ArticleIndexService.cs
index 2070645c..1be41785 100644
--- a/src/VectorNNTPD.StorageService/Storage/ArticleIndex/ArticleIndexService.cs
+++ b/src/VectorNNTPD.StorageService/Storage/ArticleIndex/ArticleIndexService.cs
@@ -152,7 +152,17 @@ public async Task StartAsync(CancellationToken cancellationToken)
foreach (var binding in bindings)
{
var database = new ArticleIndexDatabase(binding.DatabasePath, binding.SpoolDirectory, _settings, budget);
- database.Initialize(cancellationToken);
+ try
+ {
+ database.Initialize(cancellationToken);
+ }
+ catch
+ {
+ // Initialize failed before the slot was published; dispose the shell.
+ database.Dispose();
+ throw;
+ }
+
var counters = bindings.Count == 1 ? _counters : new ArticleIndexCounters();
_spools.Add(new SpoolSlot(binding, database, counters, new ArticleAccessCoalescer()));
_bySpool[binding.SpoolDirectory] = _spools[^1];
diff --git a/src/VectorNNTPD.StorageService/Storage/StorageRelativePath.cs b/src/VectorNNTPD.StorageService/Storage/StorageRelativePath.cs
index a1d1aa6d..955448cd 100644
--- a/src/VectorNNTPD.StorageService/Storage/StorageRelativePath.cs
+++ b/src/VectorNNTPD.StorageService/Storage/StorageRelativePath.cs
@@ -2,12 +2,26 @@ namespace VectorNNTPD.StorageService.Storage
{
///
- /// Builds paths under a caller-chosen base using validated relative segments and
+ /// Builds storage paths under a caller-chosen base using validated relative segments and
/// (which does not drop the base for a rooted later argument).
///
///
+ ///
+ /// This helper is not interchangeable with Common ApplicationLocalPath.
+ /// ApplicationLocalPath resolves a configured path (relative or absolute) against the
+ /// application binary directory. This type joins one or more validated leaf segments beneath an
+ /// already-chosen base such as a spool root, log directory, or sysfs node.
+ ///
+ ///
/// Callers that intend base/leaf must pass a single relative segment (no roots, separators, or
/// ./..). After joining, the fully qualified result must stay under the base directory.
+ /// Containment is lexical via : it normalizes . and
+ /// .. and does not resolve symlinks, junctions, or other reparse points.
+ ///
+ ///
+ /// additionally permits characters that are illegal as Win32
+ /// file names (Linux major:minor device ids) after the caller has constrained the alphabet.
+ ///
///
internal static class StorageRelativePath
{
diff --git a/tests/VectorNNTPD.StorageService.Tests/Listener/StorageVatpListenerServiceTests.cs b/tests/VectorNNTPD.StorageService.Tests/Listener/StorageVatpListenerServiceTests.cs
index 2a0b7a96..3b807825 100644
--- a/tests/VectorNNTPD.StorageService.Tests/Listener/StorageVatpListenerServiceTests.cs
+++ b/tests/VectorNNTPD.StorageService.Tests/Listener/StorageVatpListenerServiceTests.cs
@@ -86,6 +86,33 @@ public async Task Listener_starts_when_ready_and_shuts_down_cleanly()
Assert.Equal(StorageVatpListenerState.Stopped, service.State);
}
+ [Fact]
+ public async Task Bind_failure_disposes_the_partial_socket_and_leaves_the_listener_stopped()
+ {
+ var port = StorageServerTestOptions.GetFreeTcpPort();
+ using var blocker = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp);
+ blocker.ExclusiveAddressUse = true;
+ blocker.Bind(new IPEndPoint(IPAddress.Loopback, port));
+ blocker.Listen(1);
+
+ var runtime = CreateRuntime(port);
+ var readiness = new AcmeCertificateReadiness();
+ readiness.MarkReady();
+ await using var service = new StorageVatpListenerService(
+ runtime,
+ TestListenerCertificates.CreatePublishedProvider(),
+ NullStorageArticleOpenBoundary.Instance,
+ readiness,
+ NullLogger.Instance);
+
+ var ex = await Assert.ThrowsAnyAsync(() => service.StartAsync(CancellationToken.None));
+ Assert.True(
+ ex is SocketException or InvalidOperationException,
+ "Expected bind failure or no-endpoints failure, got " + ex.GetType().Name);
+ Assert.Equal(StorageVatpListenerState.Stopped, service.State);
+ Assert.Empty(service.LocalEndPoints);
+ }
+
[Fact]
public async Task Existing_connection_keeps_certificate_lease_after_rotation()
{
diff --git a/tests/VectorNNTPD.StorageService.Tests/Storage/ArticleIndexTests.cs b/tests/VectorNNTPD.StorageService.Tests/Storage/ArticleIndexTests.cs
index f5ea2a17..5d7efae3 100644
--- a/tests/VectorNNTPD.StorageService.Tests/Storage/ArticleIndexTests.cs
+++ b/tests/VectorNNTPD.StorageService.Tests/Storage/ArticleIndexTests.cs
@@ -44,6 +44,30 @@ public async Task Database_reopens_with_schema_version_2_and_page_size_8192()
}
}
+ [Fact]
+ public void Initialize_failure_disposes_cleanly_without_publishing_a_writer()
+ {
+ var spool = ArticleIndexTestSupport.NewDirectory();
+ var root = ArticleIndexTestSupport.NewDirectory();
+ var missingParent = Path.Join(root, "missing", "article-index.sqlite");
+ try
+ {
+ using var database = new ArticleIndexDatabase(
+ missingParent,
+ spool,
+ new ArticleIndexSettings(),
+ ArticleIndexCacheBudget.ForSpoolCount(1));
+ Assert.ThrowsAny(() => database.Initialize(CancellationToken.None));
+ // Idempotent second dispose; `using` still runs if this call throws.
+ database.Dispose();
+ }
+ finally
+ {
+ ArticleIndexTestSupport.Delete(spool);
+ ArticleIndexTestSupport.Delete(root);
+ }
+ }
+
[Fact]
public async Task Unknown_schema_version_fails_startup_without_publishing_membership()
{
diff --git a/tests/VectorNNTPD.StorageService.Tests/Storage/SpoolPersistenceBenchTests.cs b/tests/VectorNNTPD.StorageService.Tests/Storage/SpoolPersistenceBenchTests.cs
index 4b6f8ac7..9bd0f5d7 100644
--- a/tests/VectorNNTPD.StorageService.Tests/Storage/SpoolPersistenceBenchTests.cs
+++ b/tests/VectorNNTPD.StorageService.Tests/Storage/SpoolPersistenceBenchTests.cs
@@ -277,7 +277,10 @@ private static long Measure(int count, Action action)
[Fact]
public async Task Concurrent_workers_report_cpu_sink_throughput()
{
- const int count = 384;
+ // Sized for Linux CI under Coverlet: 384×750 KiB at ~5 art/s (observed concurrent
+ // rate on ubuntu-latest) exceeds the 60s worker-completion wait. Keep 1/2/4/8 workers
+ // and 750 KiB payloads; shrink the batch so each pool still finishes with margin.
+ const int count = 64;
const int bodyBytes = 750 * 1024;
var articles = new AcceptedArticle[count];
for (var i = 0; i < count; i++)
@@ -286,7 +289,7 @@ public async Task Concurrent_workers_report_cpu_sink_throughput()
}
var warmup = CreatePipeline(files: null, roots: null);
- for (var i = 0; i < 16; i++)
+ for (var i = 0; i < 8; i++)
{
Assert.Equal(
AcceptedArticleProcessResult.Completed,
@@ -363,7 +366,9 @@ private async Task RunWorkerPool(
MinWorkers = workers,
MaxWorkers = workers,
MaxInFlightPerSpool = 2,
- ControlIntervalMilliseconds = 1,
+ // Min==Max and ScaleDwell is long, so the control loop never scales. Use the
+ // production interval: a 1 ms spin steals CPU from workers on covered CI runners.
+ ControlIntervalMilliseconds = SpoolPersistenceOptions.DefaultControlIntervalMilliseconds,
ScaleDwellMilliseconds = 60_000,
};
var worker = new AcceptedArticleWorker(