roda-endpoints 0.1.0

data/lib/roda/endpoints/endpoint/class_interface.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'roda/endpoints'
+require 'roda/endpoints/transactions'
+require 'inflecto'
+
+class Roda
+  module Endpoints
+    class Endpoint
+      module ClassInterface
+        # @return [<Symbol>]
+        attr_accessor :attributes
+
+        # @return [{Symbol=>Object}]
+        attr_accessor :defaults
+
+        # @return [{Symbol=>{Symbol=>Symbol}}]
+        attr_accessor :statuses
+
+        # @return [<Symbol>]
+        attr_accessor :verbs
+
+        # @param [Symbol] key
+        def define_attribute(key)
+          self.attributes += [key]
+          attr_reader key
+        end
+
+        # @return [Dry::Container]
+        def container
+          @container ||= Roda::Endpoints.container
+        end
+
+        # @param [Class] child
+        def inherited(child)
+          child.attributes = attributes.dup
+          child.defaults = defaults.dup
+          child.statuses = statuses.dup
+          child.verbs = verbs.dup
+          super
+        end
+
+        def ns
+          @ns ||= name.gsub(/^Roda::Endpoints::/, '').underscore.tr('/', '.')
+        end
+
+        # @return [Symbol]
+        def type
+          @type ||= Inflecto.underscore(Inflecto.demodulize(name)).to_sym
+        end
+
+        # @param [Symbol] name
+        # @param [Proc] block
+        # @return [Symbol] name of the defined method
+        def verb(name, rescue_from: [], &block)
+          rescue_from = Array(rescue_from).flatten
+          if rescue_from.any?
+            block = proc do |*args|
+              begin
+                instance_exec(*args, &block)
+              rescue *rescue_from
+                Left($ERROR_INFO)
+              end
+            end
+          end
+          define_method(name, &block)
+          container.register "operations.#{type}.#{name}", block
+          self.verbs ||= superclass.verbs
+          (self.verbs += [name]).freeze
+        end
+
+        # @param [String, Symbol] key
+        # @param [Proc] block
+        #
+        # @example
+        #   r.collection :articles do |articles|
+        #     # register validation at 'validations.endpoints.articles.default'
+        #     articles.validate do
+        #       required(:title).filled?
+        #       required(:contents).filled?
+        #     end
+        #     # redefine validation for patch method at
+        #     # 'validations.endpoints.articles.patch'
+        #     articles.validate(:patch) do
+        #       required(:title).filled?
+        #       required(:contents).filled?
+        #       require(:confirm_changes).
+        #     end
+        #   end
+        def validate(key = :default, &block)
+          key = "validations.#{ns}.#{key}" if key.is_a?(Symbol)
+          schema = Dry::Validation.Form(&block)
+          container.register(key) do |params|
+            validation = schema.call(params)
+            if validation.success?
+              Right(validation.output)
+            else
+              Left([:unprocessable_entity, {}, validation])
+            end
+          end
+          schema
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        # @param [Proc] block
+        # @return [Proc]
+        def route(&block)
+          @route_block = block if block_given?
+          @route_block
+        end
+
+        def transaction(name, &block)
+          transactions << [name, block]
+        end
+
+        # @return [(Symbol, Hash, Proc)]
+        def transactions
+          @transactions ||= []
+        end
+      end
+    end
+  end
+end

data/lib/roda/endpoints/endpoint/collection.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'roda/endpoints/endpoint'
+require 'roda/endpoints/endpoint/data'
+require 'roda/endpoints/endpoint/caching'
+require 'inflecto'
+require 'rom/sql'
+
+class Roda
+  module Endpoints
+    class Endpoint
+      # HTTP endpoint representing a collection of items of the same type.
+      class Collection < Endpoint
+        include Data
+        prepend Caching
+
+        self.attributes += %i(item)
+        self.defaults = defaults.merge(
+          type: :collection,
+          last_modified: :last_modified
+        )
+
+        # @return [{Symbol=>Object}]
+        attr_reader :item
+
+        # @return [Time]
+        def last_modified
+          @last_modified ? repository.public_send(@last_modified) : super
+        end
+
+        def child(**params)
+          with(
+            type: Item,
+            name: resource_name,
+            **params
+          )
+        end
+
+        # @return [Symbol]
+        def resource_name
+          Inflecto.singularize(name).to_sym
+        end
+
+        route do |r, endpoint| # r.collection :articles do |articles|
+          r.last_modified endpoint.last_modified if endpoint.last_modified
+
+          endpoint.verbs.each do |verb|
+            # @route #{verb} /:name
+            r.public_send(verb, transaction: verb)
+
+            r.child **endpoint.item if endpoint.item # child by: :id
+          end
+        end
+
+        verb :get do |params|
+          Right(repository.list(**params))
+        end
+
+        verb :post do |params|
+          params = params[resource_name] || {}
+          Right(repository.create(**params))
+        end
+
+        # @route GET /{collection.name}
+        transaction :get do |endpoint|
+          step :retrieve, with: endpoint.operation_for(:get)
+        end
+
+        # @route POST /{collection.name}
+        transaction :post do |endpoint|
+          step :validate, with: endpoint.validation_for(:post)
+          step :persist, with: endpoint.operation_for(:post)
+        end
+      end
+    end
+  end
+end

data/lib/roda/endpoints/endpoint/data.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Roda
+  module Endpoints
+    # Generic HTTP endpoint abstraction.
+    class Endpoint
+      # Accessing data inside of endpoint.
+      module Data
+        # @param name [String]
+        # @param repository [String]
+        # @param attributes [{Symbol=>Object}]
+        def initialize(name:, repository: "repositories.#{name}", **attributes)
+          @repository_key = repository
+          super(name: name, **attributes)
+        end
+
+        # @return [ROM::Repository]
+        def repository
+          container[@repository_key] if @repository_key
+        end
+
+        # @return [{Symbol=>Object}]
+        def to_hash
+          super.merge(repository: @repository_key)
+        end
+      end
+    end
+  end
+end

data/lib/roda/endpoints/endpoint/item.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'roda/endpoints/endpoint'
+require 'roda/endpoints/endpoint/data'
+require 'roda/endpoints/endpoint/caching'
+
+class Roda
+  module Endpoints
+    class Endpoint
+      # HTTP endpoint representing a specific item of collection uniquely
+      # identified by some parameter.
+      class Item < Endpoint
+        include Data
+        include Caching
+
+        self.attributes += %i(id by finder last_modified)
+        self.defaults = defaults.merge(
+          by: :fetch,
+          finder: lambda do
+            repository.public_send(by, id)
+          end,
+          last_modified: :updated_at
+        )
+
+        # @return [Symbol]
+        attr_reader :by
+
+        # @return [Symbol]
+        attr_reader :id
+
+        # @return [Symbol]
+        attr_reader :finder
+
+        # @return [Endpoint::Collection]
+        def collection
+          parent
+        end
+
+        # @return [ROM::Struct]
+        def entity
+          @entity ||= fetch_entity
+        end
+
+        def fetch_entity
+          instance_exec(&finder)
+        end
+
+        def last_modified
+          @last_modified ? entity.public_send(@last_modified) : super
+        end
+
+        route do |r, endpoint|
+          endpoint.verbs.each do |verb|
+            # @route #{verb} /{collection.name}/{id}
+            # STDOUT.puts [verb].pretty_inspect
+            r.public_send(verb, transaction: verb)
+          end
+        end
+
+        transaction :get do |endpoint|
+          step :retrieve, with: endpoint.operation_for(:get)
+        end
+
+        transaction :patch do |endpoint|
+          step :validate, with: endpoint.validation_for(:patch)
+          step :persist, with: endpoint.operation_for(:patch)
+        end
+
+        transaction :put do |endpoint|
+          step :validate, with: endpoint.validation_for(:put)
+          # step :reset, with: 'endpoints.operations.reset'
+          step :persist, with: endpoint.operation_for(:put)
+        end
+
+        transaction :delete do |endpoint|
+          step :validate, with: endpoint.validation_for(:delete)
+          step :persist, with: endpoint.operation_for(:delete)
+        end
+
+        # @route GET /{collection.name}/{id}
+        # @param [Hash] params
+        # @return [Dry::Monads::Either]
+        verb :get do |_params|
+          Right(entity)
+        end
+
+        # @route PATCH /{collection.name}/{id}
+        # @return [Dry::Monads::Either]
+        verb :patch do |params|
+          changeset = params[name]
+          Right(repository.update(id, changeset))
+        end
+
+        # @route PUT /{collection.name}/{id}
+        # @return [Dry::Monads::Either]
+        verb :put do |params|
+          changeset = entity.to_hash.keys.each_with_object(
+            {}
+          ) do |key, changeset|
+            changeset[key] = nil
+          end.merge(params[name] || {})
+          Right(repository.update(id, changeset))
+        end
+
+        # @route DELETE /{collection.name}/{id}
+        # @return [Dry::Monads::Either]
+        verb :delete do |_params|
+          if (result = repository.delete(id))
+            Right(nil)
+          else
+            Left(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/roda/endpoints/endpoint/namespace.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class Roda
+  module Endpoints
+    # Generic HTTP endpoint abstraction.
+    class Endpoint
+      # Namespacing operations, validations, etc.
+      module Namespace
+        def self.included(child)
+          child.attributes += %i(name ns parent)
+        end
+
+        # @param name [Symbol]
+        # @param ns [String]
+        # @param attributes [{Symbol=>Object}]
+        # @param parent [Endpoint?]
+        def initialize(name:, ns: name.to_s, parent: Undefined, **attributes)
+          @name = name
+          @ns = ns
+          unless parent == Undefined
+            @parent = parent
+            @ns = "#{parent.ns}.#{ns}"
+          end
+          super(name: name, **attributes)
+        end
+
+        # @return [Symbol]
+        attr_reader :name
+
+        # @return [String]
+        attr_reader :ns
+
+        # @return [Endpoint]
+        attr_reader :parent
+
+        # @return [ROM::Repository]
+        def repository
+          container[@repository_key] if @repository_key
+        end
+
+        # @return [{Symbol=>Object}]
+        def to_hash
+          super.merge(repository: @repository_key)
+        end
+      end
+    end
+  end
+end

data/lib/roda/endpoints/endpoint/operations.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Roda
+  module Endpoints
+    # Generic HTTP endpoint abstraction.
+    class Endpoint
+      # Parameters validations for {Endpoints} based on `Dry::Validation` gem.
+      module Operations
+        def initialize(**kwargs)
+          super(**kwargs)
+          container.merge(Endpoints.container)
+          self.class.verbs.each do |verb|
+            container.register "operations.#{ns}.#{verb}", &method(verb)
+          end
+        end
+
+        # @param [Symbol] verb
+        # @return [String]
+        def operation_for(verb)
+          %W(
+            operations.#{ns}.#{verb}
+            operations.#{type}.#{verb}
+          ).detect { |key| container.key?(key) }
+        end
+      end
+    end
+  end
+end

data/lib/roda/endpoints/endpoint/transactions.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'roda/endpoints/transactions'
+
+class Roda
+  module Endpoints
+    # Generic HTTP endpoint abstraction.
+    class Endpoint
+      # Namespacing operations, validations, etc.
+      module Transactions
+        # @return [Endpoints::Transactions]
+        def transactions
+          endpoint = self
+          @transactions ||=
+            begin
+              transactions = Endpoints::Transactions.new(endpoint: self)
+              self.class.transactions.each do |(name, block)|
+                transactions.define(name) { instance_exec(endpoint, &block) }
+              end
+              transactions
+            end
+          yield @transaction if block_given?
+          @transactions
+        end
+
+        # @param [Symbol] verb
+        # @return [String]
+        def transaction_for(verb)
+          %W(
+            transactions.#{ns}.#{verb}
+            transactions.#{type}.#{verb}
+          ).detect { |key| container.key?(key) }
+        end
+
+        # @param [Symbol, String] name
+        # @param [Proc] block
+        def step(name, only: [], **kwargs, &block)
+          name = "operations.#{ns}.#{name}"
+          container.register(name, &block) if block_given?
+          verbs = Array(only).flatten
+          verbs.each do |verb|
+            result = transactions[verb].insert(container: container, **kwargs) do
+              step name
+            end
+            @transaction = result
+          end
+          transactions
+        end
+
+        def before(name, **kwargs, &block)
+          step "before_#{name}", before: name, **kwargs, &block
+        end
+
+        def after(name, **kwargs, &block)
+          step "after_#{name}", after: name, **kwargs, &block
+        end
+
+        # @param [Symbol] operation
+        # @param [Array] args
+        # @return [Dry::Monads::Either]
+        def perform(operation, *args, **options)
+          transactions[operation].call(*args, **options)
+        end
+      end
+    end
+  end
+end

data/lib/roda/endpoints/endpoint/validations.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'roda/endpoints'
+require 'roda/endpoints/functions'
+require 'dry-validation'
+
+class Roda
+  module Endpoints
+    # Generic HTTP endpoint abstraction.
+    class Endpoint
+      # Parameters validations for {Endpoints} based on `Dry::Validation` gem.
+      module Validations
+        include Functions::Shortcut
+
+        # @param [Class] child
+        def self.included(child)
+          child.defaults = child.defaults.merge(validation: 'validation').freeze
+          super
+        end
+
+        # @param [String, Symbol] key
+        # @param [Proc] block
+        #
+        # @example
+        #   r.collection :articles do |articles|
+        #     # register validation at 'validations.endpoints.articles.default'
+        #     articles.validate do
+        #       required(:title).filled?
+        #       required(:contents).filled?
+        #     end
+        #     # redefine validation for patch method at
+        #     # 'validations.endpoints.articles.patch'
+        #     articles.validate(:patch) do
+        #       required(:title).filled?
+        #       required(:contents).filled?
+        #       require(:confirm_changes).
+        #     end
+        #   end
+        def validate(key = :default, &block)
+          defaults = "validations.defaults.#{ns}.#{key}"
+          key = "validations.#{ns}.#{key}"
+          schema = Dry::Validation.Form(&block)
+          container.register(key) do |params|
+            if container.key?(defaults)
+              params = f(:deep_merge).call(params, container[defaults])
+            end
+            validation = schema.call(params)
+            if validation.success?
+              Right(validation.output)
+            else
+              Left([:unprocessable_entity, {}, validation])
+            end
+          end
+          schema
+        end
+
+        # rubocop:enable Metrics/MethodLength
+
+        def defaults(verb = :default, **attributes)
+          key = "validations.defaults.#{ns}.#{verb}" if key.is_a?(Symbol)
+          container.register key, attributes
+        end
+
+        # @param [Symbol] verb
+        # @return [Dry::Validation::Schema::Form]
+        def validation(verb)
+          if (validation = validation_for(verb))
+            container[validation]
+          else
+            # default validation requires no params and provide no results
+            provide_default_validation!
+          end
+        end
+
+        def provide_default_validation!
+          validate {} unless container.key?("validations.#{ns}.default")
+        end
+
+        # @param [Symbol] verb
+        # @return [String]
+        def validation_for(verb)
+          validation = %W(
+            validations.#{ns}.#{verb}
+            validations.#{ns}.default
+          ).detect do |key|
+            container.key?(key)
+          end
+          validation = provide_default_validation! unless validation
+          validation
+        end
+
+        def validate!(verb, params)
+          validation(verb).call(params)
+        end
+      end
+    end
+  end
+end

data/lib/roda/endpoints/endpoint/verbs.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+class Roda
+  module Endpoints
+    # Generic HTTP endpoint abstraction.
+    class Endpoint
+      # Accessing data inside of endpoint.
+      module Verbs
+        extend Forwardable
+
+        # @param [<Symbol>] only
+        # @param [<Symbol>] except
+        # @param attributes [{Symbol=>Object}]
+        def initialize(only: implemented_verbs, except: [], **attributes)
+          only = Array(only).flatten
+          except = Array(except).flatten
+          if ((unknown_only = only - implemented_verbs) +
+              (unknown_except = except - implemented_verbs)).any?
+            params = { only: unknown_only, except: unknown_except }
+            raise ArgumentError, "unknown verbs in params: #{params}"
+          end
+          @verbs = only - except
+          super(**attributes)
+        end
+
+        # @return [<Symbol>]
+        def implemented_verbs
+          self.class.verbs.to_a
+        end
+
+        # @return [<Symbol>]
+        attr_reader :verbs
+
+        def verb(name, **kwargs, &block)
+          key = "operations.#{ns}.#{name}"
+          container.register key, &block
+          singleton_class.verb(name, **kwargs, &container[key])
+        end
+        def_delegator :singleton_class, :verb
+      end
+    end
+  end
+end