Move brewery reverse geocoding from C# seeding to C++ pipeline (#249)

tooling/pipeline/includes/services/address/address_service.h

@@ -0,0 +1,40 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_ADDRESS_SERVICE_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_ADDRESS_SERVICE_H_
+
+/**
+ * @file services/address/address_service.h
+ * @brief Abstraction for resolving a street address from coordinates.
+ */
+
+#include <optional>
+#include <string>
+
+/**
+ * @brief Street-level address resolved from a coordinate pair.
+ */
+struct AddressLookupResult {
+   std::string address_line1;
+   std::string postal_code;
+};
+
+/**
+ * @brief Interface for services that reverse-geocode coordinates into a
+ * street address.
+ */
+class IAddressService {
+  public:
+   virtual ~IAddressService() = default;
+
+   /**
+    * @brief Reverse-geocodes a coordinate pair into a street address.
+    *
+    * @param longitude Longitude of the point to resolve.
+    * @param latitude Latitude of the point to resolve.
+    * @return The resolved address, or std::nullopt if it could not be
+    * resolved.
+    */
+   virtual std::optional<AddressLookupResult> ReverseGeocode(
+       double longitude, double latitude) = 0;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_ADDRESS_SERVICE_H_

tooling/pipeline/includes/services/address/mock_address_service.h

@@ -0,0 +1,27 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_MOCK_ADDRESS_SERVICE_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_MOCK_ADDRESS_SERVICE_H_
+
+/**
+ * @file services/address/mock_address_service.h
+ * @brief Deterministic IAddressService used when network geocoding is
+ * disabled.
+ */
+
+#include <optional>
+
+#include "services/address/address_service.h"
+
+/**
+ * @brief Address service that returns a fixed placeholder address for any
+ * coordinate pair, without making network calls.
+ */
+class MockAddressService final : public IAddressService {
+  public:
+   std::optional<AddressLookupResult> ReverseGeocode(
+       double /*longitude*/, double /*latitude*/) override {
+      return AddressLookupResult{.address_line1 = "123 Mock Street",
+                                 .postal_code = "00000"};
+   }
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_MOCK_ADDRESS_SERVICE_H_

tooling/pipeline/includes/services/address/nominatim_address_service.h

@@ -0,0 +1,37 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_NOMINATIM_ADDRESS_SERVICE_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_NOMINATIM_ADDRESS_SERVICE_H_
+
+/**
+ * @file services/address/nominatim_address_service.h
+ * @brief Reverse geocoding backed by the public Nominatim API.
+ */
+
+#include <memory>
+#include <optional>
+
+#include "services/address/address_service.h"
+#include "services/logging/logger.h"
+#include "web_client/web_client.h"
+
+/**
+ * @brief Reverse-geocodes coordinates into street addresses via the public
+ * Nominatim API (https://nominatim.openstreetmap.org).
+ *
+ * Required for API usage:
+ * - single identifying User-Agent and at most one request per
+ * second (https://operations.osmfoundation.org/policies/nominatim/).
+ */
+class NominatimAddressService final : public IAddressService {
+  public:
+   explicit NominatimAddressService(std::unique_ptr<WebClient> client,
+                                    std::shared_ptr<ILogger> logger);
+
+   std::optional<AddressLookupResult> ReverseGeocode(
+       double longitude, double latitude) override;
+
+  private:
+   std::unique_ptr<WebClient> client_;
+   std::shared_ptr<ILogger> logger_;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ADDRESS_NOMINATIM_ADDRESS_SERVICE_H_