GeoResolver

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: Implementation. The file contains 252 lines and belongs to the util/GeoResolver.cpp path.

The companion file is util/GeoResolver.hpp.

2. Component Responsibilities

  • Implement the behavior declared by the corresponding header or entry-point contract.
  • 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

Project-level dependencies:

  • GeoResolver.hpp
  • arpa/inet.h
  • netdb.h
  • nlohmann/json.hpp
  • sys/socket.h
  • sys/types.h
  • unistd.h

System and library dependencies:

  • cstring

4. Constants and Fixed Configuration

The file declares or uses the following fixed values:

constexpr auto kCacheTtl = std::chrono::hours(24);
constexpr auto kMinInterval = std::chrono::milliseconds(1500);

5. Functions and Methods

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

1. instance

GeoResolver& GeoResolver::instance()

Implements the instance operation declared by this component.

2. GeoResolver

GeoResolver::GeoResolver()

Constructs the object, initializes its state, builds required resources, and connects the relevant callbacks.

3. ~GeoResolver

GeoResolver::~GeoResolver()

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

4. stop

void GeoResolver::stop()

Stops stop and releases or signals its active resources.

5. is_private_ip

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

Returns whether private ip satisfies the tested condition.

6. resolve

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

Resolves resolve into normalized metadata or runtime data.

7. resolve_self

std::optional<GeoEntry> GeoResolver::resolve_self()

Resolves self into normalized metadata or runtime data.

8. on_resolved

void GeoResolver::on_resolved(ResolvedCallback cb)

Handles the resolved callback or user event.

9. fetch_from_ipapi

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

Fetches from ipapi from the external source.

10. worker_loop

void GeoResolver::worker_loop()

Runs the background worker loop processing loop.

6. Filesystem, IPC, Network, and Command Interfaces

Relevant literal paths, endpoints, or resource locations include:

  • /json/

Relevant command or protocol construction lines include:

std::string req = "GET " + path + " HTTP/1.0\r\n";

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.

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.
  • JSON input and output must be treated as external data and validated before applying decisions.
  • Socket lifecycle and framing errors are handled without performing GTK operations directly from the I/O thread.

10. Error Handling and Operational Notes

  • Exceptions are caught locally in one or more operations to prevent application-wide termination.
  • Boolean-returning operations use false to report recoverable failure.
  • Optional results distinguish unavailable data from valid empty values.

11. Source Integrity

Relative source path: util/GeoResolver.cpp

SHA-256:

d77bee2487459e7e43c7dd7939e6eb8d1c721f3b10d918278922e23e5f1b1447

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: