has_helpers 5.0.2

data/lib/has_helpers/attributes.rb

@@ -0,0 +1,196 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers::Attributes
+  def self.included(klass)
+    klass.include(Initializer)
+    klass.include(AttributeAssignment)
+    klass.include(GuardedAttributes)
+  end
+
+  # GuardedAttributes provides--and combines!--shortcuts for many common patterns of accessor methods.
+  #
+  # Take for example this +service+ accessor. There is a normal writer method which lets the user
+  # optionally set +service+. The reader method should always return either +nil+ or a +Service+
+  # object, which is ensured by calling +to_service+, the "guard" method.
+  #
+  #   attr_writer :service
+  #   def service
+  #     @service && @service.to_service
+  #   end
+  #
+  # +guarded_attr_accessor+ does all that in one line. +guarded_attr_accessor+ is smart and will convert
+  # the object passed in as the guard to a +Proc+, so you may simply pass in a symbol. There is also an
+  # +auto_guard+ option which will generate the +Proc+ based on the attribute name. The following lines
+  # are all equivalent:
+  #
+  #   guarded_attr_accessor :service, guard: -> value { value.to_service }
+  #   guarded_attr_accessor :service, guard: :to_service
+  #   guarded_attr_accessor :service, auto_guard: true
+  #
+  # +auto_guard+ is most convenient when defining multiple attributes.
+  #
+  #   guarded_attr_accessor :service, :icon, :action, auto_guard: true
+  #
+  # The previous example is equivalent to:
+  #
+  #   guarded_attr_accessor :service, guard: :to_service
+  #   guarded_attr_accessor :icon, guard: :to_icon
+  #   guarded_attr_accessor :action, guard: :to_action
+  module GuardedAttributes
+    def self.included(klass)
+      klass.extend(ClassMethods)
+      klass.include(InstanceMethods)
+      klass.class_eval do
+        ClassMethods.instance_methods.each do |method_name|
+          private_class_method method_name
+        end
+      end
+    end
+
+    module ClassMethods
+      # Use this like you would use `attr_accessor`. The writer method is the same as
+      # the standard Ruby `attr_writer`, but the reader method will be generated using
+      # `guarded_attr_reader` (see that method for details.)
+      def guarded_attr_accessor(*args, guard: nil, memoize: true, guard_nil: nil, auto_guard: false, collection: false, &block)
+        attr_writer(*args)
+        guarded_attr_reader(*args, guard: guard, memoize: memoize, guard_nil: guard_nil, auto_guard: auto_guard, collection: collection, &block)
+      end
+
+      # `guarded_attr_reader` is intended to be used in place of Ruby's standard `attr_reader`.
+      # However, this provides memoization by default and the option to provide a guard Proc
+      # which will always be run against the value.
+      #
+      # The return value (prior to running the guard proc) is the result of the given block or
+      # the instance variable which matches the accessor name (e.g. The ivar @x for `guard_attr_reader :x`).
+      #
+      # === Options
+      # +guard+:
+      # This may be set to either a Proc object or an object which is convertible to a Proc
+      # through #to_proc. The determined value (returned from the block, or fetched from the
+      # matching instance variable) will be passed into the Proc. This happens prior to
+      # memoization, if enabled.
+      #
+      # +memoize+:
+      # This is enabled by default, but it may be disabled by setting this option to +false+.
+      # Note that memoization happens _after_ execution of both the block and the guard proc,
+      # if either or both of those are given.
+      #
+      # +guard_nil+:
+      # When set to true, the guard Proc will be executed even when the argument value is nil.
+      # This is false by default.
+      #
+      # +auto_guard+:
+      # This will automatically generate a guard +Proc+ using a symbol `:to_attr`, based on the
+      # name of the attribute. It is a shorthand for setting the guard explicitly for each attribute.
+      #
+      # This example:
+      #
+      #   guarded_attr_accessor :service, :icon, :action, auto_guard: true
+      #
+      # is equivalent to this:
+      #
+      #   guarded_attr_accessor :service, guard: :to_service
+      #   guarded_attr_accessor :icon, guard: :to_icon
+      #   guarded_attr_accessor :action, guard: :to_action
+      #
+      # === Examples
+      #   class Foo
+      #     include ::HasHelpers::Attributes
+      #     guarded_attr_accessor :bar
+      #     guarded_attr_accessor :bar_with_block do
+      #       "Already set to: #{ @bar_with_block }"
+      #     end
+      #     guarded_attr_accessor :bar_with_guard, guard: -> value { value.upcase }
+      #     guarded_attr_accessor :bar_with_symbol_as_guard, guard: :to_i
+      #     guarded_attr_accessor :bar_with_block_and_guard, guard: -> value { value.downcase } do
+      #       "I cOmE fRoM cLaSs #{ self.class.name }"
+      #     end
+      #   end
+      #
+      #   foo = Foo.new
+      #   foo.bar                                  # => nil
+      #   foo.bar = 42
+      #   foo.bar                                  # => 42
+      #   foo.bar_with_block = "Derp"
+      #   foo.bar_with_block                       # => "Already set to: Derp"
+      #   foo.bar_with_guard = "hello"
+      #   foo.bar_with_guard                       # => "HELLO"
+      #   foo.bar_with_symbol_as_guard = "123.45"
+      #   foo.bar_with_symbol_as_guard             # => 123
+      #   foo.bar_with_block_and_guard             # => "i come from class c"
+      #
+      # Using +guard+
+      #   class Foo
+      #     include ::HasHelpers::Attributes
+      #     guarded_attr_accessor :action, guard: :to_action
+      #   end
+      #
+      #   foo = Foo.new
+      #   foo.action                         # => nil
+      #   foo.action = { :name => "Find" }
+      #   foo.action                         # => #<Action @name="Find">
+      def guarded_attr_reader(*args, guard: nil, memoize: true, guard_nil: nil, auto_guard: false, collection: false, &block)
+        args.each do |attr|
+          ivar_memo = "@#{ attr }_memoized"
+          ivar_memo_indicator = "@#{ attr }_memoized_indicator" # Use to indicate whether memoization has already happened.
+          guard_object = guard || (auto_guard && "to_#{ attr.to_s.singularize }".to_sym)
+          define_method(attr) do |*attr_args|
+            if memoize
+              if instance_variable_get(ivar_memo_indicator)
+                instance_variable_get(ivar_memo)
+              else
+                instance_variable_set(ivar_memo_indicator, true)
+                instance_variable_set(ivar_memo, exec_guard(guard_object, value_for(attr, attr_args, collection, block), guard_nil: guard_nil, collection: collection))
+              end
+            else
+              exec_guard(guard_object, value_for(attr, attr_args, collection, block), guard_nil: guard_nil, collection: collection)
+            end
+          end
+        end
+      end
+
+      def guarded_collection(*args, guard: nil, memoize: true, guard_nil: nil, auto_guard: false, &block)
+        guarded_attr_accessor(*args, guard: guard, memoize: memoize, guard_nil: guard_nil, auto_guard: auto_guard, collection: true, &block)
+      end
+    end
+
+    module InstanceMethods
+      private
+
+      def exec_guard(guard, value, guard_nil: nil, collection: false)
+        if guard && (!value.nil? || guard_nil)
+          if collection
+            value.map { |element| instance_exec(element, &guard.to_proc) }
+          else
+            instance_exec(value, &guard.to_proc)
+          end
+        else
+          value
+        end
+      end
+
+      # When <tt>collection</tt> is set to +true+ then instead of nil this method will return an empty +Array+.
+      def value_for(attr, args, collection, block)
+        # TODO: add a way for the collection to support Hash in addition to Array. *
+        (block ? instance_exec(*args, &block) : instance_variable_get("@#{ attr }")) || (collection ? [] : nil)
+      end
+    end
+  end
+
+  module Initializer
+    def initialize(*args)
+      attrs = args.last.is_a?(Hash) ? args.pop : {}
+      raise ArgumentError, "Unknown arguments #{ args.map(&:inspect).join(", ") }" if args.any?
+      assign_attributes(attrs)
+    end
+  end
+
+  module AttributeAssignment
+    def assign_attributes(attrs = {})
+      attrs.each do |attr, value|
+        send("#{attr}=", value)
+      end
+    end
+  end
+end

data/lib/has_helpers/aws.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Aws
+    # Gets the environment variable whose name is passed in, but aborts the app
+    # with an error message if the value is nil (i.e. the variable wasn't set).
+    # Intended for "internal" use to set up the various OpenStructs defined here.
+    def self._get_existing_env!(env_var_name, default_value = nil)
+      value = ENV[env_var_name] || default_value
+      unless value.present? || ::HasUtils::Env.test?
+        # rubocop:disable Rails/Exit
+        abort "Environment variable #{env_var_name} must be defined. " \
+                "See README for details on required environment variables."
+        # rubocop:enable Rails/Exit
+      end
+      value
+    end
+
+    ##### CONF OBJECTS #####
+
+    # The fallback credentials are for the dev_api_access AWS user, who should
+    # only have access to dev and test AWS resources.
+    def self.credentials_conf
+      @credentials_conf ||= OpenStruct.new(
+        access_key_id: _get_existing_env!("AWS_ACCESS_KEY_ID"),
+        secret_access_key: _get_existing_env!("AWS_SECRET_ACCESS_KEY")
+      )
+    end
+
+    def self.s3_conf
+      @s3_conf ||= OpenStruct.new(
+        bucket: _get_existing_env!("AWS_S3_BUCKET", "#{::HasHelpers::Application.project}-#{::HasUtils::Env.current_environment}"),
+        region: _get_existing_env!("AWS_S3_REGION", "us-east-1")
+      )
+    end
+
+    def self.sqs_conf
+      @sqs_conf ||= OpenStruct.new(
+        region: _get_existing_env!("AWS_SQS_REGION", "us-east-1")
+      )
+    end
+
+    ##### HELPER METHODS #####
+
+    # Returns a new AWS S3 client for v1 or v2, and handles credentials in
+    # an environment-appropriate manner. (See #new_aws_client for details.)
+    def self.new_s3_client(region: s3_conf.region, credentials_conf: self.credentials_conf)
+      new_aws_client(::Aws::S3::Client, region: region, credentials_conf: credentials_conf)
+    end
+
+    # Returns a new AWS SQS client for v1 or v2, and handles credentials in
+    # an environment-appropriate manner. (See #new_aws_client for details.)
+    def self.new_sqs_client(region: sqs_conf.region, credentials_conf: self.credentials_conf)
+      new_aws_client(::Aws::SQS::Client, region: region, credentials_conf: credentials_conf)
+    end
+
+    # Returns a new AWS client of the given client_class, getting credentials
+    # from the credentials_conf passed in.
+    def self.new_aws_client(client_class, region:, credentials_conf:)
+      client_class.new(
+        region: region,
+        access_key_id: credentials_conf.access_key_id,
+        secret_access_key: credentials_conf.secret_access_key
+      )
+    end
+  end
+end

data/lib/has_helpers/cards/cache.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "json"
+
+module HasHelpers
+  module Cards
+    class Cache
+      DEFAULT_NAMESPACE = "hh:cards:v1"
+
+      def initialize(redis:, namespace: DEFAULT_NAMESPACE)
+        @redis = redis
+        @namespace = namespace
+      end
+
+      def fetch(key, ttl:, stale_grace:, force: false)
+        fresh = redis.get(cache_key(key)) unless force
+        return JSON.parse(fresh) if fresh.present?
+
+        value = yield
+        encoded = JSON.dump(value)
+        redis.set(cache_key(key), encoded, ex: ttl.to_i)
+        redis.set(stale_key(key), encoded, ex: ttl.to_i + stale_grace.to_i)
+        value
+      rescue StandardError => e
+        stale = redis.get(stale_key(key))
+        raise if stale.blank?
+
+        logger&.warn("HasHelpers::Cards::Cache returning stale value for #{key}: #{e.class}: #{e.message}")
+        JSON.parse(stale)
+      end
+
+      private
+
+      attr_reader :redis
+
+      def cache_key(key)
+        "#{@namespace}:#{key}"
+      end
+
+      def stale_key(key)
+        "#{cache_key(key)}:stale"
+      end
+
+      def logger
+        Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
+      end
+    end
+  end
+end

data/lib/has_helpers/cards/config.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    class Config
+      MODES = %i[server client].freeze
+
+      attr_accessor :mode,
+                    :issuer,
+                    :audience,
+                    :base_url,
+                    :redis,
+                    :path,
+                    :cache_ttl,
+                    :cache_stale_grace
+
+      def initialize
+        @path = "/internal_graphql"
+        @cache_ttl = 5.minutes
+        @cache_stale_grace = 1.hour
+      end
+
+      def validate!
+        self.mode = mode&.to_sym
+        raise ConfigurationError, "mode is required" if mode.blank?
+        raise ConfigurationError, "mode must be :server or :client" unless MODES.include?(mode)
+        raise ConfigurationError, "issuer is required" if issuer.blank?
+
+        validate_client! if mode == :client
+        self
+      end
+
+      private
+
+      def validate_client!
+        raise ConfigurationError, "audience is required" if audience.blank?
+        raise ConfigurationError, "base_url is required" if base_url.blank?
+        raise ConfigurationError, "redis is required" if redis.blank?
+      end
+    end
+  end
+end

data/lib/has_helpers/cards/remote_role.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    RemoteRole = Struct.new(:id, :name, :organization_id, keyword_init: true) do
+      delegate :hash, to: :id
+
+      def persisted?
+        true
+      end
+
+      def ==(other)
+        other.is_a?(RemoteRole) && other.id == id
+      end
+
+      alias eql? ==
+
+      def to_h
+        {
+          id: id,
+          name: name,
+          organization_id: organization_id
+        }
+      end
+    end
+  end
+end

data/lib/has_helpers/cards/remote_roles.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    class RemoteRoles
+      CAPABILITY = "roles:read"
+
+      GET_ROLE = <<~GQL
+        query Role($id: ID!) { role(id: $id) { id name organizationId } }
+      GQL
+
+      LIST_ROLES = <<~GQL
+        query Roles($organizationId: ID) { roles(organizationId: $organizationId) { id name organizationId } }
+      GQL
+
+      def initialize(config: HasHelpers::Cards.config, cache: nil, client: nil)
+        @config = config
+        @cache = cache || Cache.new(redis: config.redis)
+        @client = client || HasHelpers::ServiceTrust::GraphQLClient.new(
+          audience: config.audience,
+          base_url: config.base_url,
+          path: config.path
+        )
+      end
+
+      def find(id, force: false)
+        payload = cache.fetch("role:#{id}", ttl: config.cache_ttl, stale_grace: config.cache_stale_grace, force: force) do
+          result = client.query(GET_ROLE, variables: { id: id }, capability: CAPABILITY)
+          raise FetchError, error_message(result, "role #{id}") unless result.success?
+          raise NotFoundError, id unless result.data && result.data["role"]
+
+          result.data["role"]
+        end
+        build(payload)
+      end
+
+      def all(force: false, organization_id: nil)
+        cache_key = organization_id.present? ? "roles:all:org=#{organization_id}" : "roles:all"
+        payload = cache.fetch(cache_key, ttl: config.cache_ttl, stale_grace: config.cache_stale_grace, force: force) do
+          variables = organization_id.present? ? { organizationId: organization_id } : {}
+          result = client.query(LIST_ROLES, variables: variables, capability: CAPABILITY)
+          raise FetchError, error_message(result, "roles list") unless result.success? && result.data
+
+          result.data["roles"] || []
+        end
+        payload.map { |hash| build(hash) }
+      end
+
+      def where(ids: nil, force: false, organization_id: nil)
+        results = all(force: force, organization_id: organization_id)
+        return results if ids.nil?
+
+        requested = ids.map(&:to_s)
+        results.select { |role| requested.include?(role.id.to_s) }
+      end
+
+      private
+
+      attr_reader :config, :cache, :client
+
+      def build(hash)
+        RemoteRole.new(
+          id: hash.fetch("id"),
+          name: hash.fetch("name"),
+          organization_id: hash["organizationId"] || hash["organization_id"]
+        )
+      end
+
+      def error_message(result, fallback)
+        messages = Array(result.errors).filter_map { |error| error["message"] || error[:message] }
+        messages.present? ? messages.join("; ") : fallback
+      end
+    end
+  end
+end

data/lib/has_helpers/cards/roles.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    module Roles
+      module_function
+
+      def find(id, **opts)
+        return nil if id.blank?
+
+        case HasHelpers::Cards.config.mode
+        when :server
+          ::HasHelpers::Role.find_by(id: id)
+        when :client
+          remote.find(id, **opts)
+        end
+      end
+
+      def all(organization_id: nil, **opts)
+        case HasHelpers::Cards.config.mode
+        when :server
+          scope = ::HasHelpers::Role.all
+          scope = scope.where(organization_id: organization_id) if organization_id.present?
+          scope.to_a
+        when :client
+          remote.all(organization_id: organization_id, **opts)
+        end
+      end
+
+      def where(ids: nil, organization_id: nil, **opts)
+        case HasHelpers::Cards.config.mode
+        when :server
+          scope = ::HasHelpers::Role.all
+          scope = scope.where(id: ids) if ids
+          scope = scope.where(organization_id: organization_id) if organization_id.present?
+          scope.to_a
+        when :client
+          remote.where(ids: ids, organization_id: organization_id, **opts)
+        end
+      end
+
+      def remote
+        @remote ||= RemoteRoles.new
+      end
+
+      def remote=(remote)
+        @remote = remote
+      end
+
+      def reset!
+        @remote = nil
+      end
+    end
+  end
+end

data/lib/has_helpers/cards.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "has_helpers/cards/config"
+require "has_helpers/cards/cache"
+require "has_helpers/cards/remote_role"
+require "has_helpers/cards/remote_roles"
+require "has_helpers/cards/roles"
+
+module HasHelpers
+  module Cards
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+    class NotFoundError < Error; end
+    class FetchError < Error; end
+
+    class << self
+      def configure
+        config = Config.new
+        yield config
+        config.validate!
+        @config = config
+      end
+
+      def config
+        @config || raise(ConfigurationError, "HasHelpers::Cards.configure must be called before use")
+      end
+
+      def reset!
+        @config = nil
+        Roles.reset! if defined?(Roles)
+      end
+    end
+  end
+end

data/lib/has_helpers/concerns/hydrate_concern.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module HasHelpers
+  module Concerns
+    module HydrateConcern
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_hydrate_fields, instance_writer: false, default: {}
+        after_initialize  { run_hydrations(:initialize) }
+        before_validation { run_hydrations(:validation) }
+        before_save       { run_hydrations(:save) }
+        before_update     { run_hydrations(:update) }
+      end
+
+      class_methods do
+        def hydrates(field, block, on: nil, sets: nil)
+          self._hydrate_fields = _hydrate_fields.merge(field => { block: block, on: on, sets: sets })
+        end
+
+        def hydrated_fields
+          _hydrate_fields.flat_map do |name, config|
+            config[:sets].presence || [name]
+          end
+        end
+      end
+
+      def hydrate(**kwargs)
+        @_hydrated_fields = []
+        self.class._hydrate_fields.each do |field, config|
+          run_hydration(field, config[:block], **kwargs) unless [:validation, :save, :update].include?(config[:on])
+        end
+        self
+      end
+
+      def hydrated_fields
+        @_hydrated_fields || []
+      end
+
+      private
+
+      def run_hydrations(timing, **kwargs)
+        self.class._hydrate_fields.each do |field, config|
+          should_run = case timing
+                       when :validation then ![:save, :update, :explicit].include?(config[:on])
+                       when :initialize then config[:on] == :initialize
+                       when :save       then config[:on] == :save
+                       when :update     then config[:on] == :update
+          end
+          run_hydration(field, config[:block], **kwargs) if should_run
+        end
+      end
+
+      def run_hydration(field, block, **kwargs)
+        attr_snapshot = changes.dup
+        dispatch_block(block, **kwargs)
+        @_hydrated_fields ||= []
+        @_hydrated_fields << field if changes != attr_snapshot
+      end
+
+      def dispatch_block(block, **kwargs)
+        return instance_exec(&block) if kwargs.empty?
+
+        params = block.parameters
+        if params.any? { |type, _| type == :keyrest }
+          instance_exec(**kwargs, &block)
+        else
+          accepted = params.select { |type, _| [:key, :keyreq].include?(type) }.map { |_, name| name }
+          accepted.any? ? instance_exec(**kwargs.slice(*accepted), &block) : instance_exec(&block)
+        end
+      end
+    end
+  end
+end

data/lib/has_helpers/concerns/importable_accessors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Concerns
+    module ImportableAccessors
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_importable_accessors, instance_writer: false, default: []
+      end
+
+      class_methods do
+        def importable_accessors(*names)
+          if names.any?
+            names = names.flatten.map(&:to_sym)
+            self._importable_accessors = (_importable_accessors + names).uniq
+            attr_accessor(*names)
+          end
+
+          _importable_accessors
+        end
+      end
+    end
+  end
+end