lepus-saga 0.3.0

data/lib/lepus/saga/stores.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Saga
+    # Persistence adapters. Each one subclasses Stores::Base and lives at
+    # "lepus/saga/stores/<name>", which is how `config.store = :<name>` finds
+    # it, whether it ships with this gem (Memory) or in its own gem
+    # (lepus-saga-active_record ships Stores::ActiveRecord).
+    module Stores
+      autoload :Base, "lepus/saga/stores/base"
+      autoload :Memory, "lepus/saga/stores/memory"
+
+      class << self
+        def build(value)
+          case value
+          when nil then nil
+          when Symbol, String then lookup(value).new
+          when Class then value.new
+          else value
+          end
+        end
+
+        def lookup(name)
+          path = Lepus::Primitive::String.new(name.to_s).underscore
+          const_name = camelize(path)
+          require "lepus/saga/stores/#{path}" unless const_defined?(const_name, false)
+          const_get(const_name, false)
+        rescue LoadError, NameError => error
+          raise ConfigurationError, "Unknown saga store #{name.inspect} (#{error.message})"
+        end
+
+        private
+
+        def camelize(path)
+          path.split("/").map { |part| part.split("_").map(&:capitalize).join }.join("::")
+        end
+      end
+    end
+  end
+end

data/lib/lepus/saga/testing.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "lepus/testing"
+
+module Lepus
+  module Saga
+    # Test-only helper to run saga step messages inline. Requires
+    # Lepus::Testing fake publishing to be enabled.
+    module Testing
+      class DrainStallError < StandardError; end
+
+      # Pops messages from the fake saga exchange and delivers them to the
+      # executor consumer until the exchange is empty. Messages rejected for
+      # retry are redelivered immediately (the TTL delay is irrelevant under
+      # fake publishing), so retry loops run to their conclusion inline.
+      def self.drain(consumer:, max_iterations: 50)
+        exchange = Lepus::Testing.exchange(Lepus::Saga.exchange_name)
+        iterations = 0
+
+        until exchange.empty?
+          if (iterations += 1) > max_iterations
+            raise DrainStallError, "saga drain did not settle after #{max_iterations} iterations"
+          end
+
+          batch = exchange.messages.dup
+          exchange.clear_messages
+          batch.each do |message|
+            result = Lepus::Testing.consumer_perform(consumer, {payload: message[:payload]})
+            exchange.add_message(message) if result == :reject
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lepus/saga/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Saga
+    VERSION = "0.3.0"
+  end
+end

data/lib/lepus/saga/web/api.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Lepus
+  module Saga
+    module Web
+      # The JSON API under /api. Reads need the store's query methods; the
+      # two actions are POSTs guarded against cross-site requests: they need a
+      # JSON body, the X-Lepus-Saga header and a same-origin Origin (or
+      # Referer when the browser sends no Origin).
+      class Api
+        class Error < StandardError
+          attr_reader :status
+
+          def initialize(status, message)
+            @status = status
+            super(message)
+          end
+        end
+
+        ROUTES = [
+          ["GET", %r{\A/me\z}, :me],
+          ["GET", %r{\A/sagas\z}, :sagas],
+          ["GET", %r{\A/executions\z}, :executions],
+          ["GET", %r{\A/executions/(?<id>[^/]+)\z}, :execution],
+          ["GET", %r{\A/moving\z}, :moving],
+          ["GET", %r{\A/series\z}, :series],
+          ["GET", %r{\A/insights/failures\z}, :failures],
+          ["GET", %r{\A/insights/latency\z}, :latency],
+          ["GET", %r{\A/stalled\z}, :stalled],
+          ["POST", %r{\A/executions/(?<id>[^/]+)/retry\z}, :retry_execution],
+          ["POST", %r{\A/executions/(?<id>[^/]+)/compensate\z}, :compensate_execution]
+        ].freeze
+        ACTIONS = {retry_execution: :retry, compensate_execution: :compensate}.freeze
+        CSRF_HEADER = "HTTP_X_LEPUS_SAGA"
+        DEFAULT_WINDOW = 24 * 3600
+        SERIES_BUCKETS = [60, 300, 600, 900, 1800, 3600, 7200, 10_800, 21_600, 43_200, 86_400].freeze
+        SERIES_TARGET = 90
+        IN_PROGRESS = ExecutionBehaviour::IN_PROGRESS_STATUSES
+        STOPPED_STATUSES = %w[failed compensation_failed].freeze
+        RELATED_LIMIT = 20
+
+        def initialize(config)
+          @config = config
+        end
+
+        def call(env)
+          request = Rack::Request.new(env)
+          method, _pattern, action, match = route(request)
+          raise Error.new(404, "Not found") unless action
+          raise Error.new(405, "Method not allowed") unless request.request_method == method
+
+          authorize_action!(request, ACTIONS[action]) if ACTIONS.key?(action)
+          json(200, send(action, request, **match.named_captures.transform_keys(&:to_sym)))
+        rescue Error => error
+          json(error.status, error: error.message)
+        rescue NotRetryableError, UnknownSagaError => error
+          json(409, error: error.message)
+        rescue NotImplementedError
+          json(501, error: "The saga store does not implement the query methods")
+        rescue ArgumentError => error
+          json(400, error: error.message)
+        end
+
+        private
+
+        attr_reader :config
+
+        def store = config.store
+
+        def route(request)
+          path = request.path_info.empty? ? "/" : request.path_info
+          candidates = ROUTES.filter_map { |method, pattern, action| [method, pattern, action, pattern.match(path)] if pattern.match?(path) }
+          candidates.find { |method, *| method == request.request_method } || candidates.first
+        end
+
+        def me(request)
+          {
+            title: config.title,
+            version: VERSION,
+            read_only: config.read_only ? true : false,
+            queries: store.queries?,
+            poll_interval: config.default_poll_interval,
+            poll_intervals: Configuration::POLL_INTERVALS,
+            stalled_after: config.stalled_after,
+            actions: ACTIONS.values.to_h { |action| [action, config.allowed?(request.env, action)] }
+          }
+        end
+
+        def sagas(request)
+          from, to = window(request)
+          live = store.count_executions(group_by: %i[saga_name status current_step], status: IN_PROGRESS)
+          stalled = store.count_executions(group_by: %i[saga_name status current_step], status: IN_PROGRESS, progress_to: stalled_before)
+          stopped = store.count_executions(group_by: %i[saga_name status current_step], status: STOPPED_STATUSES, from: from, to: to)
+          totals = store.count_executions(group_by: %i[saga_name status], from: from, to: to)
+          failures = store.failure_summary(from: from, to: to, limit: 500)
+          definitions = Lepus::Saga.definitions
+          names = (definitions.keys + store.saga_names + totals.keys.map(&:first)).uniq.sort
+
+          sagas = names.map do |name|
+            Serializer.definition(name, definitions[name]).merge(
+              stations: stations(name, live.merge(stopped), stalled, failures),
+              totals: totals.filter_map { |(saga, status), count| [status, count] if saga == name }.to_h
+            )
+          end
+          {from: Serializer.time(from), to: Serializer.time(to), stalled_after: config.stalled_after, sagas: sagas}
+        end
+
+        def stations(name, counts, stalled, failures)
+          stations = Hash.new { |hash, step| hash[step] = {attempt_failures: 0, stalled: {}} }
+          counts.each do |(saga, status, step), count|
+            stations[step][status] = count if saga == name
+          end
+          stalled.each do |(saga, status, step), count|
+            stations[step][:stalled][status] = count if saga == name
+          end
+          failures.each do |failure|
+            stations[failure[:step_name]][:attempt_failures] += failure[:count] if failure[:saga_name] == name
+          end
+          stations
+        end
+
+        def executions(request)
+          limit = integer(request, "limit", default: 50, range: 1..200)
+          rows = store.list_executions(**filters(request), before_id: param(request, "before"), limit: limit + 1)
+          {
+            executions: rows.first(limit).map { |execution| Serializer.execution(execution) },
+            next_before: (rows[limit - 1].id if rows.size > limit)
+          }
+        end
+
+        # Executions in progress and not stalled at the busiest steps, so a
+        # live view can draw every busy step from one request.
+        def moving(request)
+          per_station = integer(request, "per_station", default: 9, range: 1..50)
+          limit = integer(request, "stations", default: 40, range: 1..100)
+          since = stalled_before
+          counts = store.count_executions(group_by: %i[saga_name current_step], status: IN_PROGRESS, progress_from: since, saga_name: list(request, "saga"))
+            .reject { |(_saga, step), _count| step.nil? }
+          busiest = counts.sort_by { |(saga, step), count| [-count, saga, step] }.first(limit)
+          stations = busiest.map do |(saga, step), count|
+            rows = store.list_executions(saga_name: saga, current_step: step, status: IN_PROGRESS, progress_from: since, limit: per_station)
+            {saga_name: saga, step_name: step, count: count, executions: rows.map { |execution| Serializer.execution(execution) }}
+          end
+          {stalled_after: config.stalled_after, stations: stations, omitted: counts.size - busiest.size}
+        end
+
+        def execution(_request, id:)
+          execution = find!(id)
+          definition = Lepus::Saga.definitions[execution.saga_name]
+          related = store.executions_for_resource(execution.resource_type, execution.resource_id)
+            .reject { |other| other.id == execution.id }.first(RELATED_LIMIT)
+          {
+            execution: Serializer.execution(execution, context: true),
+            definition: Serializer.definition(execution.saga_name, definition),
+            attempts: store.step_attempts(execution).map { |attempt| Serializer.attempt(attempt) },
+            related: related.map { |other| Serializer.execution(other) }
+          }
+        end
+
+        def series(request)
+          from, to = window(request)
+          bucket = integer(request, "bucket", default: series_bucket(to - from), range: 1..)
+          result = store.execution_series(from: from, to: to, bucket: bucket, saga_name: list(request, "saga"), max_rows: config.max_rows)
+          {
+            from: Serializer.time(from), to: Serializer.time(to), bucket: bucket, truncated: result[:truncated],
+            rows: result[:rows].map { |start, counts| {t: Serializer.time(start), **counts} }
+          }
+        end
+
+        def failures(request)
+          from, to = window(request)
+          limit = integer(request, "limit", default: 20, range: 1..200)
+          rows = store.failure_summary(from: from, to: to, saga_name: list(request, "saga"), limit: limit)
+          {from: Serializer.time(from), to: Serializer.time(to), failures: rows.map { |row| row.merge(last_seen_at: Serializer.time(row[:last_seen_at])) }}
+        end
+
+        def latency(request)
+          from, to = window(request)
+          result = store.step_latency(from: from, to: to, saga_name: list(request, "saga"), max_rows: config.max_rows)
+          rows = result[:rows].map { |row| row.merge(row.slice(:p50, :p95, :p99, :max).transform_values { |ms| ms&.round(1) }) }
+          {from: Serializer.time(from), to: Serializer.time(to), rows: rows, truncated: result[:truncated]}
+        end
+
+        def stalled(request)
+          minutes = integer(request, "minutes", default: nil, range: 1..)
+          seconds = minutes ? minutes * 60 : config.stalled_after
+          limit = integer(request, "limit", default: 50, range: 1..200)
+          rows = store.stalled_executions(before: Time.now.utc - seconds).first(limit)
+          {stalled_after: seconds, executions: rows.map { |execution| Serializer.execution(execution) }}
+        end
+
+        def retry_execution(_request, id:)
+          {execution: Serializer.execution(Lepus::Saga.retry(find_actionable!(id)))}
+        end
+
+        def compensate_execution(request, id:)
+          reason = presence(body(request)["reason"].to_s.strip) || "manually compensated"
+          {execution: Serializer.execution(Lepus::Saga.compensate(find_actionable!(id), reason: reason))}
+        end
+
+        def authorize_action!(request, action)
+          raise Error.new(403, "The console is read-only") if config.read_only
+          raise Error.new(403, "Forbidden") unless config.allowed?(request.env, action)
+          raise Error.new(403, "Cross-site request rejected") unless same_origin?(request)
+        end
+
+        def same_origin?(request)
+          return false unless request.media_type == "application/json"
+          return false if request.get_header(CSRF_HEADER).to_s.empty?
+
+          origin = request.get_header("HTTP_ORIGIN") || referer_origin(request.referer)
+          !origin.nil? && origin == request.base_url
+        end
+
+        def referer_origin(referer)
+          return if referer.nil?
+
+          uri = URI.parse(referer)
+          port = (uri.port == uri.default_port) ? "" : ":#{uri.port}"
+          "#{uri.scheme}://#{uri.host}#{port}" if uri.host
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        def find!(id)
+          store.find_execution(id) || raise(Error.new(404, "Execution #{id} not found"))
+        end
+
+        def find_actionable!(id)
+          execution = find!(id)
+          return execution if Lepus::Saga.definitions.key?(execution.saga_name)
+
+          raise Error.new(409, "Saga #{execution.saga_name} is not loaded in this process")
+        end
+
+        def body(request)
+          content = request.body&.read.to_s
+          return {} if content.empty?
+
+          data = JSON.parse(content)
+          data.is_a?(Hash) ? data : {}
+        rescue JSON::ParserError
+          raise Error.new(400, "Invalid JSON body")
+        end
+
+        def filters(request)
+          filters = {
+            saga_name: list(request, "saga"),
+            status: list(request, "status"),
+            current_step: list(request, "step"),
+            partition: param(request, "partition"),
+            resource: param(request, "resource"),
+            from: time(request, "from"),
+            to: time(request, "to"),
+            error_class: list(request, "error"),
+            error_step: list(request, "error_step"),
+            error_from: time(request, "error_from"),
+            error_to: time(request, "error_to")
+          }
+          flag?(request, "stalled") ? stalled_filters(filters) : filters
+        end
+
+        def stalled_filters(filters)
+          statuses = filters[:status] ? filters[:status] & IN_PROGRESS : IN_PROGRESS
+          raise ArgumentError, "Stalled executions are #{IN_PROGRESS.join(" or ")}" if statuses.empty?
+
+          filters.merge(status: statuses, progress_to: stalled_before)
+        end
+
+        def stalled_before = Time.now.utc - config.stalled_after
+
+        def window(request)
+          to = time(request, "to") || Time.now.utc
+          from = time(request, "from") || (to - DEFAULT_WINDOW)
+          raise ArgumentError, "from must be before to" unless from < to
+
+          [from, to]
+        end
+
+        def series_bucket(span)
+          SERIES_BUCKETS.find { |seconds| span / seconds <= SERIES_TARGET } || SERIES_BUCKETS.last
+        end
+
+        def param(request, name)
+          value = request.GET[name]
+          presence(value.strip) if value.is_a?(String)
+        end
+
+        def flag?(request, name)
+          %w[1 true].include?(param(request, name))
+        end
+
+        def list(request, name)
+          presence(param(request, name)&.split(",")&.map(&:strip)&.reject(&:empty?))
+        end
+
+        def time(request, name)
+          value = param(request, name)
+          value && Time.iso8601(value)
+        rescue ArgumentError
+          raise ArgumentError, "#{name} must be an ISO 8601 time"
+        end
+
+        def integer(request, name, default:, range:)
+          value = param(request, name)
+          return default if value.nil?
+
+          number = Integer(value, exception: false)
+          raise ArgumentError, "#{name} must be an integer in #{range}" unless number && range.cover?(number)
+
+          number
+        end
+
+        def presence(value)
+          value unless value.nil? || value.empty?
+        end
+
+        def json(status, data)
+          [status, {"content-type" => "application/json; charset=utf-8", "cache-control" => "no-store"}, [JSON.generate(data)]]
+        end
+      end
+    end
+  end
+end

data/lib/lepus/saga/web/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Saga
+    module Web
+      class Configuration
+        ACTIONS = %i[read retry compensate].freeze
+        POLL_INTERVALS = [0, 2, 5, 15, 60].freeze
+
+        # Called with the Rack env and one of ACTIONS; a falsy result answers
+        # 403. Allows everything by default.
+        attr_accessor :authorize
+
+        # Hides the retry and compensate actions and refuses their requests.
+        attr_accessor :read_only
+
+        attr_accessor :title
+
+        # Seconds between refreshes until the viewer picks another interval
+        # (one of POLL_INTERVALS; 0 turns polling off).
+        attr_accessor :default_poll_interval
+
+        # Cap on the rows read for the throughput series and step latency.
+        attr_accessor :max_rows
+
+        # Seconds without progress after which an in-progress execution
+        # counts as stalled.
+        attr_accessor :stalled_after
+
+        def initialize
+          @authorize = ->(_env, _action) { true }
+          @read_only = false
+          @title = "Sagas"
+          @default_poll_interval = 5
+          @max_rows = Stores::Base::QUERY_MAX_ROWS
+          @stalled_after = 15 * 60
+        end
+
+        def allowed?(env, action)
+          return false if read_only && action != :read
+
+          authorize.call(env, action) ? true : false
+        end
+
+        def store = Lepus::Saga.store
+      end
+    end
+  end
+end

data/lib/lepus/saga/web/guard.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Saga
+    module Web
+      # Refuses every request the `authorize` hook does not allow to read, and
+      # adds the headers every response carries.
+      class Guard
+        HEADERS = {
+          "x-content-type-options" => "nosniff",
+          "referrer-policy" => "same-origin",
+          "x-frame-options" => "SAMEORIGIN"
+        }.freeze
+
+        def initialize(app, config)
+          @app = app
+          @config = config
+        end
+
+        def call(env)
+          status, headers, body = @config.allowed?(env, :read) ? @app.call(env) : forbidden(env)
+          HEADERS.each { |name, value| headers[name] ||= value }
+          [status, headers, body]
+        end
+
+        private
+
+        def forbidden(env)
+          if env["PATH_INFO"].to_s.start_with?("/api/")
+            [403, {"content-type" => "application/json"}, [JSON.generate(error: "Forbidden")]]
+          else
+            [403, {"content-type" => "text/plain; charset=utf-8"}, ["Forbidden"]]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lepus/saga/web/serializer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Saga
+    module Web
+      module Serializer
+        EXECUTION_FIELDS = %i[
+          id saga_name resource_type resource_id status current_step direction
+          epoch correlation_id failure_reason resume_count
+        ].freeze
+        EXECUTION_TIMES = %i[started_at finished_at last_progress_at created_at updated_at].freeze
+        ATTEMPT_FIELDS = %i[
+          id step_name direction epoch attempt status error_class error_message
+          error_backtrace duration_ms
+        ].freeze
+
+        module_function
+
+        def execution(record, context: false)
+          data = EXECUTION_FIELDS.to_h { |name| [name, record.public_send(name)] }
+          EXECUTION_TIMES.each { |name| data[name] = time(record.public_send(name)) }
+          data[:partition] = partition(record)
+          data[:context] = record.context if context
+          data
+        end
+
+        def attempt(record)
+          data = ATTEMPT_FIELDS.to_h { |name| [name, record.public_send(name)] }
+          data[:duration_ms] = data[:duration_ms]&.to_f&.round(1)
+          data[:context_after] = record.context_after
+          data[:started_at] = time(record.started_at)
+          data[:finished_at] = time(record.finished_at)
+          data
+        end
+
+        def definition(name, definition)
+          {
+            name: name,
+            known: !definition.nil?,
+            partition: definition&.partition,
+            steps: Array(definition&.steps).map do |step|
+              {name: step.name, compensate: step.compensate, attempts: step.retry_policy.attempts}
+            end
+          }
+        end
+
+        def time(value)
+          value&.utc&.iso8601(3)
+        end
+
+        def partition(record)
+          record.partition
+        rescue UnknownSagaError
+          record[:partition]
+        end
+      end
+    end
+  end
+end

data/lib/lepus/saga/web/static.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Lepus
+  module Saga
+    module Web
+      # Serves the console page and its assets from Web::ROOT. The page gets a
+      # <base href> of the mount path, so every relative URL works wherever
+      # the console is mounted, and points at "assets-<digest>/", a path that
+      # changes with the asset files and is therefore cached for a year.
+      # Plain "assets/" paths are served too, revalidated through their ETag.
+      class Static
+        CONTENT_SECURITY_POLICY = [
+          "default-src 'self'", "script-src 'self'", "style-src 'self'", "img-src 'self' data:",
+          "font-src 'self'", "connect-src 'self'", "object-src 'none'", "base-uri 'self'",
+          "form-action 'self'", "frame-ancestors 'self'"
+        ].join("; ").freeze
+        IMMUTABLE = "public, max-age=31536000, immutable"
+        REVALIDATE = "no-cache"
+        INDEX_PATHS = ["", "/", "/index.html"].freeze
+
+        def initialize(config, root: ROOT)
+          @config = config
+          @root = root
+          @etags = {}
+        end
+
+        def call(env)
+          return not_allowed unless %w[GET HEAD].include?(env["REQUEST_METHOD"])
+
+          path = env["PATH_INFO"].to_s
+          return index(env) if INDEX_PATHS.include?(path)
+
+          case path
+          when %r{\A/assets-(?<digest>\h+)/(?<file>.+)\z}
+            asset(env, $~[:file], ($~[:digest] == assets_digest) ? IMMUTABLE : REVALIDATE)
+          when %r{\A/assets/(?<file>.+)\z}
+            asset(env, $~[:file], REVALIDATE)
+          else
+            not_found
+          end
+        end
+
+        private
+
+        attr_reader :config, :root
+
+        def index(env)
+          base = "#{env["SCRIPT_NAME"].to_s.chomp("/")}/"
+          html = File.read(File.join(root, "index.html"))
+            .gsub("{{base}}", Rack::Utils.escape_html(base))
+            .gsub("{{assets}}", "assets-#{assets_digest}")
+            .gsub("{{title}}", Rack::Utils.escape_html(config.title))
+          headers = {
+            "content-type" => "text/html; charset=utf-8",
+            "cache-control" => REVALIDATE,
+            "content-security-policy" => CONTENT_SECURITY_POLICY
+          }
+          respond(env, html, %("#{Digest::SHA256.hexdigest(html)[0, 32]}"), headers)
+        end
+
+        def asset(env, file, cache_control)
+          path = resolve(file)
+          return not_found unless path
+
+          headers = {"content-type" => Rack::Mime.mime_type(File.extname(path), "application/octet-stream"), "cache-control" => cache_control}
+          respond(env, File.binread(path), etag(path), headers)
+        end
+
+        def respond(env, content, etag, headers)
+          headers = headers.merge("etag" => etag)
+          return [304, headers, []] if env["HTTP_IF_NONE_MATCH"].to_s.split(/\s*,\s*/).include?(etag)
+
+          body = (env["REQUEST_METHOD"] == "HEAD") ? [] : [content]
+          [200, headers.merge("content-length" => content.bytesize.to_s), body]
+        end
+
+        def resolve(file)
+          return if file.include?("\0")
+
+          assets = File.join(root, "assets")
+          path = File.expand_path(file, assets)
+          path if path.start_with?("#{assets}/") && File.file?(path)
+        end
+
+        def etag(path)
+          stat = File.stat(path)
+          @etags[[path, stat.mtime.to_r, stat.size]] ||= %("#{Digest::SHA256.file(path).hexdigest[0, 32]}")
+        end
+
+        def assets_digest
+          assets = File.join(root, "assets")
+          files = Dir.glob(File.join(assets, "**", "*")).select { |path| File.file?(path) }.sort
+          Digest::SHA256.hexdigest(files.map { |path| "#{path.delete_prefix(assets)}:#{etag(path)}" }.join("\n"))[0, 16]
+        end
+
+        def not_found
+          [404, {"content-type" => "text/plain; charset=utf-8"}, ["Not found"]]
+        end
+
+        def not_allowed
+          [405, {"content-type" => "text/plain; charset=utf-8", "allow" => "GET, HEAD"}, ["Method not allowed"]]
+        end
+      end
+    end
+  end
+end