activejob-temporal 0.1.0

data/lib/activejob/temporal/logger.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module ActiveJob
+  module Temporal
+    # Structured logging for activejob-temporal gem.
+    #
+    # This module provides structured JSON logging with event names and typed attributes.
+    # It integrates with SemanticLogger if available, otherwise falls back to standard
+    # Ruby Logger with JSON formatting.
+    #
+    # All log entries include:
+    # - event: Event name (String or Symbol)
+    # - timestamp: ISO8601 UTC timestamp
+    # - Custom attributes (Hash)
+    #
+    # @note SemanticLogger Detection
+    #   If the configured logger is a SemanticLogger instance, log entries are passed directly
+    #   as hashes. Otherwise, the module JSON-stringifies the payload before passing it to the
+    #   configured Ruby Logger instance.
+    #
+    # @example Basic logging
+    #   Logger.info("job.enqueued", job_id: "123", queue: "default")
+    #   # => { "event": "job.enqueued", "timestamp": "2025-10-29T12:00:00Z", "job_id": "123", "queue": "default" }
+    #
+    # @example Error logging
+    #   Logger.error("job.failed", job_id: "123", error: "NetworkError")
+    #
+    # @example With SemanticLogger
+    #   # If the configured logger is SemanticLogger, structured hash is passed directly
+    #   Logger.info("workflow.started", workflow_id: "wf-123")
+    #   # SemanticLogger formats as structured JSON
+    #
+    # @example Without SemanticLogger
+    #   # Falls back to JSON.generate before calling logger.info
+    #   Logger.info("workflow.started", workflow_id: "wf-123")
+    #   # => '{"event":"workflow.started","timestamp":"2025-10-31T12:00:00Z","workflow_id":"wf-123"}'
+    module Logger
+      extend self
+
+      CONTROL_CHARACTER_PATTERN = /[[:cntrl:]]/
+
+      # Logs an event at INFO level.
+      #
+      # @param event_name [String, Symbol] Name of the event (e.g., "job.enqueued")
+      # @param attributes [Hash] Additional structured data to include in log entry
+      # @return [void]
+      # @raise [ArgumentError] if event_name is not a String or Symbol
+      # @raise [ArgumentError] if attributes is not a Hash
+      # @raise [NoMethodError] if logger is not configured
+      # @example
+      #   Logger.log_event("workflow.started", workflow_id: "wf-123", job_class: "MyJob")
+      #
+      # @example With complex attributes
+      #   Logger.log_event("job.completed", {
+      #     job_id: "abc-123",
+      #     duration_ms: 1500,
+      #     result: { success: true, records_processed: 100 }
+      #   })
+      def log_event(event_name, attributes = {})
+        log(:info, event_name, attributes)
+      end
+
+      # Logs an event at INFO level.
+      #
+      # @param event_name [String, Symbol] Name of the event
+      # @param attributes [Hash] Additional structured data
+      # @return [void]
+      # @raise [ArgumentError] if event_name is not a String or Symbol
+      # @raise [ArgumentError] if attributes is not a Hash
+      # @raise [NoMethodError] if logger is not configured
+      # @example
+      #   Logger.info("job.completed", job_id: "123", duration_ms: 1500)
+      def info(event_name, attributes = {})
+        log(:info, event_name, attributes)
+      end
+
+      # Logs an event at WARN level.
+      #
+      # @param event_name [String, Symbol] Name of the event
+      # @param attributes [Hash] Additional structured data
+      # @return [void]
+      # @raise [ArgumentError] if event_name is not a String or Symbol
+      # @raise [ArgumentError] if attributes is not a Hash
+      # @raise [NoMethodError] if logger is not configured
+      # @example
+      #   Logger.warn("job.retry", job_id: "123", attempt: 2, error: "Timeout")
+      def warn(event_name, attributes = {})
+        log(:warn, event_name, attributes)
+      end
+
+      # Logs an event at ERROR level.
+      #
+      # @param event_name [String, Symbol] Name of the event
+      # @param attributes [Hash] Additional structured data
+      # @return [void]
+      # @raise [ArgumentError] if event_name is not a String or Symbol
+      # @raise [ArgumentError] if attributes is not a Hash
+      # @raise [NoMethodError] if logger is not configured
+      # @example
+      #   Logger.error("job.failed", job_id: "123", error_class: "RuntimeError", message: "Boom")
+      def error(event_name, attributes = {})
+        log(:error, event_name, attributes)
+      end
+
+      def log_to(configured_logger, level, event_name, attributes = {})
+        log(level, event_name, attributes, configured_logger: configured_logger)
+      end
+
+      private
+
+      # Internal logging method that handles all log levels.
+      # @api private
+      def log(level, event_name, attributes, configured_logger: ActiveJob::Temporal.config.logger)
+        validate_event!(event_name)
+        attributes = normalize_attributes(attributes)
+
+        payload = build_payload(sanitize_log_value(event_name), sanitize_log_value(attributes))
+        return unless configured_logger.respond_to?(level)
+
+        if semantic_logger?(configured_logger)
+          configured_logger.public_send(level, payload)
+        else
+          configured_logger.public_send(level, JSON.generate(payload))
+        end
+      end
+
+      def sanitize_log_value(value)
+        case value
+        when String
+          escape_control_characters(value)
+        when Symbol
+          sanitize_symbol(value)
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), result|
+            result[sanitize_log_key(key)] = sanitize_log_value(nested_value)
+          end
+        when Array
+          value.map { |element| sanitize_log_value(element) }
+        else
+          value
+        end
+      end
+
+      def sanitize_log_key(key)
+        case key
+        when String
+          escape_control_characters(key)
+        when Symbol
+          sanitize_symbol(key)
+        else
+          key
+        end
+      end
+
+      def sanitize_symbol(value)
+        sanitized = escape_control_characters(value.to_s)
+        sanitized == value.to_s ? value : sanitized
+      end
+
+      def escape_control_characters(value)
+        return value unless value.match?(CONTROL_CHARACTER_PATTERN)
+
+        value.gsub(CONTROL_CHARACTER_PATTERN) { |character| format("\\u%04X", character.ord) }
+      end
+
+      # Builds structured log payload with event and timestamp.
+      # @api private
+      def build_payload(event_name, attributes)
+        { event: event_name, timestamp: current_timestamp }.merge(attributes)
+      end
+
+      # Returns current UTC timestamp in ISO8601 format.
+      # @api private
+      def current_timestamp
+        Time.now.utc.iso8601
+      end
+
+      # Normalizes attributes to a hash.
+      # @api private
+      def normalize_attributes(attributes)
+        case attributes
+        when nil then {}
+        when Hash then attributes.dup
+        else
+          raise ArgumentError, "attributes must be a Hash"
+        end
+      end
+
+      # Validates event_name is a String or Symbol.
+      # @api private
+      def validate_event!(event_name)
+        return if event_name.is_a?(String) || event_name.is_a?(Symbol)
+
+        raise ArgumentError, "event_name must be a String or Symbol"
+      end
+
+      # Checks if the configured logger handles structured payloads itself.
+      # @api private
+      def semantic_logger?(configured_logger)
+        return false unless defined?(SemanticLogger)
+        return true if semantic_logger_instance?(configured_logger)
+
+        configured_logger.class.name.to_s.start_with?("SemanticLogger::")
+      end
+
+      def semantic_logger_instance?(configured_logger)
+        defined?(SemanticLogger::Logger) && configured_logger.is_a?(SemanticLogger::Logger)
+      end
+    end
+  end
+end

data/lib/activejob/temporal/metrics_server.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "io/wait"
+require "socket"
+
+require_relative "connection_worker_pool"
+require_relative "bind_policy"
+require_relative "http_line_reader"
+
+module ActiveJob
+  module Temporal
+    class MetricsServer
+      include HttpLineReader
+
+      DEFAULT_BIND_ADDRESS = "127.0.0.1"
+      READ_TIMEOUT_SECONDS = 1
+      CONTENT_TYPE = "text/plain; version=0.0.4"
+      CONNECTION_WORKERS = 4
+      CONNECTION_QUEUE_SIZE = 16
+
+      attr_reader :port, :bind_address
+
+      def initialize(port:, provider:, bind_address: DEFAULT_BIND_ADDRESS, allow_public_bind: false)
+        @requested_port = Integer(port)
+        @bind_address = bind_address
+        @allow_public_bind = allow_public_bind
+        @provider = provider
+        @running = false
+        @mutex = Mutex.new
+      end
+
+      def start
+        @mutex.synchronize do
+          return self if @running
+
+          BindPolicy.validate!(
+            endpoint: "metrics",
+            bind_address: bind_address,
+            allow_public_bind: @allow_public_bind
+          )
+          @server = TCPServer.new(bind_address, @requested_port)
+          @port = @server.addr[1]
+          @connection_pool = ConnectionWorkerPool.new(
+            size: CONNECTION_WORKERS,
+            queue_size: CONNECTION_QUEUE_SIZE,
+            name: "activejob-temporal-metrics"
+          ) { |client| serve_client(client) }.start
+          @running = true
+          @thread = Thread.new { run }
+        end
+
+        self
+      end
+
+      def stop
+        server = nil
+        thread = nil
+        connection_pool = nil
+
+        @mutex.synchronize do
+          server = @server
+          thread = @thread
+          connection_pool = @connection_pool
+          @server = nil
+          @thread = nil
+          @connection_pool = nil
+          @running = false
+        end
+
+        server&.close
+        connection_pool&.stop(timeout: 2)
+        thread&.join(2)
+      end
+
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      private
+
+      def run
+        loop do
+          server, connection_pool = @mutex.synchronize { [@server, @connection_pool] }
+          break unless server && connection_pool
+
+          connection_pool.enqueue(server.accept)
+        rescue IOError, Errno::EBADF
+          break
+        end
+      ensure
+        @mutex.synchronize { @running = false if @server }
+      end
+
+      def serve_client(client)
+        handle_client(client)
+      rescue IOError, SystemCallError
+        nil
+      ensure
+        client&.close
+      end
+
+      def handle_client(client)
+        request_line = read_line(client)
+        return unless request_line
+
+        method, path = request_line.split.first(2)
+        drain_headers(client)
+
+        unless method && path
+          write_text(client, 400, "bad_request\n")
+          return
+        end
+
+        case [method, path]
+        in ["GET" | "HEAD", "/metrics"]
+          write_text(client, 200, @provider.render, body: method == "GET")
+        in [_, "/metrics"]
+          write_text(client, 405, "method_not_allowed\n")
+        else
+          write_text(client, 404, "not_found\n")
+        end
+      end
+
+      def drain_headers(client)
+        loop do
+          line = read_line(client)
+          break if line.nil? || line == "\r\n" || line == "\n"
+        end
+      end
+
+      def write_text(client, status, payload, body: true)
+        response = "HTTP/1.1 #{status} #{reason_phrase(status)}\r\n"
+        response << "Content-Type: #{CONTENT_TYPE}\r\n"
+        response << "Content-Length: #{body ? payload.bytesize : 0}\r\n"
+        response << "Connection: close\r\n\r\n"
+        response << payload if body
+        client.write(response)
+      end
+
+      def reason_phrase(status)
+        {
+          200 => "OK",
+          400 => "Bad Request",
+          404 => "Not Found",
+          405 => "Method Not Allowed"
+        }.fetch(status)
+      end
+    end
+  end
+end

data/lib/activejob/temporal/middleware/chain.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module Middleware
+      # Ordered middleware pipeline for ActiveJob execution inside Temporal activities.
+      class Chain
+        include Enumerable
+
+        TERMINAL_CALL_CHAIN = ->(_job, terminal) { terminal.call }.freeze
+
+        def initialize(entries = [])
+          @entries = []
+          @entry_indexes_by_key = {}
+          @compiled_call_chain = TERMINAL_CALL_CHAIN
+          entries.each { |entry| add(entry) }
+        end
+
+        def add(middleware, *args, **kwargs, &block)
+          key = entry_key(middleware, args, kwargs, block)
+          callable = build_callable(middleware, args, kwargs, block)
+          upsert_entry(key, callable)
+          @compiled_call_chain = compile_call_chain
+
+          callable
+        end
+
+        def call(job, &terminal)
+          raise ArgumentError, "middleware chain requires a block" unless terminal
+
+          @compiled_call_chain.call(job, terminal)
+        end
+
+        def each(&block)
+          return enum_for(:each) unless block
+
+          @entries.each(&block)
+        end
+
+        private
+
+        def upsert_entry(key, callable)
+          if @entry_indexes_by_key.key?(key)
+            @entries[@entry_indexes_by_key.fetch(key)] = callable
+          else
+            @entry_indexes_by_key[key] = @entries.length
+            @entries << callable
+          end
+        end
+
+        def entry_key(middleware, args, kwargs, block)
+          [
+            middleware_key(middleware),
+            args.map { |argument| argument_key(argument) },
+            kwargs.sort_by { |key, _value| key.to_s }.map { |key, value| [key, argument_key(value)] },
+            block_key(block)
+          ]
+        end
+
+        def middleware_key(middleware)
+          return [:class, middleware.name] if middleware.is_a?(Class) && middleware.name
+          return [:callable_source, middleware.source_location] if middleware.respond_to?(:source_location)
+
+          [:object, middleware.object_id]
+        end
+
+        def argument_key(argument)
+          case argument
+          when NilClass, TrueClass, FalseClass, Numeric, Symbol
+            argument
+          when String
+            argument.dup.freeze
+          else
+            [:object, argument.object_id]
+          end
+        end
+
+        def block_key(block)
+          block&.source_location || block&.object_id
+        end
+
+        def compile_call_chain
+          @entries.reverse_each.reduce(TERMINAL_CALL_CHAIN) do |next_middleware, middleware|
+            lambda do |job, terminal|
+              middleware.call(job) { next_middleware.call(job, terminal) }
+            end
+          end
+        end
+
+        def build_callable(middleware, args, kwargs, block)
+          callable = if middleware.is_a?(Class)
+                       middleware.new(*args, **kwargs, &block)
+                     elsif args.empty? && kwargs.empty? && block.nil?
+                       middleware
+                     else
+                       raise ArgumentError, "middleware arguments require a middleware class"
+                     end
+
+          return callable if callable.respond_to?(:call)
+
+          raise ArgumentError, "middleware must respond to #call"
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/middleware.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "middleware/chain"
+
+module ActiveJob
+  module Temporal
+    # Runtime extension points for activity execution.
+    module Middleware
+    end
+  end
+end

data/lib/activejob/temporal/observability/datadog.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "../observability"
+
+module ActiveJob
+  module Temporal
+    module Observability
+      # rubocop:disable Metrics/ClassLength
+      class Datadog < Adapter
+        attr_accessor :service, :statsd_host, :statsd_port
+        attr_writer :statsd
+
+        def initialize(service: "activejob-temporal", statsd: nil, statsd_host: "127.0.0.1", statsd_port: 8125)
+          super(:datadog)
+          @service = service
+          @statsd = statsd
+          @statsd_host = statsd_host
+          @statsd_port = statsd_port
+        end
+
+        def trace_context_for_enqueue(_payload)
+          trace = ::Datadog::Tracing.active_trace if defined?(::Datadog::Tracing)
+          return {} unless trace.respond_to?(:to_digest)
+
+          carrier = {}
+          ::Datadog::Tracing::Contrib::HTTP.inject(trace.to_digest, carrier)
+          carrier
+        end
+
+        def record(event_name, payload)
+          case event_name
+          when :enqueue then record_enqueue(payload)
+          when :payload_serialize then record_payload_size(payload)
+          when :retry then record_retry(payload)
+          when :worker_start then record_worker_started(payload)
+          when :worker_stop then record_worker_stopped(payload)
+          when :active_tasks then record_active_tasks(payload)
+          end
+        end
+
+        def instrument(event_name, payload)
+          return yield unless event_name == :perform
+
+          started_at = monotonic_time
+          trace(event_name, payload) do
+            result = yield
+            statsd.increment("activejob_temporal.jobs.completed", tags: tags(payload))
+            result
+          rescue StandardError => e
+            statsd.increment("activejob_temporal.jobs.failed", tags: tags(payload, error: e.class.name))
+            raise
+          ensure
+            statsd.histogram(
+              "activejob_temporal.job_duration.seconds",
+              monotonic_time - started_at,
+              tags: tags(payload)
+            )
+          end
+        end
+
+        def validate_dependencies!
+          require_dependency("datadog", "datadog", "Datadog")
+          require_dependency("datadog", "datadog/statsd", "Datadog")
+          require_dependency("datadog", "datadog/tracing/contrib/http", "Datadog")
+          self
+        end
+
+        private
+
+        def record_enqueue(payload)
+          trace(:enqueue, payload) do
+            statsd.increment("activejob_temporal.jobs.enqueued", tags: tags(payload))
+          end
+        end
+
+        def record_payload_size(payload)
+          statsd.histogram("activejob_temporal.payload_size.bytes", payload[:bytes], tags: tags(payload))
+        end
+
+        def record_retry(payload)
+          statsd.increment("activejob_temporal.retries", tags: tags(payload, error: payload[:error]))
+        end
+
+        def record_worker_started(payload)
+          statsd.gauge("activejob_temporal.active_workers", 1, tags: worker_tags(payload))
+        end
+
+        def record_worker_stopped(payload)
+          statsd.gauge("activejob_temporal.active_workers", 0, tags: worker_tags(payload))
+          statsd.gauge("activejob_temporal.active_tasks", 0, tags: worker_tags(payload))
+        end
+
+        def record_active_tasks(payload)
+          statsd.gauge("activejob_temporal.active_tasks", payload[:count].to_i, tags: worker_tags(payload))
+        end
+
+        def trace(event_name, payload)
+          digest = extracted_digest(payload)
+          options = {
+            service: service,
+            resource: payload[:job_class]
+          }.compact
+          options[:continue_from] = digest if digest
+
+          ::Datadog::Tracing.trace("activejob_temporal.#{event_name}", **options) do |span|
+            set_span_tags(span, payload)
+            yield
+          end
+        end
+
+        def extracted_digest(payload)
+          carrier = Observability.trace_context_from_payload(payload).fetch("datadog", nil)
+          return if carrier.nil? || carrier.empty?
+
+          ::Datadog::Tracing::Contrib::HTTP.extract(carrier)
+        end
+
+        def set_span_tags(span, payload)
+          span.set_tag("activejob_temporal.job_class", payload[:job_class])
+          span.set_tag("activejob_temporal.job_id", payload[:job_id])
+          span.set_tag("activejob_temporal.queue", payload[:queue])
+          span.set_tag("activejob_temporal.workflow_id", payload[:workflow_id])
+          span.set_tag("activejob_temporal.run_id", payload[:run_id])
+          span.set_tag("activejob_temporal.namespace", payload[:namespace])
+          span.set_tag("activejob_temporal.task_queue", payload[:task_queue])
+          span.set_tag("activejob_temporal.attempt", payload[:attempt])
+        end
+
+        def statsd
+          @statsd ||= ::Datadog::Statsd.new(statsd_host, statsd_port)
+        end
+
+        def tags(payload, error: nil)
+          [
+            tag("job_class", payload[:job_class]),
+            tag("queue", payload[:queue]),
+            tag("namespace", payload[:namespace]),
+            tag("task_queue", payload[:task_queue]),
+            tag("error", error)
+          ].compact
+        end
+
+        def worker_tags(payload)
+          [
+            tag("namespace", payload[:namespace]),
+            tag("task_queue", payload[:task_queue]),
+            tag("worker_id", payload[:worker_id])
+          ].compact
+        end
+
+        def tag(name, value)
+          "#{name}:#{value}" unless value.nil?
+        end
+
+        def monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+  end
+end
+
+ActiveJob::Temporal::Observability.register_adapter(
+  :datadog,
+  ActiveJob::Temporal::Observability::Datadog
+)