GeoResolver.hpp

1. Overview

Asynchronous IP geolocation service that resolves remote addresses to country, city, coordinates, ISP, and ASN data using ip-api.com, with caching, rate limiting, private-address filtering, and callback delivery.

File role: Header Interface. The file contains 110 lines and belongs to the util/GeoResolver.hpp path.

The companion file is util/GeoResolver.cpp.

2. Component Responsibilities

  • Declare the component API, owned state, callbacks, and data structures.
  • Return cached entries immediately when valid
  • Reject private or local addresses
  • Queue unresolved public IP addresses
  • Process lookups in a dedicated worker thread
  • Rate-limit HTTP requests
  • Parse JSON responses and update the 24-hour cache
  • Notify registered callbacks after resolution

3. Dependencies and Integration

System and library dependencies:

  • atomic
  • chrono
  • condition_variable
  • functional
  • mutex
  • optional
  • queue
  • string
  • thread
  • unordered_map
  • unordered_set

4. Declared Types

GeoEntry

Declares a struct.

GeoResolver

Declares a class.

5. Owned State and UI Members

Threading, dispatch, and callback state

  • std::mutex mu_;
  • std::condition_variable cv_;
  • std::atomic_bool running_{true};
  • std::thread worker_;

Data and configuration state

  • std::string country_code;
  • std::string country_name;
  • std::string city;
  • std::string region;
  • std::string isp;
  • std::string asn;
  • double lat{0.0};
  • double lon{0.0};
  • std::chrono::steady_clock::time_point fetched_at;
  • std::queue<std::string> queue_;
  • std::unordered_set<std::string> in_flight_;
  • std::unordered_map<std::string, GeoEntry> cache_;
  • std::vector<ResolvedCallback> callbacks_;
  • std::chrono::steady_clock::time_point last_request_{};

6. Functions and Methods

The file exposes or implements 10 detected function or method signatures.

1. instance

static GeoResolver& instance()

Implements the instance operation declared by this component.

2. resolve

std::optional<GeoEntry> resolve(const std::string& ip)

Resolves resolve into normalized metadata or runtime data.

3. resolve_self

std::optional<GeoEntry> resolve_self()

Resolves self into normalized metadata or runtime data.

4. on_resolved

void on_resolved(ResolvedCallback cb)

Handles the resolved callback or user event.

5. stop

void stop()

Stops stop and releases or signals its active resources.

6. GeoResolver

GeoResolver()

Implements the geo resolver operation declared by this component.

7. ~GeoResolver

~GeoResolver()

Releases resources owned by the object and stops any active background integration.

8. worker_loop

void worker_loop()

Runs the background worker loop processing loop.

9. fetch_from_ipapi

std::optional<GeoEntry> fetch_from_ipapi(const std::string& ip)

Fetches from ipapi from the external source.

10. is_private_ip

static bool is_private_ip(const std::string& ip)

Returns whether private ip satisfies the tested condition.

7. Runtime Flow

  1. Return cached entries immediately when valid
  2. Reject private or local addresses
  3. Queue unresolved public IP addresses
  4. Process lookups in a dedicated worker thread
  5. Rate-limit HTTP requests
  6. Parse JSON responses and update the 24-hour cache
  7. Notify registered callbacks after resolution

8. Concurrency and Main-Loop Behavior

  • Uses one or more C++ worker threads.
  • Protects shared state with a mutex.
  • Uses a condition variable for worker wake-up and shutdown coordination.
  • Uses atomic state for cross-thread lifecycle control.

9. Runtime and Security Considerations

  • Does not send private/local addresses to the external geolocation service.
  • Uses a worker thread so network failures do not block the GTK interface.
  • Applies a client-side request interval and finite socket timeout.

10. Error Handling and Operational Notes

  • Exceptions are caught locally in one or more operations to prevent application-wide termination.
  • Optional results distinguish unavailable data from valid empty values.

11. Source Integrity

Relative source path: util/GeoResolver.hpp

SHA-256:

92dec53cedb5b250f7eb8815ed17d32de5f03498925510d6d6f6490808be064d

12. Licensing

The source header identifies this component as distributed under the GNU General Public License version 3. BastionGuard branding and trademarks remain subject to the notices stated in the source file.

Published on:
Last updated on: