yes-read-api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d731425b16d1120ca5bfd9d17e660f4b4c458e72e453379083747ebc63a4bf6
+  data.tar.gz: bec6d4e104ec6a00c9ca6cf1b88da37495883d0fa5d2062067f1793ce0bfd7e9
+SHA512:
+  metadata.gz: 34dd0f0016acaba53fcb2ac80e00fa6f68b116d9a930eeb2ec5ddbe3f23966b3569605379ed21140f47745cb0a513bc9bc4f7530c33ac3e4c20aae944a804c4c
+  data.tar.gz: 326cf251bdb5634a9f5bded5b6441abf14ca0054c19a543b97164eaad246481979833670c75eff0a4fa3259eeac52d1070a32f3404567fc42e89eb8e11e56e4b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2023 Arek Swidrak
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,159 @@
+# Yes Read API
+
+This gem implements an endpoint to query read models.
+
+## Installation
+
+Add a gem to your Gemfile
+
+```ruby
+gem 'yes-read-api'
+```
+
+and run `bundle install`
+
+## Usage
+
+See the [root README](../README.md) for the full DSL documentation and aggregate definition.
+
+There are a few steps you need to do in order to integrate this gem. In the examples below we assume you have an `Apprenticeship` read model class. The module structure is strict.
+
+- Mount gem's endpoint to use it. Example(in `routes.rb`):
+
+```ruby
+Rails.application.routes.draw do
+  mount Yes::Read::Api::Engine => '/queries'
+end
+```
+
+- Define a set of registered models. You can do it as follows (in `application.rb`)
+
+```ruby
+config.yes_read_api.read_models = ['apprenticeships']
+```
+
+- Define an authorizer for your read model's request:
+
+```ruby
+module ReadModels
+  module Apprenticeship
+    class RequestAuthorizer < Yes::Core::ReadModel::RequestAuthorizer
+      def self.call(params, auth_data)
+        auth_data['scopes'].include?('admin')
+      end
+    end
+  end
+end
+```
+
+- Define a filter class for your read model. You can declare various ActiveRecord filters which can be applied to your collection based on request params. Assuming you have a `by_id` scope in your `Apprenticeship` model:
+
+```ruby
+module ReadModels
+  module Apprenticeship
+    class Filter < Yes::Core::ReadModel::Filter
+      has_scope :ids do |controller, scope, value|
+        scope.by_id(value.split(','))
+      end
+
+      private
+
+      def read_model_class
+        ::Apprenticeship
+      end
+    end
+  end
+end
+```
+
+- _Optional._ Define an authorizer for your read model. You can inherit from `Yes::Core::ReadModelAuthorizer` or define your own base class:
+
+```ruby
+module ReadModels
+  module Apprenticeship
+    class Authorizer < ReadModels::Authorizer
+      class << self
+        def call(record, auth_data)
+          raise ReadModels::Authorizer::NotAuthorized, 'You need to be a company admin' unless company_admin?(auth_data)
+
+          true
+        end
+      end
+    end
+  end
+end
+```
+
+Now you can query your read model via `GET /queries/apprenticeships` request.
+
+### Pagination
+Read responses are always paginated. You can supply pagination parameter in case you want to change the default
+
+| Name                | Default |
+|---------------------|---------|
+| page[number]        |    1    |
+| page[size]          |    20   |
+| page[include_total] |  false  |
+
+The read response includes pagination information in the following headers
+
+| Name       | Description                                                                                                      |
+|------------|------------------------------------------------------------------------------------------------------------------|
+| X-Page     |                                                    page number                                                   |
+| X-Per-Page |                                                     page size                                                    |
+| X-Total    | Total number of items.  By default not included(null) If you need a total number set `page[include_total]` to `true` |
+
+By default pagination is using `countless_minimal` mode.
+The `X-Total` header is not returned in the response. Count query is not produced to DB.
+
+You can change this behavior per each request by adding `page[include_total]=true` params to the request query.
+
+If you wish to change the default behavior globally, so `X-Total` header is returned for the every request response by default, you can set globally `Pagy::DEFAULT[:countless_minimal] = false` or example in the `pagy_initializer.rb`. In this case `page[include_total]` param is ignored.
+
+More you can read here: [Pagy Countless](https://ddnexus.github.io/pagy/docs/extras/countless/)
+
+
+
+## Development
+
+### Prerequisites
+
+- Docker and Docker Compose
+- Ruby >= 3.2.0
+- Bundler
+
+### Setup
+
+Start PostgreSQL from the **repository root**:
+
+```shell
+docker compose up -d
+```
+
+Install dependencies:
+
+```shell
+bundle install
+```
+
+Set up the test database:
+
+```shell
+RAILS_ENV=test bundle exec rake db:create db:migrate
+```
+
+The `.env` file at `spec/dummy/.env` is loaded automatically and contains JWT test keys and database configuration.
+
+### Running Specs
+
+```shell
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yousty/yes.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'dotenv'
+
+Dotenv.load('spec/.env')
+
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/controllers/yes/read/api/application_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yes
+  module Read
+    module Api
+      class ApplicationController < ActionController::API
+        before_action :set_locale
+
+        def set_locale
+          I18n.locale = params[:locale] || I18n.default_locale
+        end
+
+        def append_info_to_payload(payload)
+          super
+          payload[:request_id] = request.uuid
+          payload[:request_headers] = request.env.select do |k, _v|
+            k.match(/\A(HTTP.*|CONTENT.*|REMOTE.*|REQUEST.*|AUTHORIZATION.*|SCRIPT.*|SERVER.*)/)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/yes/read/api/queries_controller.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'yes/read/api/advanced_filter_validator'
+
+module Yes
+  module Read
+    module Api
+      class QueriesController < ApplicationController
+        before_action :authenticate_with_token
+        before_action :validate_advanced_payload, only: :advanced
+        before_action :process_own_filter, only: :call
+
+        rescue_from(Yes::Core::AuthenticationError, with: :auth_error_response)
+
+        rescue_from(
+          Yes::Core::Authorization::ReadModelsAuthorizer::NotAuthorized,
+          Yes::Core::Authorization::ReadRequestAuthorizer::NotAuthorized,
+          with: :read_models_unauthorized_response
+        )
+
+        def call
+          persisted_filter = filter(read_model_name).persisted_filter_scope.find_by(id: params[:filter_id]) if params[:filter_id].present?
+
+          render json: response_json(persisted_filter:, filter_type: persisted_filter ? :advanced : :basic).to_json
+        end
+
+        def advanced
+          render json: response_json(filter_type: :advanced).to_json
+        end
+
+        private
+
+        def process_own_filter
+          return if params.dig(:filters, :own).blank?
+          return unless defined?(::IdentityUser)
+
+          identity_user = ::IdentityUser.find_by(id: auth_data[:identity_id])
+          return if identity_user.blank?
+          return unless identity_user.respond_to?("own_#{read_model_name.singularize}_ids")
+
+          owned_ids = identity_user.send("own_#{read_model_name.singularize}_ids")
+          params[:filters][:ids] = owned_ids.presence&.join(',') || 'none'
+        end
+
+        def response_json(filter_type: :basic, persisted_filter: nil)
+          filter_options = persisted_filter&.body&.deep_symbolize_keys&.merge(model: params[:model]) || params
+
+          request_authorizer.call(filter_options, auth_data)
+
+          filter_options[:filters] ||= {}
+          records = filter(read_model_name).new(filter_options, type: filter_type).call
+          paginated_records = paginate(records, filter_options[:page] || {})
+
+          Yes::Core::Authorization::ReadModelsAuthorizer.call(read_model_name, paginated_records, auth_data)
+
+          serialize(paginated_records, filter_options)
+        end
+
+        def request_authorizer
+          authorizer_class = "ReadModels::#{read_model_name.classify}::RequestAuthorizer"
+          Kernel.const_get(authorizer_class)
+        rescue NameError
+          raise Yes::Core::Authorization::ReadRequestAuthorizer::NotAuthorized, 'Not allowed'
+        end
+
+        def read_model_name
+          params[:model].underscore
+        end
+
+        def filter(read_model_name)
+          filter_class = "ReadModels::#{read_model_name.classify}::Filter"
+          Kernel.const_get(filter_class)
+        rescue NameError
+          Yes::Core::ReadModel::Filter
+        end
+
+        def serialize(records, filter_options)
+          options = {
+            params: filter_options,
+            include: filter_options[:include]&.split(',')&.map(&:to_sym),
+            auth_data:
+          }.compact
+
+          serializer.new(records, options)
+        end
+
+        def serializer
+          serializer_class = "ReadModels::#{read_model_name.classify}::Serializers::#{read_model_name.classify}"
+          Kernel.const_get(serializer_class)
+        end
+
+        def params
+          @params ||= request.parameters.deep_symbolize_keys
+        end
+
+        def authenticate_with_token
+          adapter = Yes::Core.configuration.auth_adapter
+          raise Yes::Core::AuthenticationError, 'No auth adapter configured' if adapter.nil?
+
+          @auth_data = adapter.authenticate(request)
+        end
+
+        attr_reader :auth_data
+
+        def auth_error_response(error)
+          render(
+            json: { title: 'Auth Token Invalid', detail: error.message }.to_json,
+            status: :unauthorized
+          )
+        end
+
+        def read_models_unauthorized_response(error)
+          render(
+            json: { title: 'Unauthorized', detail: error.message }.to_json,
+            status: :unauthorized
+          )
+        end
+
+        def validate_advanced_payload
+          return if params[:filter_definition].blank?
+
+          validation_result = Yes::Read::Api::AdvancedFilterValidator.call(params)
+          return if validation_result.success?
+
+          render(
+            json: { title: 'Invalid Payload', detail: validation_result.errors.to_h }.to_json,
+            status: :unprocessable_content
+          )
+        end
+      end
+    end
+  end
+end

data/config/initializers/api_pagination.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+ApiPagination.configure do |config|
+  # If you have more than one gem included, you can choose a paginator.
+  config.paginator = :pagy # or :will_paginate
+
+  # By default, this is set to 'Total'
+  config.total_header = 'X-Total'
+
+  # By default, this is set to 'Per-Page'
+  config.per_page_header = 'X-Per-Page'
+
+  # Optional: set this to add a header with the current page number.
+  config.page_header = 'X-Page'
+
+  # Optional: set this to add other response format. Useful with tools that define :jsonapi format
+  config.response_formats = %i[json xml jsonapi]
+
+  config.page_param do |params|
+    params.dig(:page, :number)
+  end
+
+  config.per_page_param do |params|
+    params.dig(:page, :size)
+  end
+
+  # Optional: Include the total and last_page link header
+  # By default, this is set to true
+  # Note: When using kaminari, this prevents the count call to the database
+  config.include_total = true
+end
+
+Pagy::DEFAULT[:max_per_page] = 100
+Pagy::DEFAULT[:countless_minimal] = true

data/config/routes.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Instantiates an ActionDispatch::Request from the env.
+# Extracts controller and action.
+# Decides whether to:
+# Just call the controller if no tracer is configured.
+# Otherwise, start or enrich an OpenTelemetry span with authentication and request data.
+# Returns the controller’s response (controller.action(action).call(env)).
+# It’s being used as a route handler directly in Rails routes:
+# get '/:model', to: OtlTrackableRequest.new
+# post '/:model', to: OtlTrackableRequest.new
+#
+
+require 'yes/core'
+
+module Yes
+  module Read
+    module Api
+      class OtlTrackableRequest
+        attr_accessor :action_name, :controller_class
+
+        def initialize(action_name:, controller_class: Yes::Read::Api::QueriesController)
+          @action_name = action_name
+          @controller_class = controller_class
+        end
+
+        def call(env)
+          tracer = Yes::Core.configuration.otl_tracer
+          request = ActionDispatch::Request.new(env)
+
+          self.controller_class ||= request.controller_class
+          self.action_name ||= request.params[:action] || :index
+
+          return controller_class.action(action_name).call(env) if tracer.nil?
+
+          otl_request_data = request.get? || request.delete? ? get_otl_auth_data(request, env) : otl_auth_data(request, env)
+
+          tracer.in_span("Request #{controller_class.name}", kind: :client) do |request_span|
+            request_span.add_attributes(otl_request_data)
+
+            return controller_class.action(action_name).call(env)
+          end
+        end
+
+        private
+
+        def otl_auth_data(request, env)
+          request.body.rewind
+          params = request.body.read
+          request.body.rewind # restore the cursor to the beginning able read again body
+
+          auth_token = env['HTTP_AUTHORIZATION'] || ''
+          auth_data =  auth_token.present? ? JWT.decode(auth_token.gsub('Bearer ', ''), nil, false) : {}
+          {
+            auth_token:,
+            auth_data: auth_data.to_json,
+            params:
+          }.stringify_keys
+        end
+
+        def get_otl_auth_data(request, env)
+          auth_token = env['HTTP_AUTHORIZATION'] || ''
+          auth_data =  auth_token.present? ? JWT.decode(auth_token.gsub('Bearer ', ''), nil, false) : {}
+          {
+            auth_token:,
+            auth_data: auth_data.to_json,
+            params: request.params.to_json
+          }.stringify_keys
+        end
+      end
+    end
+  end
+end
+
+Yes::Read::Api::Engine.routes.draw do
+  constraints(Yes::Read::Api::ModelConstraints) do
+    get '/:model', to: Yes::Read::Api::OtlTrackableRequest.new(action_name: :call)
+    post '/:model', to: Yes::Read::Api::OtlTrackableRequest.new(action_name: :advanced)
+  end
+end

data/lib/tasks/yousty/read/api_tasks.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# desc "Explaining what the task does"
+# task :yes_read_api do
+#   # Task goes here
+# end

data/lib/yes/read/api/advanced_filter_validator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'dry-schema'
+
+module Yes
+  module Read
+    module Api
+      class AdvancedFilterValidator
+        PaginationSchema = Dry::Schema.Params do
+          required(:size).value(:integer)
+          required(:number).value(:integer)
+        end
+
+        AdvancedEndpointPayloadSchema = Dry::Schema.Params do
+          required(:filter_definition).hash(Yes::Core::ReadModel::FilterQueryBuilder::FilterSetSchema)
+          optional(:page).hash(PaginationSchema)
+          optional(:order).value(:hash)
+          optional(:include).value(:string)
+        end
+
+        class << self
+          def call(payload)
+            new(payload).call
+          end
+        end
+
+        attr_reader :payload
+
+        def initialize(payload)
+          @payload = payload
+        end
+
+        def call
+          AdvancedEndpointPayloadSchema.call(payload)
+        end
+      end
+    end
+  end
+end

data/lib/yes/read/api/api_pagination_patch.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'pagy/extras/countless'
+require 'api-pagination'
+
+module Yes
+  module Read
+    module Api
+      module ApiPaginationPatch
+        include Pagy::CountlessExtra
+
+        private
+
+        def pagy_from(collection, options)
+          return countless_pagy(collection, options) if Pagy::DEFAULT[:countless_minimal] && options[:include_total] != 'true'
+
+          super
+        end
+
+        def countless_pagy(collection, options)
+          options[:countless_minimal] = true
+          options[:items] = options[:per_page]
+
+          pagy, = pagy_countless(collection, options)
+          pagy
+        end
+      end
+    end
+  end
+end
+
+ApiPagination.singleton_class.prepend(Yes::Read::Api::ApiPaginationPatch)

data/lib/yes/read/api/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Yes
+  module Read
+    module Api
+      class Engine < ::Rails::Engine
+        isolate_namespace Yes::Read::Api
+        config.generators.api_only = true
+
+        config.generators do |g|
+          g.test_framework :rspec
+        end
+        config.yes_read_api = Yes::Read::Api.config
+      end
+    end
+  end
+end

data/lib/yes/read/api/model_constraints.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Yes
+  module Read
+    module Api
+      class ModelConstraints
+        class << self
+          # @param request [ActionDispatch::Request]
+          def matches?(request)
+            Rails.application.config.yes_read_api.read_models.include?(request.params['model'])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/read/api/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Yes
+  module Read
+    module Api
+      VERSION = '1.0.0'
+    end
+  end
+end

data/lib/yes/read/api.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'yes/core'
+require 'zeitwerk'
+
+module Yes
+  module Read
+    module Api
+      class Error < StandardError; end
+
+      class << self
+        def loader
+          @loader ||= begin
+            loader = Zeitwerk::Loader.new
+            loader.tag = 'yes-read-api'
+            loader.push_dir(File.expand_path('../..', __dir__))
+            loader.ignore("#{File.expand_path('..', __dir__)}/read/api/version.rb")
+            loader.setup
+            loader
+          end
+        end
+
+        # @return [ActiveSupport::OrderedOptions]
+        def config
+          @config ||= ActiveSupport::OrderedOptions.new.tap do |opts|
+            opts.read_models = [] # E.g. ['apprenticeships', 'companies', 'professions']
+          end
+        end
+
+        def configure
+          yield config
+        end
+      end
+    end
+  end
+end
+
+require 'yes/read/api/version'
+
+Yes::Read::Api.loader.eager_load

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: yes-read-api
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nico Ritsche
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: api-pagination
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: pagy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: yes-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Read API for the Yes event sourcing framework
+email:
+- nico.ritsche@yousty.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/yes/read/api/application_controller.rb
+- app/controllers/yes/read/api/queries_controller.rb
+- config/initializers/api_pagination.rb
+- config/routes.rb
+- lib/tasks/yousty/read/api_tasks.rake
+- lib/yes/read/api.rb
+- lib/yes/read/api/advanced_filter_validator.rb
+- lib/yes/read/api/api_pagination_patch.rb
+- lib/yes/read/api/engine.rb
+- lib/yes/read/api/model_constraints.rb
+- lib/yes/read/api/version.rb
+homepage: https://github.com/yousty/yes
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yousty/yes
+  source_code_uri: https://github.com/yousty/yes/tree/main/yes-read-api
+  changelog_uri: https://github.com/yousty/yes/blob/main/yes-read-api/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.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: Read API for the Yes event sourcing framework
+test_files: []