wcc-contentful 0.4.0.pre.alpha → 1.0.0.pre.rc3

data/lib/wcc/contentful/store/postgres_store/schema_1.sql

@@ -0,0 +1,73 @@
+CREATE TABLE IF NOT EXISTS wcc_contentful_schema_version (
+  version integer PRIMARY KEY,
+  updated_at timestamp DEFAULT now()
+);
+
+START TRANSACTION;
+
+CREATE TABLE IF NOT EXISTS contentful_raw (
+  -- The Contentful 'sys'->'id'
+  id varchar PRIMARY KEY,
+  -- The contentful entry
+  data jsonb,
+  -- Every ID that this entry links to in 'fields'->*->[each locale]->'sys'->'id'
+  links text[]
+);
+CREATE INDEX IF NOT EXISTS contentful_raw_value_type ON contentful_raw ((data->'sys'->>'type'));
+CREATE INDEX IF NOT EXISTS contentful_raw_value_content_type ON contentful_raw ((data->'sys'->'contentType'->'sys'->>'id'));
+
+-- Insert or update a Contentful entry by it's ID
+CREATE or replace FUNCTION "fn_contentful_upsert_entry"(_id varchar, _data jsonb, _links text[]) RETURNS jsonb AS $$
+DECLARE
+  prev jsonb;
+BEGIN
+  SELECT data, links FROM contentful_raw WHERE id = _id INTO prev;
+  INSERT INTO contentful_raw (id, data, links) values (_id, _data, _links)
+    ON CONFLICT (id) DO
+      UPDATE
+      SET data = _data,
+        links = _links;
+  RETURN prev;
+END;
+$$ LANGUAGE 'plpgsql';
+
+-- Joins the entries table to itself by all the linked entries down to depth 5.
+-- Each entry has a row for each downstream entry in it's tree.
+-- Example:
+--  | id    | included_id | depth |
+--  | page1 | page2       | 1     |
+--  | page1 | subpage2    | 2     | -- through page2
+--  | page1 | asset1      | 1     |
+--  | page2 | subpage2    | 1     |
+--  ...
+CREATE MATERIALIZED VIEW IF NOT EXISTS contentful_raw_includes_ids_jointable AS
+  WITH RECURSIVE includes (root_id, depth) AS (
+    SELECT t.id as root_id, 0, t.id, t.links FROM contentful_raw t
+    UNION ALL
+      SELECT l.root_id, l.depth + 1, r.id, r.links
+      FROM includes l, contentful_raw r
+      WHERE r.id = ANY(l.links) AND l.depth < 5
+  )
+  SELECT root_id as id, id as included_id, min(depth)
+    FROM includes
+    GROUP BY root_id, id;
+
+CREATE INDEX IF NOT EXISTS contentful_raw_includes_ids_jointable_id ON contentful_raw_includes_ids_jointable (id);
+CREATE UNIQUE INDEX IF NOT EXISTS contentful_raw_includes_ids_jointable_id_included_id ON contentful_raw_includes_ids_jointable (id, included_id);
+
+-- Uses the contentful_raw_includes_ids_jointable to join the entries table to itself,
+-- aggregating the included entries into an array.
+-- Example:
+--  | id    | data  | includes                                    |
+--  | page1 | jsonb | {page2 jsonb, subpage2 jsonb, asset1 jsonb} |
+CREATE OR REPLACE VIEW contentful_raw_includes AS
+  SELECT t.id, t.data, array_remove(array_agg(r_incl.data), NULL) as includes
+    FROM contentful_raw t
+    LEFT JOIN contentful_raw_includes_ids_jointable incl ON t.id = incl.id
+    LEFT JOIN contentful_raw r_incl ON r_incl.id = incl.included_id
+    GROUP BY t.id, t.data;
+
+INSERT INTO wcc_contentful_schema_version
+  VALUES (1);
+
+COMMIT;

data/lib/wcc/contentful/store/postgres_store/schema_2.sql

@@ -0,0 +1,21 @@
+START TRANSACTION;
+
+  -- Convert a jsonb array or jsonb value to a jsonb array 
+  CREATE or replace FUNCTION "fn_contentful_jsonb_any_to_jsonb_array"(potential_arr jsonb) RETURNS jsonb AS $$
+  DECLARE
+    result jsonb;
+  BEGIN
+    SELECT
+      CASE 
+        WHEN jsonb_typeof(potential_arr) = 'array' THEN potential_arr
+        ELSE jsonb_build_array(potential_arr)
+      END
+      INTO result;
+    RETURN result;
+  END;
+  $$ LANGUAGE 'plpgsql';
+
+
+  INSERT INTO wcc_contentful_schema_version
+    VALUES (2);
+COMMIT;

data/lib/wcc/contentful/store/query.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require_relative '../../contentful'
+require_relative './query/interface'
+
+module WCC::Contentful::Store
+  # The default query object returned by Stores that extend WCC::Contentful::Store::Base.
+  # It exposes several chainable query methods to apply query filters.
+  # Enumerating the query executes it, caching the result.
+  class Query
+    include WCC::Contentful::Store::Query::Interface
+    include Enumerable
+
+    # by default all enumerable methods delegated to the to_enum method
+    delegate(*(Enumerable.instance_methods - Module.instance_methods), to: :to_enum)
+
+    # except count, which should not iterate the lazy enumerator
+    delegate :count, to: :result_set
+
+    # Executes the query against the store and memoizes the resulting enumerable.
+    #  Subclasses can override this to provide a more efficient implementation.
+    def to_enum
+      @to_enum ||=
+        result_set.lazy.map { |row| resolve_includes(row, @options[:include]) }
+    end
+
+    attr_reader :store, :content_type, :conditions
+
+    def initialize(store, content_type:, conditions: nil, options: nil, **extra)
+      @store = store
+      @content_type = content_type
+      @conditions = conditions || []
+      @options = options || {}
+      @extra = extra
+    end
+
+    # Returns a new chained Query that has a new condition.  The new condition
+    # represents the WHERE comparison being applied here.  The underlying store
+    # implementation translates this condition statement into an appropriate
+    # query against the datastore.
+    #
+    # @example
+    #  query = query.apply_operator(:gt, :timestamp, '2019-01-01', context)
+    #  # in a SQL based store, the query now contains a condition like:
+    #  #  WHERE table.'timestamp' > '2019-01-01'
+    #
+    # @operator one of WCC::Contentful::Store::Query::Interface::OPERATORS
+    # @field The path through the fields of the content type that we are querying against.
+    #          Can be an array, symbol, or dotted-notation path specification.
+    # @expected The expected value to compare the field's value against.
+    # @context A context object optionally containing `context[:locale]`
+    def apply_operator(operator, field, expected, context = nil)
+      raise ArgumentError, "Operator #{operator} not supported" unless respond_to?(operator)
+
+      field = field.to_s if field.is_a? Symbol
+      path = field.is_a?(Array) ? field : field.split('.')
+
+      path = self.class.normalize_condition_path(path, context)
+
+      _append_condition(
+        Condition.new(path, operator, expected)
+      )
+    end
+
+    WCC::Contentful::Store::Query::Interface::OPERATORS.each do |op|
+      # @see #apply_operator
+      define_method(op) do |field, expected, context = nil|
+        apply_operator(op, field, expected, context)
+      end
+    end
+
+    # Called with a filter object by {Base#find_by} in order to apply the filter.
+    # The filter in this case is a hash where the keys are paths and the values
+    # are expectations.
+    # @see #apply_operator
+    def apply(filter, context = nil)
+      self.class.flatten_filter_hash(filter).reduce(self) do |query, cond|
+        query.apply_operator(cond[:op], cond[:path], cond[:expected], context)
+      end
+    end
+
+    # Override this to provide a result set from the Query object itself
+    # rather than from calling #execute in the store.
+    def result_set
+      @result_set ||= store.execute(self)
+    end
+
+    private
+
+    def _append_condition(condition)
+      self.class.new(
+        store,
+        content_type: content_type,
+        conditions: conditions + [condition],
+        options: @options,
+        **@extra
+      )
+    end
+
+    # naive implementation recursively descends the graph to turns links into
+    # the actual entry data.  If the result set from #execute returns a tuple,
+    # it tries to pull links from the second column in the tuple.  This allows
+    # a store implementation to return ex. `SELECT entry, includes FROM...`
+    # Otherwise, if the store does not return a tuple or does not have an includes
+    # column, it calls {Base#find} for each link and so it is very inefficient.
+    def resolve_includes(row, depth)
+      entry = row.try(:entry) || row.try(:[], 0) || row
+      includes = row.try(:includes) || row.try(:[], 1)
+      return entry unless entry && depth && depth > 0
+
+      WCC::Contentful::LinkVisitor.new(entry, :Link, :Asset,
+        # Walk all the links except for the leaf nodes
+        depth: depth - 1).map! do |val|
+        resolve_link(val, includes)
+      end
+    end
+
+    # Returns the resolved link if it exists in the includes hash, or returns
+    # the link hash.
+    def resolve_link(val, includes)
+      return val unless val.is_a?(Hash) && val.dig('sys', 'type') == 'Link'
+
+      id = val.dig('sys', 'id')
+      included =
+        if includes
+          includes[id]
+        else
+          @store.find(id)
+        end
+
+      included || val
+    end
+
+    class << self
+      def op?(key)
+        Interface::OPERATORS.include?(key.to_sym)
+      end
+
+      # Turns a hash into a flat array of individual conditions, where each
+      # element can be passed as params to apply_operator
+      def flatten_filter_hash(hash, path = [])
+        hash.flat_map do |(k, v)|
+          k = k.to_s
+          if k.include?('.')
+            k, *rest = k.split('.')
+            v = { rest.join('.') => v }
+          end
+
+          if v.is_a? Hash
+            flatten_filter_hash(v, path + [k])
+          elsif op?(k)
+            { path: path, op: k.to_sym, expected: v }
+          else
+            { path: path + [k], op: :eq, expected: v }
+          end
+        end
+      end
+
+      def known_locales
+        @known_locales = WCC::Contentful.locales.keys
+      end
+      RESERVED_NAMES = %w[fields sys].freeze
+
+      # Takes a path array in non-normal form and inserts 'sys', 'fields',
+      # and the current locale as appropriate to normalize it.
+      # rubocop:disable Metrics/BlockNesting
+      def normalize_condition_path(path, context = nil)
+        context_locale = context[:locale] if context.present?
+        context_locale ||= 'en-US'
+
+        rev_path = path.reverse
+        new_path = []
+
+        current_tuple = []
+        current_locale_was_inferred = false
+        until rev_path.empty? && current_tuple.empty?
+          raise ArgumentError, "Query too complex: #{path.join('.')}" if new_path.length > 7
+
+          case current_tuple.length
+          when 0
+            # expect a locale
+            current_tuple <<
+              if known_locales.include?(rev_path[0])
+                current_locale_was_inferred = false
+                rev_path.shift
+              else
+                # infer locale
+                current_locale_was_inferred = true
+                context_locale
+              end
+          when 1
+            # expect a path
+            current_tuple << rev_path.shift
+          when 2
+            # expect 'sys' or 'fields'
+            current_tuple <<
+              if RESERVED_NAMES.include?(rev_path[0])
+                rev_path.shift
+              else
+                # infer 'sys' or 'fields'
+                current_tuple.last == 'id' ? 'sys' : 'fields'
+              end
+
+            if current_tuple.last == 'sys' && current_locale_was_inferred
+              # remove the inferred current locale
+              current_tuple.shift
+            end
+            new_path << current_tuple
+            current_tuple = []
+          end
+        end
+
+        new_path.flat_map { |x| x }.reverse.freeze
+      end
+      # rubocop:enable Metrics/BlockNesting
+    end
+
+    Condition =
+      Struct.new(:path, :op, :expected) do
+        LINK_KEYS = %w[id type linkType].freeze
+
+        def path_tuples
+          @path_tuples ||=
+            [].tap do |arr|
+              remaining = path.dup
+              until remaining.empty?
+                locale = nil
+                link_sys = nil
+                link_field = nil
+
+                sys_or_fields = remaining.shift
+                field = remaining.shift
+                locale = remaining.shift if sys_or_fields == 'fields'
+
+                if remaining[0] == 'sys' && LINK_KEYS.include?(remaining[1])
+                  link_sys = remaining.shift
+                  link_field = remaining.shift
+                end
+
+                arr << [sys_or_fields, field, locale, link_sys, link_field].compact
+              end
+            end
+        end
+      end
+  end
+end

data/lib/wcc/contentful/store/query/interface.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class WCC::Contentful::Store::Query
+  # This module represents the common interface of queries that must be returned
+  # by a store's #find_all implementation.
+  # It is documentation ONLY and does not add functionality.
+  #
+  # This is distinct from WCC::Contentful::Store::Query, because certain helpers
+  # exposed publicly by that abstract class are not part of the actual interface
+  # and can change without a major version update.
+  module Interface
+    include Enumerable
+
+    # The set of operators that can be applied to a query.  Not all stores
+    # implement all operators.  At a bare minimum a store must implement #eq.
+    OPERATORS = %i[
+      eq
+      ne
+      all
+      in
+      nin
+      exists
+      lt
+      lte
+      gt
+      gte
+      query
+      match
+    ].freeze
+
+    WCC::Contentful::Store::Query::Interface::OPERATORS.each do |op|
+      # @see #apply_operator
+      define_method(op) do |_field, _expected, _context = nil|
+        raise NotImplementedError, "#{self.class} does not implement ##{op}"
+      end
+    end
+
+    # Applies an equality condition to the query.  The underlying store
+    # translates this into a '==' check.
+    #
+    # sig {abstract.params(
+    #    field: T.any(T::String),
+    #    expected: T.untyped,
+    #    context: T.nilable(T::Hash[T.untyped, T.untyped])
+    #  ).returns(T.self_type)}
+    def eq(_field, _expected, _context = nil)
+      raise NotImplementedError, "#{self.class} does not implement #eq"
+    end
+
+    # Called with a filter object in order to apply the filter.
+    # The filter in this case is a hash where the keys are paths and the values
+    # are expectations.
+    #
+    # sig {abstract.params(
+    #    field: T.any(T::String),
+    #    expected: T.untyped,
+    #    context: T.nilable(T::Hash[T.untyped, T.untyped])
+    #  ).returns(T.self_type)}
+    def apply(_filter, _context = nil)
+      raise NotImplementedError, "#{self.class} does not implement #apply"
+    end
+  end
+end

data/lib/wcc/contentful/store/rspec_examples.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative './rspec_examples/basic_store'
+require_relative './rspec_examples/nested_queries'
+require_relative './rspec_examples/include_param'
+
+# rubocop:disable Style/BlockDelimiters
+
+# These shared examples are included to help you implement a new store from scratch.
+# To get started implementing your store, require this file and then include the
+# shared examples in your RSpec block.
+#
+# The shared examples take a hash which describes the feature set that this store
+# implements.  All the additional features start out in the 'pending' state,
+# once you've implemented that feature in your store then you can switch them
+# to `true`.
+#
+# [:nested_queries] - This feature allows queries that reference a field on a
+#    linked object, example: `Player.find_by(team: { slug: '/dallas-cowboys' })`.
+#    This becomes essentially a JOIN.  For reference see the Postgres store.
+# [:include_param] - This feature defines how the store respects the `include: n`
+#    key in the Options hash.  Some stores can make use of this parameter to get
+#    all linked entries of an object in a single query.
+#    If your store does not respect the include parameter, then the Model layer
+#    will be calling #find a lot in order to resolve linked entries.
+#
+# @example
+#   require 'wcc/contentful/store/rspec_examples'
+#   RSpec.describe MyStore do
+#     subject { MyStore.new }
+#
+#     it_behaves_like 'contentful store', {
+#       # nested_queries: true,
+#       # include_param: true
+#     }
+#
+RSpec.shared_examples 'contentful store' do |feature_set|
+  feature_set = {
+    nested_queries: 'pending',
+    include_param: 'pending'
+  }.merge(feature_set&.symbolize_keys || {})
+
+  include_examples 'basic store'
+  include_examples 'supports nested queries', feature_set[:nested_queries]
+  include_examples 'supports include param', feature_set[:include_param]
+end
+
+# rubocop:enable Style/BlockDelimiters