Skip to content
2 changes: 2 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,8 @@ Nested groups:
- `BackFiller:TcpKeepAlive` — TCP `SO_KEEPALIVE` for every upstream NNTP socket and every accepted cache-listener socket. `TimeSeconds` default 10 (range 1–7200) is idle time before the first probe. `IntervalSeconds` default 5 (range 1–300) is the gap between probes. `RetryCount` default 3 (range 1–20) is unanswered probes before the stack drops the connection. At the defaults, dead-path detection completes in about 25 s, before the default NNTP command timeout (30 s) and well before the listener I/O-progress timeout (60 s). Independent of per-provider MySQL `keepalive` (NNTP `DATE`). Nagle and buffer settings are unchanged. Platforms that cannot set a probe option still enable `SO_KEEPALIVE` and keep OS defaults for that option; enabling keepalive itself must succeed or the socket is rejected.
- `BackFiller:Systemd` — notify and watchdog enablement
- `BackFiller:SilentConsumerMonitor` — optional. Only `Enabled` (default true) is public. Do not place VirtualHost, Hosts, Management URL, or queue lists here. AMQP hosts/vhost/port and Management BaseUrl bind from the `RabbitMQ` section; username/password are projected from `nntpsharedconfig` onto live `RabbitMqOptions` on account refresh (Management uses them on the next HTTP call; AMQP uses them on the next reconnect dial). Article Work queues come from the MySQL provider catalog as `backfiller.{backbone}`. Detection thresholds are internal code defaults (`ProcessingStall` / `DispatchStall` / `ConsumerLoss`). Management poll failures yield `Unknown` and do not resolve open shared alerts; instance-local monitoring continues. See `docs/architecture.md` § Silent-consumer monitoring (including Management outages and `Unknown`) for the traced data flow and multi-instance semantics. Monitor failures never disable consumption.
- `BackFiller:LabStageProfiling` — lab-only Article Work stage latency histograms. Default `Enabled` false (no ambient profiler installed; production path unchanged). When `Enabled` is true, installs bounded per-stage histograms (pipeline, handler, session acquire, busy wait, ARTICLE command/status, payload receive, parse, retain, reply publish, plus reply serialize / publish-gate wait / gate-held confirm) and optionally writes `article-work-stage-profile.json` under `ExportDirectory` every `ExportIntervalSeconds` (default 2). Nested stages overlap — do not sum totals as exclusive wall time. Env: `BackFiller__LabStageProfiling__Enabled`, `BackFiller__LabStageProfiling__ExportDirectory`, `BackFiller__LabStageProfiling__ExportIntervalSeconds`.
- `BackFiller:LabUpstreamIsolation` — lab-only. Default `Enabled` false (ordinary deployments unchanged). When `Enabled` is true, every upstream NNTP dial through `INntpTransportFactory` must target `AllowedHost`:`AllowedPort` before a socket opens; otherwise connect fails closed with no unguarded fallback. `AllowedHost` must be exactly `127.0.0.1` (no `localhost`, DNS names, IPv6, or non-loopback). `AllowedPort` is required (1–65535) when enabled. `RejectTls` default true rejects provider `UseTls=true`. `RewritePublishedDestinations` default false; when true (requires `Enabled` and `RejectTls`), each account refresh rewrites **published** provider dial fields to `AllowedHost`:`AllowedPort` with `UseTls=false` and clears username/password so AUTHINFO is not sent — MySQL rows are **not** updated, and production dial behaviour is unchanged when rewrite is off. Incomplete or inconsistent enabled/rewrite configuration fails `ValidateOnStart`. Env examples: `BackFiller__LabUpstreamIsolation__Enabled`, `BackFiller__LabUpstreamIsolation__AllowedPort`, `BackFiller__LabUpstreamIsolation__RewritePublishedDestinations`.

## RabbitMQ section

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
using VectorNNTPD.BackFillerService.Configuration;
using VectorNNTPD.BackFillerService.Nntp;

namespace VectorNNTPD.BackFillerService.Accounts
{
/// <summary>
/// Lab-only rewriter that replaces published provider dial targets with the isolation allowlist
/// endpoint and clears credentials so AUTHINFO is not attempted against the local peer.
/// </summary>
/// <remarks>
/// Does not mutate MySQL rows. Applied after <see cref="ProviderAccountMapper.Map"/> on each refresh
/// when <see cref="LabUpstreamIsolationOptions.RewritePublishedDestinations"/> is true.
/// Production behaviour is unchanged when that flag is false.
/// </remarks>
internal static class LabUpstreamDestinationRewriter
{
/// <summary>
/// Returns <paramref name="providers"/> unchanged when rewrite is disabled; otherwise every
/// definition is retargeted to the allowlisted cleartext loopback endpoint without credentials.
/// </summary>
/// <param name="providers">Mapped providers from the account source.</param>
/// <param name="options">Lab isolation options already validated at startup when rewrite is enabled.</param>
/// <returns>Effective definitions used for pool publication.</returns>
/// <exception cref="ArgumentNullException">An argument is null.</exception>
/// <exception cref="InvalidOperationException">
/// Rewrite is enabled but isolation is incomplete (should have failed <c>ValidateOnStart</c>).
/// </exception>
internal static IReadOnlyList<BackFillerProviderDefinition> Apply(
IReadOnlyList<BackFillerProviderDefinition> providers,
LabUpstreamIsolationOptions options)
{
ArgumentNullException.ThrowIfNull(providers);
ArgumentNullException.ThrowIfNull(options);

if (!options.RewritePublishedDestinations)
{
return providers;
}

if (!options.Enabled)
{
throw new InvalidOperationException(
"LabUpstreamIsolation RewritePublishedDestinations requires Enabled=true.");
}

if (options.AllowedPort is null or < 1 or > 65535)
{
throw new InvalidOperationException(
"LabUpstreamIsolation AllowedPort must be in 1..65535 when RewritePublishedDestinations is true.");
}

var host = LabUpstreamIsolationOptions.RequiredLiteralHost;
var port = options.AllowedPort.Value;
var rewritten = new BackFillerProviderDefinition[providers.Count];
for (var i = 0; i < providers.Count; i++)
{
var source = providers[i];
rewritten[i] = new BackFillerProviderDefinition(
source.Backbone,
host,
port,
UseTls: false,
Username: null,
Password: null,
source.MinSessions,
source.MaxSessions,
source.KeepAliveSeconds);
}

return rewritten;
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,11 @@ internal sealed class ProviderAccountConfigurationService : IHostedService, INnt
/// <summary>Live RabbitMQ options. Username and password are replaced from each published snapshot.</summary>
private readonly IOptions<RabbitMqOptions> _rabbitMq;

/// <summary>
/// Lab isolation options. When rewrite is enabled, published dial targets are replaced after mapping.
/// </summary>
private readonly IOptions<LabUpstreamIsolationOptions> _labUpstreamIsolation;

/// <summary>Control-plane logger. Events are written through <see cref="ProviderAccountLogMessages"/>.</summary>
private readonly ILogger<ProviderAccountConfigurationService> _logger;

Expand Down Expand Up @@ -91,6 +96,9 @@ internal sealed class ProviderAccountConfigurationService : IHostedService, INnt
/// <param name="acmeOptions">Live ACME options updated from each shared snapshot.</param>
/// <param name="logger">Logger passed to <see cref="ProviderAccountLogMessages"/>.</param>
/// <param name="rabbitMqOptions">Live RabbitMQ options. Username and password are replaced from each shared snapshot.</param>
/// <param name="labUpstreamIsolation">
/// Lab isolation options. Optional in tests; defaults to disabled rewrite when omitted.
/// </param>
/// <exception cref="ArgumentNullException">Any argument is null.</exception>
/// <remarks>
/// The live <see cref="ProviderConfigurationCatalog"/> is owned by <see cref="NntpProviderRegistry"/>.
Expand All @@ -104,7 +112,8 @@ internal ProviderAccountConfigurationService(
IOptions<BackFillerOptions> backFillerOptions,
IOptions<AcmeCloudflareOptions> acmeOptions,
ILogger<ProviderAccountConfigurationService> logger,
IOptions<RabbitMqOptions>? rabbitMqOptions = null)
IOptions<RabbitMqOptions>? rabbitMqOptions = null,
IOptions<LabUpstreamIsolationOptions>? labUpstreamIsolation = null)
{
ArgumentNullException.ThrowIfNull(source);
ArgumentNullException.ThrowIfNull(sharedConfiguration);
Expand All @@ -118,6 +127,7 @@ internal ProviderAccountConfigurationService(
_registry = registry;
_runtime = runtime;
_backFillerOptions = backFillerOptions;
_labUpstreamIsolation = labUpstreamIsolation ?? Options.Create(new LabUpstreamIsolationOptions());
_acmeOptions = acmeOptions;
_rabbitMq = rabbitMqOptions ?? Options.Create(new RabbitMqOptions());
_logger = logger;
Expand Down Expand Up @@ -278,44 +288,50 @@ private async Task<bool> RefreshAsync(bool required, CancellationToken cancellat
ProviderAccountLogMessages.RowRejected(_logger, rejected.Backbone, rejected.Reason);
}

// Lab rewrite runs after mapping so pools never publish WAN dial targets while enabled.
// MySQL rows are not updated; credentials are cleared so AUTHINFO is not sent to the peer.
var effectiveProviders = LabUpstreamDestinationRewriter.Apply(
mapped.Providers,
_labUpstreamIsolation.Value);

IReadOnlyList<BackFillerProviderDefinition> previous;
lock (_gate)
{
previous = _published;
}

if (SnapshotsEqual(previous, mapped.Providers))
if (SnapshotsEqual(previous, effectiveProviders))
{
lock (_gate)
{
Project(shared, fqdn);
_shared = shared;
}

ProviderAccountLogMessages.SnapshotUnchanged(_logger, mapped.Providers.Count);
ProviderAccountLogMessages.SnapshotUnchanged(_logger, effectiveProviders.Count);
if (_lastRefreshFailed)
{
ProviderAccountLogMessages.RefreshRecovered(_logger, mapped.Providers.Count);
ProviderAccountLogMessages.RefreshRecovered(_logger, effectiveProviders.Count);
}

_lastRefreshFailed = false;
_hadSuccessfulSnapshot = true;
return true;
}

await _registry.ApplySnapshotAsync(mapped.Providers, cancellationToken).ConfigureAwait(false);
await _registry.ApplySnapshotAsync(effectiveProviders, cancellationToken).ConfigureAwait(false);
lock (_gate)
{
Project(shared, fqdn);
_published = mapped.Providers;
_published = effectiveProviders;
_shared = shared;
}

LogDelta(previous, mapped.Providers);
LogDelta(previous, effectiveProviders);
ProviderAccountLogMessages.SnapshotLoaded(
_logger,
_runtime.ServerId,
mapped.Providers.Count,
effectiveProviders.Count,
mapped.Rejected.Count);
if (_lastRefreshFailed)
{
Expand Down
Loading
Loading