Add first-seen and last-seen DNS history metadata

.github/workflows/dns-history-test.yml

@@ -0,0 +1,31 @@
+name: DNS history regression test
+
+on:
+  pull_request:
+    paths:
+      - "dooked/**"
+      - ".github/workflows/dns-history-test.yml"
+  push:
+    branches:
+      - master
+      - main
+
+jobs:
+  dns-history-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Configure isolated history test
+        run: >
+          cmake -S dooked -B build
+          -DCMAKE_POLICY_VERSION_MINIMUM=3.5
+          -DDOOKED_BUILD_HISTORY_TESTS=ON
+
+      - name: Build isolated history test
+        run: cmake --build build --target dooked_dns_history_test --config Release
+
+      - name: Run isolated history test
+        run: ctest --test-dir build --output-on-failure

README.md

@@ -39,3 +39,31 @@ make
 ## Usage
 
 For comprehensive help, use `dooked --help`
+
+### DNS history metadata
+
+When a previous JSON result is used as input, dooked preserves DNS record
+history in each `dns_probe` item:
+
+- `first-seen`: when this DNS record was first observed.
+- `last-seen`: when this DNS record was most recently observed.
+- `seen`: how many runs have observed this DNS record.
+- `currently-seen`: whether this DNS record was present in the latest run.
+
+Historical records that are missing from the latest DNS response are kept in
+the JSON output with `currently-seen: false`. This keeps load-balanced or
+rotating records searchable without making the default comparison repeatedly
+report old historical records as newly missing.
+
+Useful flags:
+
+```
+dooked -i previous.json --fs
+dooked -i previous.json --ls 2
+dooked -i previous.json --lsd "03/15/2021"
+```
+
+- `--fs` / `--first-seen`: print records first observed in the current run.
+- `--ls` / `--last-seen N`: print missing records last seen at least `N` days ago.
+- `--lsd` / `--last-seen-date`: print missing records last seen before a US
+  date or datetime, for example `03/15/2021` or `03/15/2021 14:30:00`.

dooked/CMakeLists.txt

@@ -43,13 +43,13 @@ endif(NOT CMAKE_BUILD_TYPE)
 ############################################################
 
 if(CMAKE_BUILD_TYPE STREQUAL "Debug")
-  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_DIR}/${OUTPUT_DEBUG}")
-  set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_DIR}/${OUTPUT_DEBUG}")
-  set(CMAKE_EXECUTABLE_OUTPUT_DIRECTORY "${PROJECT_DIR}/${OUTPUT_DEBUG}")
+  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${OUTPUT_DEBUG}")
+  set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${OUTPUT_DEBUG}")
+  set(CMAKE_EXECUTABLE_OUTPUT_DIRECTORY "${OUTPUT_DEBUG}")
 else()
-  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_DIR}/${OUTPUT_RELEASE}")
-  set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${PROJECT_DIR}/${OUTPUT_RELEASE}")
-  set(CMAKE_EXECUTABLE_OUTPUT_DIRECTORY "${PROJECT_DIR}/${OUTPUT_RELEASE}")
+  set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${OUTPUT_RELEASE}")
+  set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${OUTPUT_RELEASE}")
+  set(CMAKE_EXECUTABLE_OUTPUT_DIRECTORY "${OUTPUT_RELEASE}")
 endif()
 
 # Messages
@@ -103,6 +103,25 @@ add_executable(${PROJECT_NAME}
    ${SRC_FILES} ${HEADERS_FILES}
 )
 
+option(DOOKED_BUILD_HISTORY_TESTS "Build DNS history metadata regression tests" OFF)
+
+if(DOOKED_BUILD_HISTORY_TESTS)
+  enable_testing()
+  add_executable(dooked_dns_history_test
+    ./tests/dns_history_test.cpp
+    ./source/utils/constants.cpp
+    ./source/utils/io_utils.cpp
+    ./source/utils/string_utils.cpp
+  )
+  set_target_properties(dooked_dns_history_test PROPERTIES LINK_LIBRARIES "")
+  target_compile_features(dooked_dns_history_test PRIVATE cxx_std_17)
+  target_include_directories(dooked_dns_history_test PRIVATE
+    ${PROJECT_DIR}/include
+    ${PROJECT_DIR}/json/single_include
+  )
+  add_test(NAME dooked_dns_history_test COMMAND dooked_dns_history_test)
+endif()
+
 if(NOT MSVC)
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++17 -O3")
    if ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")

dooked/include/cli_preprocessor.hpp

@@ -24,7 +24,10 @@ struct cli_args_t {
   int post_http_request{};
   int thread_count{};
   int content_length{-1};
+  int last_seen_days{-1};
+  std::string last_seen_date{};
   bool include_date{false};
+  bool show_first_seen{false};
 };
 
 struct runtime_args_t {
@@ -36,6 +39,9 @@ struct runtime_args_t {
   http_process_e http_request_time_{};
   int thread_count{};
   int content_length{-1};
+  int last_seen_days{-1};
+  std::string last_seen_date{};
+  bool show_first_seen{false};
 };
 
 void run_program(cli_args_t const &cli_args);