Implementation/45801 api with subset representer

app/models/journable/with_historic_attributes.rb

@@ -0,0 +1,212 @@
+#-- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) 2012-2022 the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+#++
+
+# This class is used to wrap a Journable and provide access to its attributes at given timestamps.
+# It is used to provide the old and new values of a journable in the journables's payload.
+# https://github.com/opf/openproject/pull/11783
+#
+# Usage:
+#
+#   # Wrap single work package
+#   timestamps = [Timestamp.parse("2022-01-01T00:00:00Z"), Timestamp.parse("PT0S")]
+#   work_package = WorkPackage.find(1)
+#   work_package = Journable::WithHistoricAttributes.wrap(work_package, timestamps:)
+#
+#   # Wrap multiple work packages
+#   timestamps = query.timestamps
+#   work_packages = query.results.work_packages
+#   work_packages = Journable::WithHistoricAttributes.wrap_multiple(work_packages, timestamps:)
+#
+#   # Access historic attributes at timestamps after wrapping
+#   work_package = Journable::WithHistoricAttributes.wrap(work_package, timestamps:)
+#   work_package.subject  # => "Subject at PT0S (current time)"
+#   work_package.attributes_by_timestamp["2022-01-01T00:00:00Z"].subject  # => "Subject at 2022-01-01 (baseline time)"
+#
+#   # Check at which timestamps the work package matches query filters after wrapping
+#   query.timestamps  # => [<Timestamp 2022-01-01T00:00:00Z>, <Timestamp PT0S>]
+#   work_package = Journable::WithHistoricAttributes.wrap(work_package, query:)
+#   work_package.matches_query_filters_at_timestamps  # => [<Timestamp 2022-01-01T00:00:00Z>]
+#
+#   # Include only changed attributes in payload
+#   # i.e. only historic attributes that differ from the work_package's attributes
+#   timestamps = [Timestamp.parse("2022-01-01T00:00:00Z"), Timestamp.parse("PT0S")]
+#   work_package = Journable::WithHistoricAttributes.wrap(work_package, timestamps:, include_only_changed_attributes: true)
+#   work_package.attributes_by_timestamp["2022-01-01T00:00:00Z"].subject  # => "Subject at 2022-01-01 (baseline time)"
+#   work_package.attributes_by_timestamp["PT0S"].subject  # => nil
+#
+#   # Simplified interface for two timestamps
+#   query.timestamps  # => [<Timestamp 2022-01-01T00:00:00Z>, <Timestamp PT0S>]
+#   work_package = Journable::WithHistoricAttributes.wrap(work_package, query:)
+#   work_package.baseline_timestamp  # => [<Timestamp 2022-01-01T00:00:00Z>]
+#   work_package.current_timestamp  # => [<Timestamp PT0S>]
+#   work_package.matches_query_filters_at_baseline_timestamp?
+#   work_package.matches_query_filters_at_current_timestamp?
+#   work_package.baseline_attributes.subject # => "Subject at 2022-01-01 (baseline time)"
+#   work_package.subject  # => "Subject at PT0S (current time)"
+#
+class Journable::WithHistoricAttributes < SimpleDelegator
+  attr_accessor :timestamps,
+                :query,
+                :include_only_changed_attributes,
+                :loader
+
+  def initialize(journable,
+                 timestamps: nil,
+                 query: nil,
+                 include_only_changed_attributes: false,
+                 loader: Loader.new(journable))
+    super(journable)
+
+    if query and not journable.is_a? WorkPackage
+      raise Journable::NotImplementedError, "Journable::WithHistoricAttributes with query " \
+                                            "is only implemented for WorkPackages at the moment " \
+                                            "because Query objects currently only support work packages."
+    end
+
+    self.query = query
+    self.timestamps = timestamps || query.try(:timestamps) || []
+    self.include_only_changed_attributes = include_only_changed_attributes
+
+    self.loader = loader
+  end
+  private_class_method :new
+
+  class << self
+    def wrap(journable_or_journables,
+             timestamps: query.try(:timestamps) || [],
+             query: nil,
+             include_only_changed_attributes: false)
+      wrapped = wrap_each_journable(Array(journable_or_journables), timestamps:, query:, include_only_changed_attributes:)
+
+      case journable_or_journables
+      when Array, ActiveRecord::Relation
+        wrapped
+      else
+        wrapped.first
+      end
+    end
+
+    private
+
+    def wrap_each_journable(journables, timestamps:, query:, include_only_changed_attributes:)
+      loader = Loader.new(journables)
+      journables = loader.at_timestamp(timestamps.last).values if timestamps.last.try(:historic?)
+
+      journables.map { |j| new(j, timestamps:, query:, include_only_changed_attributes:, loader:) }
+    end
+  end
+
+  def attributes_by_timestamp
+    @attributes_by_timestamp ||= Hash.new do |h, t|
+      attributes = if include_only_changed_attributes
+                     changes_at_timestamp(t)&.transform_values(&:last)
+                   else
+                     historic_attributes_at(t)
+                   end
+
+      h[t] = attributes ? Hashie::Mash.new(attributes) : nil
+    end
+  end
+
+  def changed_at_timestamp(timestamp)
+    changes_at_timestamp(timestamp)&.keys || []
+  end
+
+  def matches_query_filters_at_timestamps
+    if query.present?
+      timestamps.select { |timestamp| loader.work_package_ids_of_query_at_timestamp(query:, timestamp:).include?(__getobj__.id) }
+    else
+      []
+    end
+  end
+
+  def exists_at_timestamps
+    timestamps.select { |t| at_timestamp(t).present? }
+  end
+
+  def baseline_timestamp
+    timestamps.first
+  end
+
+  def baseline_attributes
+    attributes_by_timestamp[baseline_timestamp.to_s]
+  end
+
+  def matches_query_filters_at_baseline_timestamp?
+    matches_query_filters_at_timestamps.include?(baseline_timestamp)
+  end
+
+  def current_timestamp
+    timestamps.last
+  end
+
+  def matches_query_filters_at_current_timestamp?
+    matches_query_filters_at_timestamps.include?(current_timestamp)
+  end
+
+  def matches_query_filters_at_timestamp?(timestamp)
+    matches_query_filters_at_timestamps.include?(timestamp)
+  end
+
+  def at_timestamp(timestamp)
+    loader.journable_at_timestamp(__getobj__, timestamp)
+  end
+
+  def to_ary
+    __getobj__.send(:to_ary)
+  end
+
+  def inspect
+    __getobj__.inspect.gsub(/#<(.+)>/m, "#<#{self.class.name} \\1>")
+  end
+
+  private
+
+  def historic_attributes_at(timestamp)
+    historic_journable = at_timestamp(Timestamp.parse(timestamp))
+
+    return unless historic_journable
+
+    historic_journable
+      .attributes
+      .select do |key, _|
+        respond_to?(key)
+      end
+  end
+
+  def changes_at_timestamp(timestamp)
+    historic_journable = at_timestamp(Timestamp.parse(timestamp))
+
+    return unless historic_journable
+
+    ::Acts::Journalized::JournableDiffer
+      .changes(__getobj__, historic_journable)
+  end
+
+  class NotImplemented < StandardError; end
+end

app/models/journable/with_historic_attributes/loader.rb

@@ -0,0 +1,69 @@
+# -- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) 2010-2023 the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+# ++
+
+class Journable::WithHistoricAttributes
+  class Loader
+    def initialize(journables)
+      @journables = Array(journables)
+    end
+
+    def journable_at_timestamp(journable, timestamp)
+      at_timestamp(timestamp)[journable.id]
+    end
+
+    def at_timestamp(timestamp)
+      @at_timestamp ||= Hash.new do |h, t|
+        h[t] = journables.first.class.at_timestamp(t).where(id: journables.map(&:id)).index_by(&:id)
+      end
+
+      @at_timestamp[timestamp]
+    end
+
+    def work_package_ids_of_query_at_timestamp(query:, timestamp: nil)
+      @work_package_ids_of_query_at_timestamp ||= Hash.new do |qh, q|
+        qh[q] = Hash.new do |ht, t|
+          ht[t] = work_package_ids_of_query_at_timestamp_calculation(q, t)
+        end
+      end
+
+      @work_package_ids_of_query_at_timestamp[query][timestamp]
+    end
+
+    private
+
+    def work_package_ids_of_query_at_timestamp_calculation(query, timestamp)
+      query = query.dup
+      query.timestamps = [timestamp] if timestamp
+
+      query.results.work_packages.where(id: journables.map(&:id)).pluck(:id)
+    end
+
+    attr_accessor :journables
+  end
+  private_constant :Loader
+end

app/models/timestamp.rb

@@ -40,14 +40,29 @@ def initialize(arg = Timestamp.now.to_s)
   end
 
   def self.parse(iso8601_string)
+    return iso8601_string if iso8601_string.is_a?(Timestamp)
+
+    iso8601_string.strip!
+    iso8601_string = substitute_special_shortcut_values(iso8601_string)
     if iso8601_string.start_with? "P" # ISO8601 "Period"
-      ActiveSupport::Duration.parse(iso8601_string)
-    elsif Time.zone.parse(iso8601_string).blank?
-      raise ArgumentError, "The string \"#{iso8601_string}\" cannot be parsed to a Time."
+      iso8601_string = ActiveSupport::Duration.parse(iso8601_string).iso8601
+    elsif (time = Time.zone.parse(iso8601_string)).present?
+      iso8601_string = time.iso8601
+    else
+      raise ArgumentError, "The string \"#{iso8601_string}\" cannot be parsed to Time or ActiveSupport::Duration."
     end
     Timestamp.new(iso8601_string)
   end
 
+  # Take a comma-separated string of ISO-8601 timestamps and convert it
+  # into an array of Timestamp objects.
+  #
+  def self.parse_multiple(comma_separated_iso8601_string)
+    comma_separated_iso8601_string.to_s.split(",").compact_blank.collect do |iso8601_string|
+      Timestamp.parse(iso8601_string)
+    end
+  end
+
   def self.now
     new(ActiveSupport::Duration.build(0).iso8601)
   end
@@ -68,10 +83,18 @@ def iso8601
     @timestamp_iso8601_string.to_s
   end
 
+  def to_iso8601
+    iso8601
+  end
+
   def inspect
     "#<Timestamp \"#{iso8601}\">"
   end
 
+  def absolute
+    Timestamp.new(to_time)
+  end
+
   def to_time
     if relative?
       Time.zone.now - (to_duration * (to_duration.to_i.positive? ? 1 : -1))
@@ -88,7 +111,7 @@ def to_duration
     end
   end
 
-  def as_json
+  def as_json(*_args)
     to_s
   end
 
@@ -97,8 +120,54 @@ def to_json(*_args)
   end
 
   def ==(other)
-    iso8601 == other.iso8601
+    case other
+    when String
+      iso8601 == other or to_s == other
+    when Timestamp
+      iso8601 == other.iso8601
+    when NilClass
+      to_s.blank?
+    else
+      raise Timestamp::Exception, "Comparison to #{other.class.name} not implemented, yet."
+    end
+  end
+
+  def eql?(other)
+    self == other
   end
 
+  def historic?
+    self != Timestamp.now
+  end
+
+  delegate :hash, to: :iso8601
+
   class Exception < StandardError; end
+
+  # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/PerceivedComplexity
+  def self.substitute_special_shortcut_values(string)
+    # map now to PT0S
+    string = "PT0S" if string == "now"
+
+    # map 1y to P1Y, 1m to P1M, 1w to P1W, 1d to P1D
+    # map -1y to P-1Y, -1m to P-1M, -1w to P-1W, -1d to P-1D
+    # map -1y1d to P-1Y-1D
+    sign = "-" if string.start_with? "-"
+    years = string.scan(/(\d+)y/).flatten.first
+    months = string.scan(/(\d+)m/).flatten.first
+    weeks = string.scan(/(\d+)w/).flatten.first
+    days = string.scan(/(\d+)d/).flatten.first
+    if years || months || weeks || days
+      string = "P" \
+               "#{sign if years}#{years}#{'Y' if years}" \
+               "#{sign if months}#{months}#{'M' if months}" \
+               "#{sign if weeks}#{weeks}#{'W' if weeks}" \
+               "#{sign if days}#{days}#{'D' if days}"
+    end
+
+    string
+  end
+  # rubocop:enable Metrics/AbcSize
+  # rubocop:enable Metrics/PerceivedComplexity
 end