Zero-Downtime MMDB Hot-Reloads: Atomic POSIX mmap Swaps in Go, Rust, and Node.js

# DO NOT DO THIS IN PRODUCTION!
curl -fsSL -H "Authorization: Bearer ${KEY}" \
  -o /var/lib/ipscope/ipscope-complete.mmdb \
  "https://api.ipscope.io/v1/mmdb/releases/latest/download?format=mmdb"

BEFORE RENAME:
  Directory Entry: "ipscope-complete.mmdb"  --->  [ Inode #40112 (141 MB, Old Snapshot) ]
                                                        ^
                                                        | (Active mmap VMA)
                                                  [ Live Go/Rust/NGINX Workers ]

STEP 1: Stage & Verify New File on the SAME Filesystem Mount:
  Directory Entry: ".stage.ipscope.9a8f12"  --->  [ Inode #88304 (142 MB, New Snapshot) ]

STEP 2: Atomic rename(".stage.ipscope.9a8f12", "ipscope-complete.mmdb"):
  Directory Entry: "ipscope-complete.mmdb"  --->  [ Inode #88304 (142 MB, New Snapshot) ]

  Meanwhile, Inode #40112 (Old Snapshot) has link_count = 0 on disk,
  but its kernel reference count > 0 because live workers still hold the old mmap!
  Inode #40112 remains 100% intact in the OS page cache until the last worker calls munmap().

#!/usr/bin/env bash
set -euo pipefail

DB_DIR="${IPSCOPE_DB_DIR:-/var/lib/ipscope}"
DB_FILENAME="${IPSCOPE_DB_FILENAME:-ipscope-complete.mmdb}"
TARGET="${DB_DIR}/${DB_FILENAME}"
ETAG_FILE="${DB_DIR}/.${DB_FILENAME}.etag"
API_BASE="${IPSCOPE_API_BASE:-https://api.ipscope.io}"

if [ -z "${IPSCOPE_DOWNLOAD_KEY:-}" ]; then
  echo "ERROR: IPSCOPE_DOWNLOAD_KEY environment variable is not set" >&2
  exit 1
fi

mkdir -p "$DB_DIR"

# Create temporary staging inode in the SAME directory as TARGET
STAGE="$(mktemp "${DB_DIR}/.stage.${DB_FILENAME}.XXXXXX")"
ETAG_TMP="$(mktemp "${DB_DIR}/.etag.${DB_FILENAME}.XXXXXX")"

cleanup() {
  rm -f "$STAGE" "$ETAG_TMP"
}
trap cleanup EXIT

CURL_ETAG_ARGS=()
if [ -f "$ETAG_FILE" ] && [ -f "$TARGET" ]; then
  CURL_ETAG_ARGS=(--etag-compare "$ETAG_FILE")
fi

# 1. Download artifact with conditional ETag support
HTTP_STATUS="$(curl -sS -L -w "%{http_code}" \
  --retry 3 --retry-delay 2 --max-time 300 \
  -H "Authorization: Bearer ${IPSCOPE_DOWNLOAD_KEY}" \
  "${CURL_ETAG_ARGS[@]}" \
  --etag-save "$ETAG_TMP" \
  -o "$STAGE" \
  "${API_BASE}/v1/mmdb/releases/latest/download?format=mmdb")"

if [ "$HTTP_STATUS" = "304" ]; then
  echo "[ipscope-sync] Local ${DB_FILENAME} is already up to date (HTTP 304)."
  exit 0
fi

if [ "$HTTP_STATUS" != "200" ]; then
  echo "ERROR: Download failed with HTTP status ${HTTP_STATUS}" >&2
  exit 1
fi

# 2. Fetch and verify cryptographic SHA-256 digest
EXPECTED_SHA256="$(curl -fsSL \
  --retry 3 --max-time 30 \
  -H "Authorization: Bearer ${IPSCOPE_DOWNLOAD_KEY}" \
  "${API_BASE}/v1/mmdb/releases/latest/checksums?format=text" \
  | awk '/\.mmdb$/ {print $1; exit}')"

if [ -z "$EXPECTED_SHA256" ]; then
  echo "ERROR: Could not parse .mmdb SHA-256 from checksums endpoint" >&2
  exit 1
fi

if command -v sha256sum >/dev/null 2>&1; then
  ACTUAL_SHA256="$(sha256sum "$STAGE" | awk '{print $1}')"
else
  ACTUAL_SHA256="$(shasum -a 256 "$STAGE" | awk '{print $1}')"
fi

if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
  echo "ERROR: SHA-256 mismatch! expected=${EXPECTED_SHA256} actual=${ACTUAL_SHA256}" >&2
  exit 1
fi

# 3. Flush staging inode pages to disk, set permissions, and perform atomic POSIX rename(2)
chmod 0644 "$STAGE"
sync "$STAGE"
mv -f "$STAGE" "$TARGET"
mv -f "$ETAG_TMP" "$ETAG_FILE"

echo "[ipscope-sync] Atomically promoted new ${DB_FILENAME} (sha256=${ACTUAL_SHA256})."

package ipdb

import (
	"fmt"
	"net"
	"os"
	"sync/atomic"
	"syscall"
	"time"

	"github.com/oschwald/maxminddb-golang"
)

type readerSnapshot struct {
	reader *maxminddb.Reader
	inode  uint64
}

type AtomicMMDB struct {
	path    string
	current atomic.Pointer[readerSnapshot]
}

func fileInode(path string) (uint64, error) {
	info, err := os.Stat(path)
	if err != nil {
		return 0, err
	}
	if stat, ok := info.Sys().(*syscall.Stat_t); ok {
		return stat.Ino, nil
	}
	return uint64(info.ModTime().UnixNano()), nil
}

func NewAtomicMMDB(path string) (*AtomicMMDB, error) {
	ino, err := fileInode(path)
	if err != nil {
		return nil, fmt.Errorf("stat mmdb: %w", err)
	}
	r, err := maxminddb.Open(path)
	if err != nil {
		return nil, fmt.Errorf("open mmdb: %w", err)
	}

	// Canary sanity check before accepting reader
	var probe map[string]any
	if err := r.Lookup(net.ParseIP("1.1.1.1"), &probe); err != nil {
		_ = r.Close()
		return nil, fmt.Errorf("canary lookup failed: %w", err)
	}

	m := &AtomicMMDB{path: path}
	m.current.Store(&readerSnapshot{reader: r, inode: ino})
	return m, nil
}

// ReloadIfInodeChanged checks whether the target path points to a new inode.
// If so, it opens the new mmap, validates a canary IP, atomically swaps the pointer,
// and drains the old mmap after a 10-second grace period.
func (m *AtomicMMDB) ReloadIfInodeChanged() (bool, error) {
	newInode, err := fileInode(m.path)
	if err != nil {
		return false, err
	}

	cur := m.current.Load()
	if cur != nil && cur.inode == newInode {
		return false, nil // Same inode, nothing to reload
	}

	nextReader, err := maxminddb.Open(m.path)
	if err != nil {
		return false, fmt.Errorf("open new mmdb inode: %w", err)
	}

	// Canary lookup on new reader before exposing it to live traffic
	var canary map[string]any
	if err := nextReader.Lookup(net.ParseIP("1.1.1.1"), &canary); err != nil {
		_ = nextReader.Close()
		return false, fmt.Errorf("new mmdb failed canary check: %w", err)
	}

	prev := m.current.Swap(&readerSnapshot{
		reader: nextReader,
		inode:  newInode,
	})

	if prev != nil && prev.reader != nil {
		go func(old *maxminddb.Reader) {
			// Allow all in-flight sub-microsecond lookups on the old pointer to complete
			time.Sleep(10 * time.Second)
			_ = old.Close()
		}(prev.reader)
	}

	return true, nil
}

// Lookup executes on the hot path with zero locks and zero allocations.
func (m *AtomicMMDB) Lookup(ip net.IP, result any) error {
	return m.current.Load().reader.Lookup(ip, result)
}

use arc_swap::ArcSwap;
use maxminddb::Reader;
use memmap2::Mmap;
use serde::de::DeserializeOwned;
use std::net::IpAddr;
use std::path::{Path, PathBuf};
use std::sync::Arc;

pub struct HotReloadMmdb {
    path: PathBuf,
    reader: ArcSwap<Reader<Mmap>>,
}

impl HotReloadMmdb {
    pub fn open(path: impl AsRef<Path>) -> Result<Self, maxminddb::MaxMindDBError> {
        let path_buf = path.as_ref().to_path_buf();
        let initial = Reader::open_mmap(&path_buf)?;
        Ok(Self {
            path: path_buf,
            reader: ArcSwap::from_pointee(initial),
        })
    }

    /// Atomically swaps in a freshly memory-mapped `.mmdb` reader.
    /// Any thread currently executing `lookup()` holds an `Arc` guard to the old
    /// `Reader<Mmap>`, so the old `Mmap` is unmapped automatically the instant
    /// the last in-flight lookup guard drops!
    pub fn reload(&self) -> Result<(), maxminddb::MaxMindDBError> {
        let next_reader = Reader::open_mmap(&self.path)?;
        // Validate canary lookup before swapping
        let canary_ip: IpAddr = "1.1.1.1".parse().unwrap();
        let _: Option<serde_json::Value> = next_reader.lookup(canary_ip)?;

        self.reader.store(Arc::new(next_reader));
        Ok(())
    }

    #[inline]
    pub fn lookup<T: DeserializeOwned>(
        &self,
        ip: IpAddr,
    ) -> Result<Option<T>, maxminddb::MaxMindDBError> {
        let guard = self.reader.load();
        guard.lookup::<T>(ip)
    }
}

import maxmind, { type Reader, type Response } from 'maxmind';

export class HotReloadMmdbReader<T extends Response> {
  private reader!: Reader<T>;
  private readonly dbPath: string;

  private constructor(dbPath: string, initialReader: Reader<T>) {
    this.dbPath = dbPath;
    this.reader = initialReader;
  }

  public static async open<T extends Response>(dbPath: string): Promise<HotReloadMmdbReader<T>> {
    const initial = await maxmind.open<T>(dbPath);
    return new HotReloadMmdbReader<T>(dbPath, initial);
  }

  public async reload(): Promise<void> {
    const nextReader = await maxmind.open<T>(this.dbPath);
    // Validate canary lookup before replacing live reference
    nextReader.get('1.1.1.1');
    this.reader = nextReader;
  }

  public lookup(ip: string): T | null {
    return this.reader.get(ip);
  }
}