lepus-saga 0.3.0 → 0.3.2

data/lib/lepus/saga/stores/base.rb

@@ -29,6 +29,9 @@ module Lepus
         QUERY_MAX_ROWS = 50_000
         MAX_SERIES_BUCKETS = 1_000
         GROUPABLE = %i[saga_name status partition current_step].freeze
+        SORTS = {started_at: :started_at, duration: :duration_ms, finished_at: :finished_at}.freeze
+        NULLABLE_SORTS = %i[duration_ms finished_at].freeze
+        DIRECTIONS = %i[desc asc].freeze
         SERIES_KEYS = ["started", *ExecutionBehaviour::TERMINAL_STATUSES].freeze
         LATENCY_STATUSES = %w[succeeded failed].freeze
         PERCENTILES = {p50: 50, p95: 95, p99: 99}.freeze
@@ -87,7 +90,8 @@ module Lepus
           raise NotImplementedError
         end
 
-        # Executions of a resource, most recently created first.
+        # Executions of a resource, most recently started first (ties by id,
+        # descending).
         def executions_for_resource(resource_type, resource_id)
           raise NotImplementedError
         end
@@ -112,6 +116,16 @@ module Lepus
           raise NotImplementedError
         end
 
+        # Names of the steps each of `executions` ran forward (attempts in the
+        # execute direction, whatever their status), as a Hash keyed by
+        # execution id, every id present. Stores override it to read them in
+        # one query.
+        def executed_steps(executions)
+          executions.to_h do |execution|
+            [execution.id, step_attempts(execution).select { |attempt| attempt.direction == "execute" }.map(&:step_name).uniq]
+          end
+        end
+
         # Number of attempts of `execution` for this step, direction and epoch,
         # whatever their status.
         def count_step_attempts(execution, step_name:, direction:, epoch:)
@@ -139,23 +153,38 @@ module Lepus
         # Whether the optional query methods below are implemented.
         def queries? = false
 
-        # Executions matching the filters, newest first by id (UUIDv7, so by
-        # creation time), at most `limit` of them. `before_id` returns the
-        # page after the execution with that id. Every filter is optional:
-        # `saga_name`, `status` and `current_step` take a value or a list;
-        # `partition` matches the partition column, and executions without one
-        # whose definition runs in that partition; `resource` is a
-        # case-insensitive substring of resource_type or resource_id; `from`
-        # (inclusive) and `to` (exclusive) bound created_at, `progress_from`
-        # and `progress_to` bound last_progress_at the same way (in-progress
-        # executions with `progress_to: Time.now.utc - 15 * 60` are the
-        # stalled ones). `error_class` and `error_step` take a value or a list
-        # and keep executions with a failed attempt of that error class and at
-        # that step (either filter alone matches on its own attribute);
+        # Executions matching the filters, at most `limit` of them, in the
+        # order of `sort` and `direction`:
+        #
+        # - `sort: :started_at` (the default), `:duration` (duration_ms) or
+        #   `:finished_at`, `direction: :desc` (the default) or `:asc`. The id
+        #   breaks ties in the same direction. Executions without a value
+        #   (in-progress ones have no duration_ms or finished_at) come last in
+        #   either direction, by id. Ids need not follow time: rows written
+        #   with ids that are not time-ordered (e.g. random UUIDv4) still list
+        #   in time order.
+        # - `after` is the id of the last execution of the previous page: the
+        #   page holds the executions strictly after it, by (sort value, id),
+        #   in the same order. An `after` that names no execution returns an
+        #   empty page.
+        #
+        # Every filter is optional: `saga_name`, `status` and `current_step`
+        # take a value or a list; `partition` matches the partition column,
+        # and executions without one whose definition runs in that partition;
+        # `resource` is a case-insensitive substring of resource_type or
+        # resource_id; `from` (inclusive) and `to` (exclusive) bound
+        # started_at, `progress_from` and `progress_to` bound
+        # last_progress_at and `finished_from` and `finished_to` bound
+        # finished_at the same way (in-progress executions with
+        # `progress_to: Time.now.utc - 15 * 60` are the stalled ones).
+        # `error_class` and `error_step` take a value or a list and keep
+        # executions with a failed attempt of that error class and at that
+        # step (either filter alone matches on its own attribute);
         # `error_from` (inclusive) and `error_to` (exclusive) bound that
         # failed attempt's started_at, the window #failure_summary counts.
-        def list_executions(saga_name: nil, status: nil, current_step: nil, partition: nil, resource: nil, from: nil, to: nil,
-          progress_from: nil, progress_to: nil, error_class: nil, error_step: nil, error_from: nil, error_to: nil, before_id: nil, limit: 50)
+        def list_executions(sort: :started_at, direction: :desc, after: nil, limit: 50, saga_name: nil, status: nil, current_step: nil,
+          partition: nil, resource: nil, from: nil, to: nil, progress_from: nil, progress_to: nil, finished_from: nil, finished_to: nil,
+          error_class: nil, error_step: nil, error_from: nil, error_to: nil)
           raise NotImplementedError
         end
 
@@ -165,11 +194,37 @@ module Lepus
         # resolves executions without one to their definition's partition
         # (nil for an unknown saga).
         def count_executions(group_by:, saga_name: nil, status: nil, current_step: nil, partition: nil, resource: nil, from: nil, to: nil,
-          progress_from: nil, progress_to: nil, error_class: nil, error_step: nil, error_from: nil, error_to: nil)
+          progress_from: nil, progress_to: nil, finished_from: nil, finished_to: nil, error_class: nil, error_step: nil, error_from: nil,
+          error_to: nil)
           raise NotImplementedError
         end
 
-        # Executions started (by created_at) and finished in each terminal
+        # Executions that finished between `from` (inclusive) and `to`
+        # (exclusive), latest finish first (ties by id), at most `per_saga`
+        # of each saga when given and at most `limit` in all. `saga_name`
+        # takes a value or a list. Returns `{executions: [...], counts:
+        # {[saga_name, status] => n}}`, the counts covering every execution
+        # that finished in the window, so a caller can tell how many the
+        # limits left out. `listed_from` (at most `from`) widens the listed
+        # executions, not the counts, back to that time, so a caller polling
+        # with some overlap can catch late writes without counting them
+        # twice. Built on #list_executions and #count_executions.
+        def finished_executions(from:, to:, listed_from: nil, saga_name: nil, per_saga: nil, limit: 100)
+          counts = count_executions(group_by: %i[saga_name status], saga_name: saga_name, finished_from: from, finished_to: to)
+          window = {saga_name: saga_name, finished_from: [listed_from, from].compact.min, finished_to: to}
+          names = (per_saga && listed_from.nil?) ? counts.keys.map(&:first).uniq : nil
+          executions = if per_saga
+            (names || saga_names_finished(**window)).sort.flat_map do |name|
+              list_executions(**window, saga_name: name, sort: :finished_at, limit: [per_saga, limit].min)
+            end
+          else
+            list_executions(**window, sort: :finished_at, limit: limit)
+          end
+          ordered = executions.sort_by { |execution| [execution.finished_at.to_r, execution.id] }.reverse
+          {executions: ordered.first(limit), counts: counts}
+        end
+
+        # Executions started (by started_at) and finished in each terminal
         # status (by finished_at) per `bucket` seconds between `from` and
         # `to`. Returns `{rows: [[bucket_start, {"started" => n, "completed" =>
         # n, ...}], ...], truncated:}` with every bucket of the window, bucket
@@ -226,6 +281,22 @@ module Lepus
           attributes.each { |name, value| record.public_send(:"#{name}=", value) }
         end
 
+        # The column and direction of a #list_executions order, and whether
+        # rows without a value can match: never for finished_at when a
+        # finished_at bound is among the filters.
+        def list_order(sort, direction, filters = {})
+          column = SORTS[sort.to_s.to_sym] || raise(ArgumentError, "Cannot sort executions by #{sort.inspect}")
+          descending = direction.to_s.to_sym
+          raise ArgumentError, "Unknown sort direction #{direction.inspect}" unless DIRECTIONS.include?(descending)
+
+          bounded = column == :finished_at && (filters[:finished_from] || filters[:finished_to])
+          [column, descending == :desc, NULLABLE_SORTS.include?(column) && !bounded]
+        end
+
+        def saga_names_finished(**window)
+          count_executions(group_by: :saga_name, **window).keys
+        end
+
         def filter_values(value)
           values = Array(value).map(&:to_s)
           values unless values.empty?

data/lib/lepus/saga/stores/memory.rb

@@ -131,7 +131,7 @@ module Lepus
 
         def executions_for_resource(resource_type, resource_id)
           where(@executions, Execution) { |row| row[:resource_type] == resource_type && row[:resource_id] == resource_id }
-            .sort_by { |execution| [execution.created_at, execution.id] }.reverse
+            .sort_by { |execution| [execution.started_at, execution.id] }.reverse
         end
 
         def create_step_attempt(execution, attributes)
@@ -177,10 +177,15 @@ module Lepus
 
         def queries? = true
 
-        def list_executions(before_id: nil, limit: 50, **filters)
+        def list_executions(sort: :started_at, direction: :desc, after: nil, limit: 50, **filters)
+          column, descending, = list_order(sort, direction, filters)
+          cursor = after && find_execution(after)
+          return [] if after && !cursor
+
+          compare = list_comparator(column, descending)
           executions = matching_executions(**filters)
-          executions = executions.select { |execution| execution.id < before_id } if before_id
-          executions.sort_by(&:id).reverse.first(limit)
+          executions = executions.select { |execution| compare.call(execution, cursor).positive? } if cursor
+          executions.sort(&compare).first(limit)
         end
 
         def count_executions(group_by:, **filters)
@@ -192,7 +197,7 @@ module Lepus
           window = from...to
           executions = matching_executions(saga_name: saga_name)
           started, started_truncated = take_rows(
-            executions.map(&:created_at).select { |time| window.cover?(time) }.sort.reverse, max_rows
+            executions.map(&:started_at).select { |time| window.cover?(time) }.sort.reverse, max_rows
           )
           finished, finished_truncated = take_rows(
             executions.select { |execution| execution.terminal? && window.cover?(execution.finished_at) }
@@ -229,7 +234,8 @@ module Lepus
         private
 
         def matching_executions(saga_name: nil, status: nil, current_step: nil, partition: nil, resource: nil, from: nil, to: nil,
-          progress_from: nil, progress_to: nil, error_class: nil, error_step: nil, error_from: nil, error_to: nil)
+          progress_from: nil, progress_to: nil, finished_from: nil, finished_to: nil, error_class: nil, error_step: nil, error_from: nil,
+          error_to: nil)
           sagas = filter_values(saga_name)
           statuses = filter_values(status)
           steps = filter_values(current_step)
@@ -241,16 +247,35 @@ module Lepus
             (sagas.nil? || sagas.include?(row[:saga_name])) &&
               (statuses.nil? || statuses.include?(row[:status])) &&
               (steps.nil? || steps.include?(row[:current_step])) &&
-              (from.nil? || row[:created_at] >= from) &&
-              (to.nil? || row[:created_at] < to) &&
-              (progress_from.nil? || row[:last_progress_at] >= progress_from) &&
-              (progress_to.nil? || row[:last_progress_at] < progress_to) &&
+              within?(row[:started_at], from, to) &&
+              within?(row[:last_progress_at], progress_from, progress_to) &&
+              within?(row[:finished_at], finished_from, finished_to) &&
               (failing.nil? || failing.include?(row[:id])) &&
               (partition_sagas.nil? || in_partition?(row, partition.to_s, partition_sagas)) &&
               (needle.nil? || row.values_at(:resource_type, :resource_id).any? { |value| value.to_s.downcase.include?(needle) })
           end
         end
 
+        # Orders by the column in the given direction with nulls last either
+        # way, then by id in the same direction.
+        def list_comparator(column, descending)
+          lambda do |left, right|
+            a = left[column]
+            b = right[column]
+            next(a.nil? ? 1 : -1) if a.nil? != b.nil?
+
+            order = (a.nil? ? 0 : a <=> b).nonzero? || left.id <=> right.id
+            descending ? -order : order
+          end
+        end
+
+        def within?(value, from, to)
+          return true if from.nil? && to.nil?
+          return false if value.nil?
+
+          (from.nil? || value >= from) && (to.nil? || value < to)
+        end
+
         def failing_execution_ids(error_classes, steps, from, to)
           return if [error_classes, steps, from, to].all?(&:nil?)
 

data/lib/lepus/saga/version.rb

@@ -2,6 +2,6 @@
 
 module Lepus
   module Saga
-    VERSION = "0.3.0"
+    VERSION = "0.3.2"
   end
 end

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

@@ -25,6 +25,7 @@ module Lepus
           ["GET", %r{\A/executions\z}, :executions],
           ["GET", %r{\A/executions/(?<id>[^/]+)\z}, :execution],
           ["GET", %r{\A/moving\z}, :moving],
+          ["GET", %r{\A/recent\z}, :recent],
           ["GET", %r{\A/series\z}, :series],
           ["GET", %r{\A/insights/failures\z}, :failures],
           ["GET", %r{\A/insights/latency\z}, :latency],
@@ -40,6 +41,8 @@ module Lepus
         IN_PROGRESS = ExecutionBehaviour::IN_PROGRESS_STATUSES
         STOPPED_STATUSES = %w[failed compensation_failed].freeze
         RELATED_LIMIT = 20
+        SORTS = {"started_at" => :started_at, "duration" => :duration}.freeze
+        DIRECTIONS = %w[desc asc].freeze
 
         def initialize(config)
           @config = config
@@ -104,7 +107,7 @@ module Lepus
               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}
+          {now: Serializer.time(Time.now.utc), from: Serializer.time(from), to: Serializer.time(to), stalled_after: config.stalled_after, sagas: sagas}
         end
 
         def stations(name, counts, stalled, failures)
@@ -121,12 +124,18 @@ module Lepus
           stations
         end
 
+        # A page of executions in the order of `sort` (started_at or
+        # duration) and `dir`; `next` is the `after` of the following page.
         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)
+          sort = choice(request, "sort", SORTS.keys, default: "started_at")
+          direction = choice(request, "dir", DIRECTIONS, default: "desc")
+          rows = store.list_executions(**filters(request), sort: SORTS[sort], direction: direction.to_sym,
+            after: param(request, "after"), limit: limit + 1)
           {
+            sort: sort, dir: direction,
             executions: rows.first(limit).map { |execution| Serializer.execution(execution) },
-            next_before: (rows[limit - 1].id if rows.size > limit)
+            next: (rows[limit - 1].id if rows.size > limit)
           }
         end
 
@@ -143,7 +152,40 @@ module Lepus
             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}
+          {now: Serializer.time(Time.now.utc), stalled_after: config.stalled_after, stations: stations, omitted: counts.size - busiest.size}
+        end
+
+        # Executions that finished since `since` (the `now` of an earlier
+        # response), per saga line: the latest `per_saga` of them with the
+        # steps they passed, and counts by status of every one, so a live
+        # view can finish or replay them without losing any. `replay_from`
+        # (before `since`) also lists, without counting, the ones that
+        # finished from then on, for writes that landed after the last poll.
+        def recent(request)
+          since = time(request, "since") || raise(ArgumentError, "since must be an ISO 8601 time")
+          now = Time.now.utc
+          raise ArgumentError, "since must be before now" unless since < now
+
+          replay_from = time(request, "replay_from")
+          replay_from = nil if replay_from && replay_from >= since
+          per_saga = integer(request, "per_saga", default: 8, range: 1..50)
+          limit = integer(request, "limit", default: 100, range: 1..500)
+          result = store.finished_executions(
+            from: since, to: now, listed_from: replay_from, saga_name: list(request, "saga"), per_saga: per_saga, limit: limit
+          )
+          steps = store.executed_steps(result[:executions].reject { |execution| execution.status == "completed" })
+          by_saga = result[:executions].group_by(&:saga_name)
+          counts = result[:counts].group_by { |(saga, _status), _count| saga }
+          lines = (by_saga.keys | counts.keys).sort.map do |saga|
+            line_counts = counts.fetch(saga, [])
+            {
+              saga_name: saga,
+              total: line_counts.sum(&:last),
+              counts: line_counts.to_h { |(_saga, status), count| [status, count] },
+              executions: by_saga.fetch(saga, []).map { |execution| Serializer.finished(execution, steps.fetch(execution.id, [])) }
+            }
+          end
+          {now: Serializer.time(now), since: Serializer.time(since), lines: lines}
         end
 
         def execution(_request, id:)
@@ -288,6 +330,13 @@ module Lepus
           presence(value.strip) if value.is_a?(String)
         end
 
+        def choice(request, name, values, default:)
+          value = param(request, name) || default
+          raise ArgumentError, "#{name} must be one of #{values.join(", ")}" unless values.include?(value)
+
+          value
+        end
+
         def flag?(request, name)
           %w[1 true].include?(param(request, name))
         end

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

@@ -6,7 +6,7 @@ module Lepus
       module Serializer
         EXECUTION_FIELDS = %i[
           id saga_name resource_type resource_id status current_step direction
-          epoch correlation_id failure_reason resume_count
+          epoch correlation_id failure_reason resume_count duration_ms
         ].freeze
         EXECUTION_TIMES = %i[started_at finished_at last_progress_at created_at updated_at].freeze
         ATTEMPT_FIELDS = %i[
@@ -24,6 +24,19 @@ module Lepus
           data
         end
 
+        # A finished execution and the steps it passed: `reached` is the
+        # furthest step it ran forward and, on the compensation path,
+        # `back_to` the last step it compensated (or failed compensating).
+        def finished(record, executed)
+          steps = Array(Lepus::Saga.definitions[record.saga_name]&.steps).map(&:name)
+          reached = executed.max_by { |name| steps.index(name) || -1 } || record.current_step
+          {
+            id: record.id, saga_name: record.saga_name, status: record.status,
+            started_at: time(record.started_at), finished_at: time(record.finished_at), duration_ms: record.duration_ms,
+            reached: reached, back_to: (record.current_step if record.compensate_direction?)
+          }
+        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/lib/lepus/saga.rb

@@ -95,7 +95,7 @@ module Lepus
             epoch: execution.epoch + 1,
             status: execution.compensate_direction? ? "compensating" : "running",
             failure_reason: nil,
-            finished_at: nil)
+            **execution.reopen_attributes)
         end
         Instrumentation.saga_event("saga.resumed", execution)
         StepProducer.publish_step(execution)

data/web/assets/app.css

@@ -300,6 +300,21 @@ button, input, select { font: inherit; color: inherit; }
 .sym-idle { fill: var(--paper); stroke: var(--token); stroke-width: 3; }
 .sym-stop { fill: var(--stop); }
 .sym-back { fill: var(--back); }
+.sym-replay { fill: var(--token); fill-opacity: 0.5; stroke: var(--line); stroke-width: 2; stroke-opacity: 0.45; }
+
+.m-key {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 18px;
+  list-style: none;
+  margin: -6px 0 18px;
+  padding: 0;
+  color: var(--ink-3);
+  font-size: 13px;
+  font-weight: 550;
+}
+.m-key li { display: inline-flex; align-items: center; gap: 6px; }
+.m-key .sym svg { display: block; width: 14px; height: 14px; overflow: visible; }
 
 /* The map */
 
@@ -366,6 +381,14 @@ button, input, select { font: inherit; color: inherit; }
 .t-more.is-back { stroke: var(--back); }
 .t-more-n { fill: var(--token-text); font-size: 11.5px; font-weight: 750; }
 .t-more-n.is-back { fill: var(--back-text); }
+.t-token.is-replay { fill-opacity: 0.5; stroke-opacity: 0.6; }
+.t-flash { fill: var(--stop); }
+.t-note { fill: var(--raise); stroke: var(--rule); stroke-width: 1.5; }
+.t-note-n { font-size: 11.5px; font-weight: 750; }
+.t-note-pale, .t-note-sep { fill: var(--ink-2); }
+.t-note-done { fill: var(--ink-2); }
+.t-note-back { fill: var(--back-text); }
+.t-note-stop { fill: var(--stop-text); }
 .g-trail-move { stop-color: var(--token); }
 .g-trail-back { stop-color: var(--back); }
 
@@ -801,7 +824,25 @@ button, input, select { font: inherit; color: inherit; }
   border-bottom: 1px solid var(--rule);
 }
 .rows td { padding: 12px 12px 12px 0; border-bottom: 1px solid var(--rule-soft); vertical-align: middle; }
-.rows tr { cursor: pointer; }
+.rows tbody tr { cursor: pointer; }
+.rows th .sort {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  margin: -4px -6px;
+  padding: 4px 6px;
+  border: 0;
+  border-radius: 6px;
+  background: none;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+.rows th .sort:hover { color: var(--ink); background: var(--rule-soft); }
+.rows th .sort svg { width: 10px; height: 10px; fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; opacity: 0.45; }
+.rows th[aria-sort="ascending"] .sort, .rows th[aria-sort="descending"] .sort { color: var(--ink); }
+.rows th[aria-sort="ascending"] .sort svg, .rows th[aria-sort="descending"] .sort svg { opacity: 1; }
+.sort-pick { display: none; }
 .rows tbody tr:hover td { background: var(--rule-soft); }
 .rows td:first-child, .rows th:first-child { padding-left: 4px; }
 .rows .r-res a { font-weight: 650; text-decoration: none; overflow-wrap: anywhere; }
@@ -875,6 +916,7 @@ button, input, select { font: inherit; color: inherit; }
   .h-took { grid-column: 3; padding-left: 6px; padding-top: 0; }
   .h-error, .h-trace { grid-column: 3; }
   .rows thead { display: none; }
+  .sort-pick { display: inline-block; }
   .rows, .rows tbody, .rows tr, .rows td { display: block; }
   .rows tr {
     display: grid;
@@ -890,6 +932,8 @@ button, input, select { font: inherit; color: inherit; }
   .rows .r-step { grid-column: 1; font-size: 14px; }
   .rows .r-when { grid-column: 2; text-align: right; }
   .rows .r-took { display: none; }
+  .rows.is-by-took .r-when { display: none; }
+  .rows.is-by-took .r-took { display: block; grid-column: 2; text-align: right; }
 }
 
 @media (min-width: 1700px) {

data/web/assets/js/api.js

@@ -41,6 +41,7 @@ export const api = {
   executions: (params) => request(url("executions", params)),
   execution: (id) => request(url(`executions/${encodeURIComponent(id)}`)),
   moving: (params) => request(url("moving", params)),
+  recent: (params) => request(url("recent", params)),
   series: (params) => request(url("series", params)),
   failures: (params) => request(url("insights/failures", params)),
   latency: (params) => request(url("insights/latency", params)),

data/web/assets/js/dom.js

@@ -9,7 +9,7 @@ function apply(el, attrs) {
   }
 }
 
-function append(el, children) {
+export function append(el, children) {
   for (const child of children.flat(Infinity)) {
     if (child === null || child === undefined || child === false) continue;
     el.append(child instanceof Node ? child : document.createTextNode(String(child)));