feat: poll MMDB every 6 hours to mitigate upstream release drift

The daily scheduled update at 01:20 UTC was systematically lagging the
upstream mergedipdb release by 24h. The upstream cron nominally fires
at 01:00 UTC but GitHub Actions schedule latency shifts the actual
publish time anywhere from ~01:05 to ~06:00+ UTC, so any fixed
single-daily time misses the current release on delayed days.

Introduce DB_UPDATE_INTERVAL_HOURS (default 6, must divide 24 evenly),
shift the anchor DB_UPDATE_TIME_UTC default to 00:20, and replace
secs_until_next with secs_until_next_tick that schedules at anchor +
N*interval. Also set RUST_LOG=rustyip=info,warn in the Ansible env
template so the scheduler and "database updated successfully (N bytes)"
info logs are actually visible in docker logs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: NetworkCats

.env.example

@@ -7,9 +7,14 @@ DB_PATH=data/Merged-IP.mmdb
 # URL to download the MMDB database from
 DB_UPDATE_URL=https://github.com/NetworkCats/Merged-IP-Data/releases/latest/download/Merged-IP.mmdb
 
-# Daily UTC time to update the database (HH:MM format)
-# Merged IP Data releases at 01:00 UTC; this should be at least 20 minutes later
-DB_UPDATE_TIME_UTC=01:20
+# Update schedule: anchor time (HH:MM) + interval in hours.
+# Interval must divide 24 evenly (1, 2, 3, 4, 6, 8, 12, 24).
+# Default = every 6h starting at 00:20 UTC -> runs at 00:20, 06:20, 12:20, 18:20.
+# Upstream mergedipdb cron targets 01:00 UTC but GitHub Actions schedule
+# latency can push the actual release anywhere from ~01:05 to ~06:00+ UTC,
+# so we poll 4x/day to catch it whenever it lands.
+DB_UPDATE_TIME_UTC=00:20
+DB_UPDATE_INTERVAL_HOURS=6
 
 # Site domain name (used for display/metadata)
 SITE_DOMAIN=localhost

deploy/ansible/roles/app/templates/env.j2

@@ -1,7 +1,9 @@
 LISTEN_ADDR=0.0.0.0:3000
 DB_PATH=/data/Merged-IP.mmdb
 DB_UPDATE_URL={{ db_update_url }}
-DB_UPDATE_TIME_UTC={{ db_update_time_utc | default('01:20') }}
+DB_UPDATE_TIME_UTC={{ db_update_time_utc | default('00:20') }}
+DB_UPDATE_INTERVAL_HOURS={{ db_update_interval_hours | default('6') }}
+RUST_LOG={{ rust_log | default('rustyip=info,warn') }}
 SITE_DOMAIN={{ site_domain }}
 {% if ipv4_domain %}
 IPV4_DOMAIN={{ ipv4_domain }}

docker-compose.yml

@@ -21,7 +21,8 @@ services:
       - LISTEN_ADDR=0.0.0.0:3000
       - DB_PATH=/data/Merged-IP.mmdb
       - DB_UPDATE_URL=${DB_UPDATE_URL:-https://github.com/NetworkCats/Merged-IP-Data/releases/latest/download/Merged-IP.mmdb}
-      - DB_UPDATE_TIME_UTC=${DB_UPDATE_TIME_UTC:-01:20}
+      - DB_UPDATE_TIME_UTC=${DB_UPDATE_TIME_UTC:-00:20}
+      - DB_UPDATE_INTERVAL_HOURS=${DB_UPDATE_INTERVAL_HOURS:-6}
       - SITE_DOMAIN=${SITE_DOMAIN:-localhost}
       - IPV4_DOMAIN=${IPV4_DOMAIN:-}
     volumes:

src/config.rs

@@ -7,8 +7,11 @@ pub struct Config {
     pub listen_addr: SocketAddr,
     pub db_path: String,
     pub db_update_url: String,
-    /// Daily UTC time to check for database updates, as (hour, minute).
+    /// Anchor UTC time for the update schedule, as (hour, minute).
+    /// Updates run at this time and every `db_update_interval_hours` thereafter.
     pub db_update_time_utc: (u8, u8),
+    /// Hours between update ticks. Must divide 24 evenly (1, 2, 3, 4, 6, 8, 12, 24).
+    pub db_update_interval_hours: u8,
     pub site_domain: String,
     pub ipv4_domain: String,
     pub dev_mode: bool,
@@ -32,6 +35,22 @@ fn parse_time_utc(s: &str) -> (u8, u8) {
     (hour, minute)
 }
 
+/// Parses the interval-hours string, panicking on invalid input or values that do not divide 24 evenly.
+fn parse_interval_hours(s: &str) -> u8 {
+    let v: u8 = s
+        .parse()
+        .expect("DB_UPDATE_INTERVAL_HOURS must be a valid integer 1-24");
+    assert!(
+        (1..=24).contains(&v),
+        "DB_UPDATE_INTERVAL_HOURS must be 1-24"
+    );
+    assert!(
+        24 % v == 0,
+        "DB_UPDATE_INTERVAL_HOURS must divide 24 evenly (1, 2, 3, 4, 6, 8, 12, 24)"
+    );
+    v
+}
+
 impl Config {
     pub fn from_env() -> Self {
         let listen_addr = env::var("LISTEN_ADDR")
@@ -47,7 +66,11 @@ impl Config {
         });
 
         let db_update_time_utc =
-            parse_time_utc(&env::var("DB_UPDATE_TIME_UTC").unwrap_or_else(|_| "01:20".to_string()));
+            parse_time_utc(&env::var("DB_UPDATE_TIME_UTC").unwrap_or_else(|_| "00:20".to_string()));
+
+        let db_update_interval_hours = parse_interval_hours(
+            &env::var("DB_UPDATE_INTERVAL_HOURS").unwrap_or_else(|_| "6".to_string()),
+        );
 
         let site_domain = env::var("SITE_DOMAIN").unwrap_or_else(|_| "localhost".to_string());
 
@@ -62,6 +85,7 @@ impl Config {
             db_path,
             db_update_url,
             db_update_time_utc,
+            db_update_interval_hours,
             site_domain,
             ipv4_domain,
             dev_mode,
@@ -89,6 +113,7 @@ mod tests {
         "DB_PATH",
         "DB_UPDATE_URL",
         "DB_UPDATE_TIME_UTC",
+        "DB_UPDATE_INTERVAL_HOURS",
         "SITE_DOMAIN",
         "IPV4_DOMAIN",
         "DEV_MODE",
@@ -120,7 +145,8 @@ mod tests {
         assert_eq!(config.listen_addr.to_string(), "0.0.0.0:3000");
         assert_eq!(config.db_path, "data/Merged-IP.mmdb");
         assert!(config.db_update_url.contains("Merged-IP.mmdb"));
-        assert_eq!(config.db_update_time_utc, (1, 20));
+        assert_eq!(config.db_update_time_utc, (0, 20));
+        assert_eq!(config.db_update_interval_hours, 6);
         assert_eq!(config.site_domain, "localhost");
         assert!(config.ipv4_domain.is_empty());
         assert!(!config.dev_mode);
@@ -190,6 +216,22 @@ mod tests {
         unsafe { remove_var("DB_UPDATE_TIME_UTC") };
     }
 
+    #[test]
+    fn custom_update_interval() {
+        let _guard = lock_env();
+        // SAFETY: ENV_LOCK is held.
+        unsafe {
+            clear_config_vars();
+            set_var("DB_UPDATE_INTERVAL_HOURS", "12");
+        }
+
+        let config = Config::from_env();
+        assert_eq!(config.db_update_interval_hours, 12);
+
+        // SAFETY: ENV_LOCK is held.
+        unsafe { remove_var("DB_UPDATE_INTERVAL_HOURS") };
+    }
+
     #[test]
     fn custom_site_domain() {
         let _guard = lock_env();
@@ -315,4 +357,43 @@ mod tests {
 
         let _config = Config::from_env();
     }
+
+    #[test]
+    #[should_panic(expected = "DB_UPDATE_INTERVAL_HOURS must divide 24 evenly")]
+    fn update_interval_non_divisor_panics() {
+        let _guard = lock_env();
+        // SAFETY: ENV_LOCK is held.
+        unsafe {
+            clear_config_vars();
+            set_var("DB_UPDATE_INTERVAL_HOURS", "5");
+        }
+
+        let _config = Config::from_env();
+    }
+
+    #[test]
+    #[should_panic(expected = "DB_UPDATE_INTERVAL_HOURS must be 1-24")]
+    fn update_interval_zero_panics() {
+        let _guard = lock_env();
+        // SAFETY: ENV_LOCK is held.
+        unsafe {
+            clear_config_vars();
+            set_var("DB_UPDATE_INTERVAL_HOURS", "0");
+        }
+
+        let _config = Config::from_env();
+    }
+
+    #[test]
+    #[should_panic(expected = "DB_UPDATE_INTERVAL_HOURS must be a valid integer 1-24")]
+    fn update_interval_invalid_panics() {
+        let _guard = lock_env();
+        // SAFETY: ENV_LOCK is held.
+        unsafe {
+            clear_config_vars();
+            set_var("DB_UPDATE_INTERVAL_HOURS", "not-a-number");
+        }
+
+        let _config = Config::from_env();
+    }
 }

src/main.rs

@@ -76,6 +76,7 @@ async fn main() {
             init_path,
             init_url,
             config.db_update_time_utc,
+            config.db_update_interval_hours,
             init_cancel,
         )
         .await;

src/updater.rs

@@ -104,38 +104,49 @@ pub fn spawn_updater(
     db_path: PathBuf,
     update_url: String,
     update_time_utc: (u8, u8),
+    interval_hours: u8,
     cancel: CancellationToken,
 ) -> JoinHandle<()> {
     tokio::spawn(run_updater(
         shared_db,
         db_path,
         update_url,
         update_time_utc,
+        interval_hours,
         cancel,
     ))
 }
 
 /// Returns the number of seconds from `now_secs` (seconds since UNIX epoch)
-/// until the next occurrence of the given UTC `(hour, minute)`.
-fn secs_until_next(now_secs: u64, hour: u8, minute: u8) -> u64 {
+/// until the next tick. Ticks occur at `(anchor_hour, anchor_minute)` UTC and
+/// every `interval_hours` thereafter. `interval_hours` must divide 24 evenly.
+fn secs_until_next_tick(
+    now_secs: u64,
+    anchor_hour: u8,
+    anchor_minute: u8,
+    interval_hours: u8,
+) -> u64 {
     const SECS_PER_DAY: u64 = 86_400;
+    let interval = u64::from(interval_hours) * 3600;
+    let anchor = u64::from(anchor_hour) * 3600 + u64::from(anchor_minute) * 60;
     let time_of_day = now_secs % SECS_PER_DAY;
-    let target = u64::from(hour) * 3600 + u64::from(minute) * 60;
-    if target > time_of_day {
-        target - time_of_day
+    let offset_from_anchor = if time_of_day >= anchor {
+        time_of_day - anchor
     } else {
-        // Target time already passed today; schedule for tomorrow.
-        SECS_PER_DAY - time_of_day + target
-    }
+        SECS_PER_DAY - (anchor - time_of_day)
+    };
+    let next_boundary = ((offset_from_anchor / interval) + 1) * interval;
+    next_boundary - offset_from_anchor
 }
 
-/// Runs the daily database updater loop. Sleeps until the configured UTC time
-/// each day, then downloads and swaps in a fresh database.
+/// Runs the database updater loop. Sleeps until the next scheduled tick, then
+/// downloads and hot-swaps a fresh database.
 pub async fn run_updater(
     shared_db: SharedDb,
     db_path: PathBuf,
     update_url: String,
     update_time_utc: (u8, u8),
+    interval_hours: u8,
     cancel: CancellationToken,
 ) {
     let (hour, minute) = update_time_utc;
@@ -144,13 +155,15 @@ pub async fn run_updater(
             .duration_since(UNIX_EPOCH)
             .expect("system clock before UNIX epoch")
             .as_secs();
-        let delay = Duration::from_secs(secs_until_next(now_secs, hour, minute));
+        let delay =
+            Duration::from_secs(secs_until_next_tick(now_secs, hour, minute, interval_hours));
         info!(
-            "next database update in {}h {}m (at {:02}:{:02} UTC)",
+            "next database update in {}h {}m (anchor {:02}:{:02} UTC, every {}h)",
             delay.as_secs() / 3600,
             (delay.as_secs() % 3600) / 60,
             hour,
             minute,
+            interval_hours,
         );
         tokio::select! {
             () = tokio::time::sleep(delay) => {}
@@ -172,7 +185,12 @@ async fn update_db(
 ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     let reader = download_db(update_url, db_path).await?;
     shared_db.store(Arc::new(Some(reader)));
-    info!("database updated successfully");
+    let size = fs::metadata(db_path)
+        .await
+        .ok()
+        .map(|m| m.len())
+        .unwrap_or(0);
+    info!("database updated successfully ({size} bytes)");
     Ok(())
 }
 
@@ -279,7 +297,8 @@ mod tests {
             shared_db,
             PathBuf::from("/nonexistent/path.mmdb"),
             "https://invalid.example.com/db.mmdb".to_string(),
-            (1, 20),
+            (0, 20),
+            6,
             cancel.clone(),
         );
 
@@ -293,31 +312,57 @@ mod tests {
     }
 
     #[test]
-    fn secs_until_next_later_today() {
-        // 00:00:00 UTC, target 01:20 UTC => 1h 20m = 4800s
-        assert_eq!(secs_until_next(0, 1, 20), 4800);
+    fn secs_until_next_tick_daily_from_midnight() {
+        // 00:00 UTC, anchor 01:20, interval 24h => 1h 20m = 4800s.
+        assert_eq!(secs_until_next_tick(0, 1, 20, 24), 4800);
+    }
+
+    #[test]
+    fn secs_until_next_tick_daily_wraps_to_tomorrow() {
+        // 02:00 UTC (7200s), anchor 01:20 (4800s), interval 24h
+        // => 86400 - 7200 + 4800 = 84000s.
+        assert_eq!(secs_until_next_tick(7200, 1, 20, 24), 84000);
+    }
+
+    #[test]
+    fn secs_until_next_tick_daily_exact_time_wraps() {
+        // Exactly at the anchor with 24h interval => schedule for next day.
+        let target_secs = 3600 + 20 * 60;
+        assert_eq!(secs_until_next_tick(target_secs, 1, 20, 24), 86400);
+    }
+
+    #[test]
+    fn secs_until_next_tick_every_six_hours_at_midnight() {
+        // 00:00 UTC with anchor 00:20 and interval 6h => next tick in 20m = 1200s.
+        assert_eq!(secs_until_next_tick(0, 0, 20, 6), 1200);
+    }
+
+    #[test]
+    fn secs_until_next_tick_every_six_hours_just_after_tick() {
+        // 00:21 UTC (1260s), anchor 00:20, interval 6h
+        // => next tick is 06:20 UTC = 6h - 1m = 21540s.
+        let now_secs = 20 * 60 + 60; // 00:21
+        assert_eq!(secs_until_next_tick(now_secs, 0, 20, 6), 21540);
     }
 
     #[test]
-    fn secs_until_next_wraps_to_tomorrow() {
-        // 02:00:00 UTC (7200s into the day), target 01:20 (4800s into the day)
-        // => should wrap to next day: 86400 - 7200 + 4800 = 84000s
-        let now_secs = 7200; // midnight + 2 hours
-        assert_eq!(secs_until_next(now_secs, 1, 20), 84000);
+    fn secs_until_next_tick_every_six_hours_at_tick() {
+        // Exactly at a tick (00:20) with 6h interval => schedule for 6h later.
+        let target_secs = 20 * 60;
+        assert_eq!(secs_until_next_tick(target_secs, 0, 20, 6), 6 * 3600);
     }
 
     #[test]
-    fn secs_until_next_exact_time_wraps_to_tomorrow() {
-        // Exactly at the target time => should schedule for next day (full 24h).
-        let target_secs = 1 * 3600 + 20 * 60; // 01:20 = 4800s
-        assert_eq!(secs_until_next(target_secs, 1, 20), 86400);
+    fn secs_until_next_tick_every_six_hours_before_anchor() {
+        // 00:10 UTC (600s), anchor 00:20, interval 6h => next tick in 10m = 600s.
+        assert_eq!(secs_until_next_tick(600, 0, 20, 6), 600);
     }
 
     #[test]
-    fn secs_until_next_midnight_target() {
-        // 23:00:00 UTC, target 00:00 UTC => 1 hour = 3600s
+    fn secs_until_next_tick_midnight_target() {
+        // 23:00 UTC, anchor 00:00, interval 24h => 1h = 3600s.
         let now_secs = 23 * 3600;
-        assert_eq!(secs_until_next(now_secs, 0, 0), 3600);
+        assert_eq!(secs_until_next_tick(now_secs, 0, 0, 24), 3600);
     }
 
     #[tokio::test]