pack_api 1.0.0

data/lib/pack_api/models/types/collection_result_metadata.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class CollectionResultMetadata < Dry::Struct
+    attribute :first_item, Types::Integer
+    attribute :last_item, Types::Integer
+    attribute :total_items, Types::Integer
+
+    ###
+    # Cursors for the current record set (see PackAPI::Paginator)
+    attribute? :next_page_cursor, Types::String.optional
+    attribute? :previous_page_cursor, Types::String.optional
+    attribute? :first_page_cursor, Types::String.optional
+    attribute? :last_page_cursor, Types::String.optional
+    attribute? :current_page_cursor, Types::String.optional
+    attribute? :recordset_cursor, Types::String.optional
+
+    ###
+    # A cursor representing a separate query that will always yield what the current_page_cursor produces
+    attribute? :current_page_snapshot_cursor, Types::String.optional
+
+    attribute? :sort, Types::Any.optional
+
+    def self.default
+      new(
+        first_item: 1,
+        last_item: 1,
+        total_items: 1
+      )
+    end
+
+    def self.from_paginator(paginator, sort = nil, current_page_snapshot_cursor = nil)
+      new(
+        first_item: paginator.item_range.begin,
+        last_item: paginator.item_range.end,
+        total_items: paginator.total_items,
+        next_page_cursor: paginator.next_page_cursor,
+        previous_page_cursor: paginator.previous_page_cursor,
+        current_page_cursor: paginator.current_page_cursor,
+        first_page_cursor: paginator.first_page_cursor,
+        last_page_cursor: paginator.last_page_cursor,
+        recordset_cursor: paginator.recordset_cursor,
+        sort: sort || paginator.sort,
+        current_page_snapshot_cursor:
+      )
+    end
+  end
+end

data/lib/pack_api/models/types/custom_filter_definition.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class CustomFilterDefinition < BaseType
+    attribute :name, Types::Symbol
+    attribute :type, Types::Symbol.default(:custom)
+  end
+end

data/lib/pack_api/models/types/enum_filter_definition.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class EnumFilterDefinition < BaseType
+    attribute :name, Types::Symbol
+    attribute :type, Types::Symbol.default(:enum)
+    attribute :options, Types::Array.of(FilterOption)
+    attribute :can_exclude, Types::Bool.default(false)
+  end
+end

data/lib/pack_api/models/types/filter_option.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class FilterOption < BaseType
+    attribute :label, Types::String
+    attribute :value, Types::String
+  end
+end

data/lib/pack_api/models/types/globally_identifiable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  module GloballyIdentifiable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def make_gid(model_id)
+        GlobalID.new(URI::GID.build(app: GlobalID.app, model_name: name, model_id: model_id))
+      end
+    end
+
+    included do
+      def gid
+        @gid ||= self.class.make_gid(id)
+      end
+    end
+  end
+end

data/lib/pack_api/models/types/numeric_filter_definition.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class NumericFilterDefinition < BaseType
+    attribute :name, Types::Symbol
+    attribute :type, Types::Symbol.default(:numeric)
+    attribute :operators, Types::Array.of(FilterOption)
+  end
+end

data/lib/pack_api/models/types/range_filter_definition.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class RangeFilterDefinition < BaseType
+    attribute :name, Types::Symbol
+    attribute :type, Types::Symbol.default(:range)
+    attribute :range_start_constraints, Types::Hash.schema(min: Types::Any.optional, max: Types::Any.optional).optional
+    attribute :range_end_constraints, Types::Hash.schema(min: Types::Any.optional, max: Types::Any.optional).optional
+  end
+end

data/lib/pack_api/models/types/result.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class Result < Dry::Struct
+    attribute :success, Types::Bool
+    attribute? :value, Types::Any.optional
+    attribute? :errors, Types::Hash.optional
+    attribute? :collection_metadata, CollectionResultMetadata.optional
+
+    def self.from_request_error(message, model: nil)
+      new(success: false, errors: { request: [message] }, value: model)
+    end
+
+    def self.from_collection(models:,
+                             value_object_factory:,
+                             optional_attributes: nil,
+                             paginator: nil,
+                             sort: nil,
+                             current_page_snapshot_cursor: nil)
+      value = value_object_factory.create_collection(models:, optional_attributes:)
+      if paginator.present?
+        collection_metadata = CollectionResultMetadata.from_paginator(paginator, sort, current_page_snapshot_cursor)
+      end
+
+      new(
+        success: true,
+        value:,
+        collection_metadata:
+      )
+    end
+
+    def self.from_model(model:, value_object_factory:, optional_attributes: nil)
+      if model.errors.present?
+        errors = value_object_factory.create_errors(model:)
+        errors[:request] = model.errors[:base] if model.errors[:base].present?
+        new(
+          success: false,
+          errors:
+        )
+      else
+        new(
+          success: true,
+          value: value_object_factory.create_object(model:, optional_attributes:)
+        )
+      end
+    end
+
+    def attribute_error_string(attribute)
+      return '' if errors.nil? || errors[attribute].blank?
+
+      errors[attribute]&.join(', ')
+    end
+
+    def request_error_string
+      return '' if errors.nil? || errors[:request].blank?
+
+      "#{errors[:request]&.join(', ')}."
+    end
+
+    def error_string
+      return '' if errors.nil?
+
+      one_message_per_error = errors.map do |attribute, errors|
+        "#{attribute.to_s.titleize}: #{Array.wrap(errors).join(', ')}"
+      end
+
+      one_message_per_error.join(', ')
+    end
+  end
+end

data/lib/pack_api/models/types/simple_filter_definition.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PackAPI::Types
+  class SimpleFilterDefinition < BaseType
+    attribute :name, Types::Symbol
+    attribute :type, Types::Symbol.default(:simple)
+    attribute :data_type, Types::String
+  end
+end

data/lib/pack_api/models/values_in_background_batches.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PackAPI
+  class ValuesInBackgroundBatches < ValuesInBatches
+    include Enumerable
+
+    attr_reader :low_watermark, :background_worker
+
+    def initialize(method:, batch_size:, optional_attributes: nil, **kwargs, &block)
+      super
+      @low_watermark = 1
+    end
+
+    def each
+      @background_worker = Rails.env.test? ?
+         Concurrent::ImmediateExecutor.new :
+         Concurrent::SingleThreadExecutor.new
+      super
+      background_worker.shutdown
+      @background_worker = nil
+    end
+
+    private
+
+    def process_item(index, item, block)
+      cache_next_batch if index == low_watermark
+      block.call(item)
+    end
+
+    def cache_key
+      @cache_key ||= "api:batches:#{SecureRandom.uuid}"
+    end
+
+    def cache_next_batch
+      background_worker.post do
+        Rails.application.executor.wrap do
+          Rails.logger.debug { "Storing next batch in cache #{cache_key}" }
+          Rails.cache.write(cache_key, fetch_batch(cursor: next_batch_cursor), expires_in: 1.minute)
+        end
+      end
+    end
+
+    def make_next_batch_available
+      cached_next_result = Rails.cache.read(cache_key)
+      if cached_next_result.nil?
+        Rails.logger.debug { "Fetching next batch without cache #{cache_key}" }
+        @result = fetch_batch(cursor: next_batch_cursor)
+      else
+        Rails.logger.debug { "Fetching next batch from cache #{cache_key}" }
+        @result = cached_next_result
+      end
+
+      raise PackAPI::InternalError.new(object: @result.errors) unless @result.success
+    ensure
+      Rails.cache.delete(cache_key)
+    end
+  end
+end

data/lib/pack_api/models/values_in_batches.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PackAPI
+  class ValuesInBatches
+    include Enumerable
+
+    attr_reader :method, :batch_size, :optional_attributes, :kwargs
+
+    def initialize(method:, batch_size:, optional_attributes: nil, **kwargs)
+      @method = method
+      @batch_size = batch_size
+      @optional_attributes = optional_attributes
+      @kwargs = kwargs
+    end
+
+    def each(&block)
+      make_next_batch_available
+      return if batch.empty?
+
+      loop do
+        batch.each_with_index { |item, index| process_item(index, item, block) }
+        break if next_batch_cursor.blank?
+
+        make_next_batch_available
+      end
+    end
+
+    def batch
+      @result.value
+    end
+
+    private
+
+    def process_item(_index, item, block)
+      block.call(item)
+    end
+    
+    def next_batch_cursor
+      @result&.collection_metadata&.next_page_cursor
+    end
+
+    def make_next_batch_available
+      @result = fetch_batch(cursor: next_batch_cursor)
+      raise PackAPI::InternalError.new(object: @result.errors) unless @result.success
+    end
+
+    def fetch_batch(cursor: nil)
+      method.call(**kwargs.merge(optional_attributes:, per_page: batch_size, cursor:))
+    end
+  end
+end

data/lib/pack_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PackAPI
+  VERSION = "1.0.0"
+end

data/lib/pack_api.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_record"
+require "dry-types"
+require "dry/struct"
+require "brotli"
+
+require_relative "types"
+require_relative "pack_api/version"
+require_relative "pack_api/config/dry_types_initializer"
+
+# Load in dependency order
+module PackAPI
+  autoload :InternalError, "pack_api/models/internal_error"
+  autoload :ValuesInBatches, "pack_api/models/values_in_batches"
+  autoload :ValuesInBackgroundBatches, "pack_api/models/values_in_background_batches"
+
+  module Mapping
+    autoload :AbstractTransformer, "pack_api/models/mapping/abstract_transformer"
+    autoload :AttributeHashTransformer, "pack_api/models/mapping/attribute_hash_transformer"
+    autoload :NullTransformer, "pack_api/models/mapping/null_transformer"
+    autoload :APIToModelAttributesTransformer, "pack_api/models/mapping/api_to_model_attributes_transformer"
+    autoload :ModelToAPIAttributesTransformer, "pack_api/models/mapping/model_to_api_attributes_transformer"
+    autoload :ErrorHashToAPIAttributesTransformer, "pack_api/models/mapping/error_hash_to_api_attributes_transformer"
+    autoload :NormalizedAPIAttribute, "pack_api/models/mapping/normalized_api_attribute"
+    autoload :AttributeMap, "pack_api/models/mapping/attribute_map"
+    autoload :AttributeMapRegistry, "pack_api/models/mapping/attribute_map_registry"
+    autoload :FilterMap, "pack_api/models/mapping/filter_map"
+    autoload :ValueObjectFactory, "pack_api/models/mapping/value_object_factory"
+  end
+
+  module Pagination
+    autoload :OpaqueTokenV2, "pack_api/models/pagination/opaque_token_v2"
+    autoload :PaginatorCursor, "pack_api/models/pagination/paginator_cursor"
+    autoload :Paginator, "pack_api/models/pagination/paginator"
+    autoload :PaginatorBuilder, "pack_api/models/pagination/paginator_builder"
+    autoload :SnapshotPaginator, "pack_api/models/pagination/snapshot_paginator"
+  end
+
+  module Querying
+    autoload :AbstractFilter, "pack_api/models/querying/abstract_filter"
+    autoload :AbstractBooleanFilter, "pack_api/models/querying/abstract_boolean_filter"
+    autoload :AbstractEnumFilter, "pack_api/models/querying/abstract_enum_filter"
+    autoload :AbstractNumericFilter, "pack_api/models/querying/abstract_numeric_filter"
+    autoload :AbstractRangeFilter, "pack_api/models/querying/abstract_range_filter"
+    autoload :DefaultFilter, "pack_api/models/querying/default_filter"
+    autoload :DiscoverableFilter, "pack_api/models/querying/discoverable_filter"
+    autoload :DynamicEnumFilter, "pack_api/models/querying/dynamic_enum_filter"
+    autoload :AttributeFilter, "pack_api/models/querying/attribute_filter"
+    autoload :AttributeFilterFactory, "pack_api/models/querying/attribute_filter_factory"
+    autoload :FilterFactory, "pack_api/models/querying/filter_factory"
+    autoload :ComposableQuery, "pack_api/models/querying/composable_query"
+    autoload :CollectionQuery, "pack_api/models/querying/collection_query"
+    autoload :SortHash, "pack_api/models/querying/sort_hash"
+  end
+
+  module Types
+    autoload :BaseType, "pack_api/models/types/base_type"
+    autoload :AggregateType, "pack_api/models/types/aggregate_type"
+    autoload :GloballyIdentifiable, "pack_api/models/types/globally_identifiable"
+    autoload :Result, "pack_api/models/types/result"
+    autoload :CollectionResultMetadata, "pack_api/models/types/collection_result_metadata"
+    autoload :FilterOption, "pack_api/models/types/filter_option"
+    autoload :SimpleFilterDefinition, "pack_api/models/types/simple_filter_definition"
+    autoload :BooleanFilterDefinition, "pack_api/models/types/boolean_filter_definition"
+    autoload :EnumFilterDefinition, "pack_api/models/types/enum_filter_definition"
+    autoload :NumericFilterDefinition, "pack_api/models/types/numeric_filter_definition"
+    autoload :RangeFilterDefinition, "pack_api/models/types/range_filter_definition"
+    autoload :CustomFilterDefinition, "pack_api/models/types/custom_filter_definition"
+  end
+end

data/lib/types.rb

@@ -0,0 +1,3 @@
+module Types
+  include Dry.Types()
+end

metadata

@@ -0,0 +1,276 @@
+--- !ruby/object:Gem::Specification
+name: pack_api
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Flytedesk
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: brotli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.12'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.12'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-collection_matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: |
+  Building blocks used to implement an API around a domain pack. Includes:
+  - elements for passing data out of the API
+  - elements for describing the filters supported by query endpoints in the API
+  - elements for building the mapping between domain models and API models
+  - elements for building the query endpoints themselves, based on user inputs (sort, filter, pagination)
+  - elements for retrieving multiple pages of data from other query endpoints
+email:
+- dev@flytedesk.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/pack_api.rb
+- lib/pack_api/config/dry_types_initializer.rb
+- lib/pack_api/models/internal_error.rb
+- lib/pack_api/models/mapping/abstract_transformer.rb
+- lib/pack_api/models/mapping/api_to_model_attributes_transformer.rb
+- lib/pack_api/models/mapping/attribute_hash_transformer.rb
+- lib/pack_api/models/mapping/attribute_map.rb
+- lib/pack_api/models/mapping/attribute_map_registry.rb
+- lib/pack_api/models/mapping/error_hash_to_api_attributes_transformer.rb
+- lib/pack_api/models/mapping/filter_map.rb
+- lib/pack_api/models/mapping/model_to_api_attributes_transformer.rb
+- lib/pack_api/models/mapping/normalized_api_attribute.rb
+- lib/pack_api/models/mapping/null_transformer.rb
+- lib/pack_api/models/mapping/value_object_factory.rb
+- lib/pack_api/models/pagination/opaque_token_v2.rb
+- lib/pack_api/models/pagination/paginator.rb
+- lib/pack_api/models/pagination/paginator_builder.rb
+- lib/pack_api/models/pagination/paginator_cursor.rb
+- lib/pack_api/models/pagination/snapshot_paginator.rb
+- lib/pack_api/models/querying/abstract_boolean_filter.rb
+- lib/pack_api/models/querying/abstract_enum_filter.rb
+- lib/pack_api/models/querying/abstract_filter.rb
+- lib/pack_api/models/querying/abstract_numeric_filter.rb
+- lib/pack_api/models/querying/abstract_range_filter.rb
+- lib/pack_api/models/querying/attribute_filter.rb
+- lib/pack_api/models/querying/attribute_filter_factory.rb
+- lib/pack_api/models/querying/collection_query.rb
+- lib/pack_api/models/querying/composable_query.rb
+- lib/pack_api/models/querying/default_filter.rb
+- lib/pack_api/models/querying/discoverable_filter.rb
+- lib/pack_api/models/querying/dynamic_enum_filter.rb
+- lib/pack_api/models/querying/filter_factory.rb
+- lib/pack_api/models/querying/sort_hash.rb
+- lib/pack_api/models/types/aggregate_type.rb
+- lib/pack_api/models/types/base_type.rb
+- lib/pack_api/models/types/boolean_filter_definition.rb
+- lib/pack_api/models/types/collection_result_metadata.rb
+- lib/pack_api/models/types/custom_filter_definition.rb
+- lib/pack_api/models/types/enum_filter_definition.rb
+- lib/pack_api/models/types/filter_option.rb
+- lib/pack_api/models/types/globally_identifiable.rb
+- lib/pack_api/models/types/numeric_filter_definition.rb
+- lib/pack_api/models/types/range_filter_definition.rb
+- lib/pack_api/models/types/result.rb
+- lib/pack_api/models/types/simple_filter_definition.rb
+- lib/pack_api/models/values_in_background_batches.rb
+- lib/pack_api/models/values_in_batches.rb
+- lib/pack_api/version.rb
+- lib/types.rb
+homepage: https://github.com/flytedesk/pack_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/flytedesk/pack_api
+  changelog_uri: https://github.com/flytedesk/pack_api/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Building blocks for implementing APIs around domain models
+test_files: []