implement stale node cleanup functionality and configuration

README.md

@@ -86,6 +86,8 @@ The web app can be configured with environment variables (defaults shown):
 | `HIDDEN_CHANNELS` | _unset_ | Comma-separated channel names the ingestor will ignore when forwarding packets. |
 | `FEDERATION` | `1` | Set to `1` to announce your instance and crawl peers, or `0` to disable federation. Private mode overrides this. |
 | `PRIVATE` | `0` | Set to `1` to hide the chat UI, disable message APIs, and exclude hidden clients from public listings. |
+| `STALE_NODE_CLEANUP_INTERVAL` | `0` | Hours between stale node cleanup cycles (e.g., `24` for daily). Disabled by default. |
+| `STALE_NODE_MIN_AGE` | `168` | Minimum age in hours before incomplete nodes are eligible for cleanup (default 7 days). |
 
 The application derives SEO-friendly document titles, descriptions, and social
 preview tags from these existing configuration values and reuses the bundled

web/lib/potato_mesh/application.rb

@@ -52,6 +52,7 @@
 require_relative "application/data_processing"
 require_relative "application/filesystem"
 require_relative "application/instances"
+require_relative "application/cleanup"
 require_relative "application/routes/api"
 require_relative "application/routes/ingest"
 require_relative "application/routes/root"
@@ -64,6 +65,7 @@ class Application < Sinatra::Base
     extend App::Identity
     extend App::Federation
     extend App::Instances
+    extend App::Cleanup
     extend App::Prometheus
     extend App::Queries
     extend App::DataProcessing
@@ -75,6 +77,7 @@ class Application < Sinatra::Base
     include App::Identity
     include App::Federation
     include App::Instances
+    include App::Cleanup
     include App::Prometheus
     include App::Queries
     include App::DataProcessing
@@ -134,6 +137,7 @@ def self.resolve_port(default_port: DEFAULT_PORT)
       set :views, File.expand_path("../../views", __dir__)
       set :federation_thread, nil
       set :federation_worker_pool, nil
+      set :stale_node_cleanup_thread, nil
       set :port, resolve_port
       set :bind, DEFAULT_BIND_ADDRESS
 
@@ -179,6 +183,16 @@ def self.resolve_port(default_port: DEFAULT_PORT)
           reason: "configuration",
         )
       end
+
+      if PotatoMesh::Config.stale_node_cleanup_enabled?
+        start_stale_node_cleanup_thread!
+      else
+        debug_log(
+          "Stale node cleanup disabled",
+          context: "cleanup.nodes",
+          reason: "configuration",
+        )
+      end
     end
   end
 end
@@ -198,6 +212,7 @@ def self.resolve_port(default_port: DEFAULT_PORT)
   PotatoMesh::App::Identity,
   PotatoMesh::App::Federation,
   PotatoMesh::App::Instances,
+  PotatoMesh::App::Cleanup,
   PotatoMesh::App::Prometheus,
   PotatoMesh::App::Queries,
   PotatoMesh::App::DataProcessing,

web/lib/potato_mesh/application/cleanup.rb

@@ -0,0 +1,127 @@
+# Copyright © 2025-26 l5yth & contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# frozen_string_literal: true
+
+module PotatoMesh
+  module App
+    # Database cleanup utilities for removing stale or incomplete records.
+    module Cleanup
+      # Remove nodes that appear incomplete and have not been updated recently.
+      #
+      # Nodes are considered incomplete when they retain the default Meshtastic
+      # name prefix (e.g., "Meshtastic 1234") and lack hardware model data.
+      # These entries typically result from brief mesh contacts that never
+      # exchanged full node information.
+      #
+      # @param cutoff_time [Integer] Unix timestamp threshold; nodes older than
+      #   this are eligible for removal.
+      # @return [Integer] count of nodes deleted.
+      def prune_stale_nodes(cutoff_time = nil)
+        cutoff_time ||= Time.now.to_i - PotatoMesh::Config.stale_node_min_age_seconds
+        db = open_database
+
+        sql = <<~SQL
+          DELETE FROM nodes
+          WHERE long_name LIKE 'Meshtastic%'
+            AND (hw_model IS NULL OR hw_model = '')
+            AND last_heard < ?
+        SQL
+
+        deleted_count = 0
+        with_busy_retry do
+          db.execute(sql, [cutoff_time])
+          deleted_count = db.changes
+        end
+
+        if deleted_count.positive?
+          info_log(
+            "Pruned stale nodes",
+            context: "cleanup.nodes",
+            count: deleted_count,
+            cutoff: cutoff_time,
+          )
+        else
+          debug_log(
+            "No stale nodes to prune",
+            context: "cleanup.nodes",
+            cutoff: cutoff_time,
+          )
+        end
+
+        deleted_count
+      rescue SQLite3::Exception => e
+        warn_log(
+          "Failed to prune stale nodes",
+          context: "cleanup.nodes",
+          error_class: e.class.name,
+          error_message: e.message,
+        )
+        0
+      ensure
+        db&.close
+      end
+
+      # Execute the stale node cleanup loop once.
+      #
+      # @return [Integer] number of nodes removed.
+      def run_stale_node_cleanup
+        prune_stale_nodes
+      end
+
+      # Launch a background thread responsible for periodic node cleanup.
+      #
+      # @return [Thread, nil] the thread handling cleanup, or nil when disabled.
+      def start_stale_node_cleanup_thread!
+        return nil unless PotatoMesh::Config.stale_node_cleanup_enabled?
+
+        existing = settings.respond_to?(:stale_node_cleanup_thread) ? settings.stale_node_cleanup_thread : nil
+        return existing if existing&.alive?
+
+        thread = Thread.new do
+          loop do
+            sleep PotatoMesh::Config.stale_node_cleanup_interval_seconds
+            begin
+              run_stale_node_cleanup
+            rescue StandardError => e
+              warn_log(
+                "Stale node cleanup loop error",
+                context: "cleanup.nodes",
+                error_class: e.class.name,
+                error_message: e.message,
+              )
+            end
+          end
+        end
+        thread.name = "potato-mesh-node-cleanup" if thread.respond_to?(:name=)
+        set(:stale_node_cleanup_thread, thread)
+        thread
+      end
+
+      # Halt the background cleanup thread if currently running.
+      #
+      # @return [void]
+      def stop_stale_node_cleanup_thread!
+        return unless settings.respond_to?(:stale_node_cleanup_thread)
+
+        thread = settings.stale_node_cleanup_thread
+        return unless thread&.alive?
+
+        thread.kill
+        thread.join(2)
+        set(:stale_node_cleanup_thread, nil)
+      end
+    end
+  end
+end

web/lib/potato_mesh/config.rb

@@ -42,6 +42,8 @@ module Config
     DEFAULT_FEDERATION_WORKER_QUEUE_CAPACITY = 128
     DEFAULT_FEDERATION_TASK_TIMEOUT_SECONDS = 120
     DEFAULT_INITIAL_FEDERATION_DELAY_SECONDS = 2
+    DEFAULT_STALE_NODE_CLEANUP_INTERVAL_HOURS = 0
+    DEFAULT_STALE_NODE_MIN_AGE_HOURS = 168
 
     # Retrieve the configured API token used for authenticated requests.
     #
@@ -429,6 +431,58 @@ def initial_federation_delay_seconds
       )
     end
 
+    # Determine how often stale nodes are removed from the database.
+    #
+    # Set `STALE_NODE_CLEANUP_INTERVAL` to a positive value in hours (e.g., `24`
+    # for daily) to enable automatic cleanup. Disabled by default.
+    #
+    # @return [Integer] hours between cleanup cycles (default 0 = disabled).
+    def stale_node_cleanup_interval_hours
+      raw = ENV["STALE_NODE_CLEANUP_INTERVAL"]
+      return DEFAULT_STALE_NODE_CLEANUP_INTERVAL_HOURS if raw.nil? || raw.strip.empty?
+
+      begin
+        parsed = Integer(raw.strip, 10)
+        parsed.negative? ? 0 : parsed
+      rescue ArgumentError
+        DEFAULT_STALE_NODE_CLEANUP_INTERVAL_HOURS
+      end
+    end
+
+    # Convert cleanup interval to seconds for internal scheduling.
+    #
+    # @return [Integer] seconds between cleanup cycles.
+    def stale_node_cleanup_interval_seconds
+      stale_node_cleanup_interval_hours * 3600
+    end
+
+    # Determine whether stale node cleanup is enabled.
+    #
+    # @return [Boolean] true when automatic cleanup should run.
+    def stale_node_cleanup_enabled?
+      stale_node_cleanup_interval_hours.positive?
+    end
+
+    # Minimum age in hours before an incomplete node is eligible for cleanup.
+    #
+    # Nodes with default names (e.g., "Meshtastic 1234") and missing hardware
+    # model information must exceed this age before removal.
+    #
+    # @return [Integer] hours before incomplete nodes can be pruned (default 168 = 7 days).
+    def stale_node_min_age_hours
+      fetch_positive_integer(
+        "STALE_NODE_MIN_AGE",
+        DEFAULT_STALE_NODE_MIN_AGE_HOURS,
+      )
+    end
+
+    # Convert minimum age to seconds for internal use.
+    #
+    # @return [Integer] seconds before incomplete nodes can be pruned.
+    def stale_node_min_age_seconds
+      stale_node_min_age_hours * 3600
+    end
+
     # Retrieve the configured site name for presentation.
     #
     # @return [String] human friendly site label.