Implement BoundedChannel and multithreaded logging infra

tooling/pipeline/includes/services/logging/channel_logger.h

@@ -0,0 +1,54 @@
+/**
+ * @file services/logging/channel_logger.h
+ * @brief Channel-backed producer for asynchronous pipeline logging.
+ *
+ * Intent: Decouple logging from synchronous I/O by forwarding entries to a
+ * bounded channel. LogConsumer drains the channel on a dedicated thread.
+ */
+
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_CHANNEL_LOGGER_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_CHANNEL_LOGGER_H_
+
+#include <string_view>
+
+#include "concurrency/bounded_channel.h"
+#include "services/logging/log_entry.h"
+#include "services/logging/logger.h"
+
+/**
+ * @class ChannelLogger
+ * @brief ILogger implementation that sends entries to a BoundedChannel.
+ *
+ * Non-copyable, non-movable. Holds a non-owning reference to the channel.
+ */
+class ChannelLogger final : public ILogger {
+ public:
+   /**
+    * @brief Construct a channel-backed logger.
+    *
+    * @param channel Reference to bounded channel for log entry transfer.
+    *                Channel must outlive this logger instance.
+    */
+   explicit ChannelLogger(BoundedChannel<LogEntry>& channel);
+
+   ChannelLogger(const ChannelLogger&) = delete;
+   ChannelLogger& operator=(const ChannelLogger&) = delete;
+   ChannelLogger(ChannelLogger&&) = delete;
+   ChannelLogger& operator=(ChannelLogger&&) = delete;
+
+   ~ChannelLogger() override = default;
+
+   /**
+    * @brief Queue a log entry for asynchronous processing.
+    *
+    * Blocks if the channel is full (backpressure). Returns immediately
+    * if the channel is closed.
+    */
+   void Log(LogLevel level, PipelinePhase phase,
+            std::string_view message) override;
+
+ private:
+   BoundedChannel<LogEntry>& channel_;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_CHANNEL_LOGGER_H_

tooling/pipeline/includes/services/logging/log_consumer.h

@@ -0,0 +1,59 @@
+/**
+ * @file services/logging/log_consumer.h
+ * @brief Dedicated log consumer/drain for asynchronous pipeline logging.
+ *
+ * Intent: Dequeue LogEntry values from a BoundedChannel on a dedicated thread
+ * and forward them to spdlog for I/O and formatting. Decouples application
+ * logic from logging latency.
+ */
+
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_CONSUMER_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_CONSUMER_H_
+
+#include <spdlog/spdlog.h>
+
+#include <string>
+
+#include "concurrency/bounded_channel.h"
+#include "services/logging/log_entry.h"
+
+/**
+ * @class LogConsumer
+ * @brief Consumes log entries from channel and forwards to spdlog.
+ *
+ * Non-copyable, non-movable. Designed to run on its own dedicated std::thread.
+ * Drains the channel until closure, then exits cleanly.
+ */
+class LogConsumer {
+ public:
+   /**
+    * @brief Construct a log consumer.
+    *
+    * @param channel Reference to bounded channel for log entry retrieval.
+    *                Channel must outlive this consumer instance.
+    */
+   explicit LogConsumer(BoundedChannel<LogEntry>& channel);
+
+   LogConsumer(const LogConsumer&) = delete;
+   LogConsumer& operator=(const LogConsumer&) = delete;
+   LogConsumer(LogConsumer&&) = delete;
+   LogConsumer& operator=(LogConsumer&&) = delete;
+
+   /**
+    * @brief Main loop: drain channel and forward entries to spdlog.
+    *
+    * Intended to be called once on a dedicated thread. Returns when:
+    * - Channel is closed AND all queued entries are drained.
+    *
+    * Thread-safe for use from multiple ChannelLogger instances on other threads.
+    */
+   void Run();
+
+ private:
+   BoundedChannel<LogEntry>& channel_;
+
+   static spdlog::level::level_enum ToSpdlogLevel(LogLevel level);
+   static std::string ToString(PipelinePhase phase);
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_CONSUMER_H_

tooling/pipeline/includes/services/logging/log_entry.h

@@ -0,0 +1,65 @@
+/**
+ * @file services/logging/log_entry.h
+ * @brief POD log entry structure for asynchronous pipeline logging.
+ *
+ * Intent: Lightweight, move-safe data transfer between logging producer
+ * (ChannelLogger) and consumer (LogConsumer) via BoundedChannel<LogEntry>.
+ */
+
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_
+
+#include <chrono>
+#include <string>
+
+/**
+ * @enum LogLevel
+ * @brief Severity levels for log entries.
+ */
+enum class LogLevel {
+   Debug,  ///< Development/debugging information.
+   Info,   ///< General informational messages.
+   Warn,   ///< Warning conditions.
+   Error,  ///< Error conditions.
+};
+
+/**
+ * @enum PipelinePhase
+ * @brief Execution phases for contextual logging.
+ *
+ * Used to tag log entries by their processing stage, enabling phase-specific
+ * analysis and filtering of the execution timeline.
+ */
+enum class PipelinePhase {
+   Startup,                      ///< Initialization and validation.
+   UserGeneration,               ///< User profile generation.
+   BreweryAndBeerGeneration,     ///< Brewery and beer data generation.
+   CheckinGeneration,            ///< Checkin (visit) record generation.
+   RatingGeneration,             ///< Rating and review generation.
+   FollowGeneration,             ///< Follow relationship generation.
+   Teardown,                     ///< Finalization and cleanup.
+};
+
+/**
+ * @struct LogEntry
+ * @brief Single log event for asynchronous processing.
+ *
+ * All fields are value types, allowing safe move semantics across
+ * BoundedChannel without shared ownership or synchronization overhead.
+ */
+struct LogEntry {
+   /// @brief Timestamp when entry was created.
+   std::chrono::system_clock::time_point timestamp =
+       std::chrono::system_clock::now();
+
+   /// @brief Severity level of this entry.
+   LogLevel level;
+
+   /// @brief Pipeline phase when entry was logged.
+   PipelinePhase phase;
+
+   /// @brief Log message text.
+   std::string message;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_

tooling/pipeline/includes/services/logging/logger.h

@@ -0,0 +1,45 @@
+/**
+ * @file services/logging/logger.h
+ * @brief Abstract logging interface for pipeline components.
+ *
+ * Intent: Decouple logging from channel/worker implementation details.
+ * All pipeline components depend on ILogger, enabling swappable backends.
+ */
+
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_
+
+#include <optional>
+#include <string>
+#include <string_view>
+
+#include "services/logging/log_entry.h"
+
+/**
+ * @class ILogger
+ * @brief Minimal interface for submitting log entries.
+ *
+ * Non-copyable and non-movable. Implementations are typically short-lived,
+ * created and owned by the composition root.
+ */
+class ILogger {
+ public:
+   ILogger() = default;
+   ILogger(const ILogger&) = delete;
+   ILogger& operator=(const ILogger&) = delete;
+   ILogger(ILogger&&) = delete;
+   ILogger& operator=(ILogger&&) = delete;
+   virtual ~ILogger() = default;
+
+   /**
+    * @brief Submit a log entry to the logging subsystem.
+    *
+    * @param level Log level (Debug, Info, Warn, Error).
+    * @param phase Pipeline execution phase (Startup, Generation, Teardown, etc.).
+    * @param message Log message text.
+    */
+   virtual void Log(LogLevel level, PipelinePhase phase,
+                    std::string_view message) = 0;
+};
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_