debezium/dbz#2090 Add SSH config file watcher with host reconciliation by d1vyanshu-kumar · Pull Request #460 · debezium/debezium-platform

d1vyanshu-kumar · 2026-07-09T10:28:27Z

Fixes debezium/dbz#2090

Description

Adds the SSH config file watcher that monitors ~/.ssh/config and keeps the host_status database table in sync automatically.

How it works:

SshConfigWatcherService registers a Java NIO WatchService on the SSH config parent directory and filters events to the config file specifically. A 2-second debounce coalesces rapid editor saves into a single reconciliation run. A @Scheduled(every = "5m", delayed = "5m") fallback handles environments where WatchService misses events — such as NFS mounts and Kubernetes ConfigMap volumes, which use atomic symlink-swap instead of ENTRY_MODIFY events.

Reconciliation logic:

HostReconciliationPlanBuilder is a dedicated, package-private class that compares SSH config state against database state and produces a ReconciliationPlan — three lists describing what to add, remove, or update. It is intentionally not a CDI bean: no injected dependencies, no mutable state, no side effects. This makes it directly
unit-testable without a running Quarkus application.

Persistence layer:

HostStatusService extends AbstractService<HostStatusEntity, HostStatus, HostStatusReference> following the same Blaze-Persistence pattern used by PipelineService, VaultService, and ConnectionService. The HostStatus entity view is annotated @CreatableEntityView and @UpdatableEntityView to support all three operations the reconciler needs.

CDI transaction boundary:

@Transactional on self-invocations is silently ignored. All database write methods live in the separate HostStatusService bean so every call goes through the CDI proxy and transactions are properly committed and rolled back.

Runtime mode guard:

The bean is always instantiated. Each @Observes and @Scheduled method is guarded by if (!isHostMode()) return; so no file system access happens in operator mode.

HostProvisioningService stub:

The watcher calls provisioningService.provision(alias) for new and updated hosts. The class is included here with empty method bodies so this sub-issue compiles independently. Ansible execution will be implemented in a future implementation.

Tests:

HostReconciliationPlanBuilderTest contains 7 plain JUnit 5 tests — no @QuarkusTest, no database, no mocks of the watcher itself. It directly instantiates the builder and verifies every reconciliation scenario: add, remove, update, mixed, empty, unchanged,
and null-hostname fallback.

PR Checklist

I have read the contribution guidelines
and the governance document on PR expectations.
Minimal changes to code not directly related to your change
One feature/change per PR
Rebased on upstream main

Signed-off-by: divyanshu_Kumar <154233802+d1vyanshu-kumar@users.noreply.github.com>

mfvitale · 2026-07-09T10:48:12Z

+ * (see {@code AbstractService}, {@code PipelineService}, etc.).
+ */
+@ApplicationScoped
+public class HostReconciliationRepository {


Though I like the repository pattern, for historic reason, we use the BlazeBit persistence layer.
Could you please so align with it? This means your service will extend the AbstractService, so same basic method like list, create, update, delete, findBy are already there.

mfvitale · 2026-07-09T13:41:33Z

+     * @param dbHosts   active host entities from the database (status ≠ REMOVED)
+     * @return the reconciliation plan describing what needs to change
+     */
+    ReconciliationPlan buildReconciliationPlan(List<SshHostEntry> fileHosts,


WDYT to put this on a separate class?

mfvitale · 2026-07-09T13:46:23Z

+    private void scheduleReconciliation() {
+        ScheduledFuture<?> existing = pendingReconciliation;
+        if (existing != null && !existing.isDone()) {
+            existing.cancel(false);


Could interrupting the provisioning lead to a bad state?

@mfvitale no, it can't. The cancel(false) only cancels tasks that are still waiting in the 2-second debounce window (i.e., the reconciliation hasn't started yet). The false parameter means "do not interrupt if already running" - so if a reconciliation is already in progress and executing provisioning calls, it will run to completion uninterrupted.

Essentially, the cancel only prevents duplicate reconciliation runs from being queued during rapid file events - it never interrupts an active one.

Thanks for the explanation.

mfvitale · 2026-07-09T14:15:29Z

+                break;
+            }
+
+            if (key == null) {


Could you just flip this so you can remove the continue?

mfvitale · 2026-07-09T14:18:56Z

+        }
+
+        for (String alias : plan.toRemove()) {
+            repository.markHostRemoved(alias);


What happens with the delete?

@mfvitale Right now, when a host is removed from the SSH config, we mark its status as REMOVED in the database. This ensures the scheduler won't deploy any new pipelines to that host going forward.

The actual pipeline undeployment (stopping and migrating active pipelines from the removed host) is planned for a future implementation - the HostPipelineController will handle that lifecycle. For this iteration, marking as REMOVED is the safe first step that prevents further deployments while the undeployment logic is built out.

mfvitale · 2026-07-09T14:21:34Z

+ * <p>These are plain JUnit 5 tests with no {@code @QuarkusTest} — they test only
+ * the stateless comparison function, which has zero database access and zero side effects.
+ */
+class SshConfigWatcherServiceTest {


Well effectively this tests the reconciliation plan not the watcher itself. If you move the buildReconciliationPlan in a separate class as suggested this will be the tests for that class, then I could see another test testing the watcher itself.

… extract plan builder Signed-off-by: divyanshu_Kumar <154233802+d1vyanshu-kumar@users.noreply.github.com>

d1vyanshu-kumar · 2026-07-10T09:40:48Z

Hi @mfvitale, thanks again for the thorough review and the guidance!

I just pushed a new commit. I've completely refactored the persistence layer to align with the Blaze-Persistence architecture. We now have a proper HostStatusService extending AbstractService, along with the HostStatus and HostStatusReference entity views.

I also took your advice on separating concerns—I pulled all the pure reconciliation math out of the Watcher and put it into a dedicated HostReconciliationPlanBuilder class. The tests are much cleaner now too, since they only test the pure logic without needing to mock the entire Watcher.

The minor points (flipping the if guard, etc.) are also sorted, and I noted your point about the REMOVED status for the future pipeline undeployment implementation.

Let me know if everything looks good to go now!

mfvitale · 2026-07-10T09:41:43Z

+ * injected dependencies, no mutable state, and no side effects. Every method
+ * is a deterministic transformation of its inputs.
+ */
+class HostReconciliationPlanBuilder {


Why this is not a bean? I think it should be.

@mfvitale I kept it as a plain Java object instantiated with new because it's completely stateless and acts as a pure function (no dependencies or side effects).

I think you make a good point about consistency — I can see that making it a bean keeps the dependency graph explicit and follows the same pattern as the rest of the codebase. I'll convert it to an @ApplicationScoped bean and inject it into the watcher in the next commit.

mfvitale · 2026-07-10T09:42:09Z

-                    logger.debugv("SSH config file event: {0} — {1}",
-                            event.kind().name(), changedFile);
-                    configFileAffected = true;
+                if (configFileAffected) {


Should this be inside the if above?

@mfvitale, I can see how this looks odd at first glance. The reason it's outside the loop is to handle the OVERFLOW case cleanly. When WatchService overflows, we set the flag and break out of the loop. The if (configFileAffected) check after the loop catches both the normal case (our config file was modified) and the overflow case (we missed events and need a full resync) in a single place.

That said, I could also just call scheduleReconciliation() directly from both places and drop the flag entirely — let me know if you'd prefer that, happy to refactor it either way.

That said, I could also just call scheduleReconciliation() directly from both places and drop the flag entirely — let me know if you'd prefer that, happy to refactor it either way.

Yes, this is exactly where I was leading you.

mfvitale · 2026-07-10T09:58:21Z

@d1vyanshu-kumar Could you also add an IT for the Watcher?

d1vyanshu-kumar · 2026-07-10T10:09:04Z

@d1vyanshu-kumar Could you also add an IT for the Watcher?

Sure, I'll add one! I'm thinking of a @QuarkusTest that writes a temp SSH config file, verifies the initial reconciliation picks it up in the database, and then modifies the file to check that the watcher detects the change and updates the DB state accordingly. I'll include it in the next commit.

debezium/dbz#2090 Add SSH config file watcher with host reconciliation

968810a

Signed-off-by: divyanshu_Kumar <154233802+d1vyanshu-kumar@users.noreply.github.com>

mfvitale reviewed Jul 9, 2026

View reviewed changes

debezium/dbz#2090 Refactor persistence layer to Blaze-Persistence and…

fcf276d

… extract plan builder Signed-off-by: divyanshu_Kumar <154233802+d1vyanshu-kumar@users.noreply.github.com>

d1vyanshu-kumar requested a review from mfvitale July 10, 2026 09:40

mfvitale reviewed Jul 10, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

d1vyanshu-kumar commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

PR Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d1vyanshu-kumar commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfvitale commented Jul 10, 2026

Uh oh!

d1vyanshu-kumar commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

d1vyanshu-kumar commented Jul 9, 2026 •

edited

Loading

d1vyanshu-kumar commented Jul 10, 2026 •

edited

Loading