tomyum 0.1.0.a

data/lib/tomyum/attributes.rb

@@ -0,0 +1,92 @@
+require_relative "registry"
+require_relative "attributes/visitor"
+require_relative "serializers/serializable"
+require_relative "validators/normalizable"
+require_relative "validators/validatable"
+
+# Attributes
+require_relative "attributes/boolean"
+require_relative "attributes/string"
+require_relative "attributes/number"
+require_relative "attributes/integer"
+require_relative "attributes/float"
+require_relative "attributes/array"
+require_relative "attributes/object"
+require_relative "attributes/schema"
+require_relative "attributes/date"
+require_relative "attributes/time"
+require_relative "attributes/currency"
+require_relative "attributes/uri"
+require_relative "attributes/ip_address"
+
+module Tomyum
+  # Attributes registry holds the references to all attributes
+  #
+  # @see .create
+  module Attributes
+    include Tomyum::Assertions
+    KeyError  = Tomyum::Error.create "Attribute %s already exists"
+
+    @registry = Registry.new({}, error: KeyError) do |id, name, options, block|
+      attribute = get(id)
+      attribute.new(name, options, &block)
+    end
+
+    class << self
+      # Holds reference to all attribute objects
+      #
+      # @return [Registry]
+      attr_accessor :registry
+
+      # Creates new attribute (Delegates to Registry#create).
+      #
+      # @return [Attribute]
+      #
+      # @example Creates primitive attribute
+      #   Attributes.create(:string, :username, required: true)
+      #
+      # @example Creates compound attribute
+      #   Attributes.create(:object, :user) do
+      #     string :username
+      #   end
+      def create(type, name, options = {}, &block)
+        registry.create(type, name, options, &block)
+      end
+
+      # Registers new Attribute (alias for Registry#register)
+      #
+      # @example
+      #   register(:custom, CustomAttribute)
+      def register(type, klass, override: false)
+        registry.register(type, klass, override: override)
+      end
+
+      def key?(key)
+        registry.key?(key)
+      end
+    end
+
+    ALL = {
+      string:       String,
+      number:       Number,
+      integer:      Integer,
+      float:        Float,
+      boolean:      Boolean,
+      object:       Object,
+      array:        Array,
+      schema:       Schema,
+      time:         Time,
+      date:         Date,
+      uri:          URI,
+      currency:     Currency,
+      ip_address:   IPAddress,
+    }.freeze
+
+    SCALAR_TYPES     = %i[string number integer float boolean].freeze
+    NATIVE_TYPES     = SCALAR_TYPES + %i[array object].freeze
+    NON_SCALAR_TYPES = ALL.keys - SCALAR_TYPES
+
+    # register pre-defined attributes
+    ALL.each { |name, attr| register(name, attr) }
+  end
+end

data/lib/tomyum/endpoint.rb

@@ -0,0 +1,102 @@
+require_relative "endpoints/params"
+require_relative "endpoints/method"
+
+module Tomyum
+  class Endpoint
+    include Tomyum::Assertions
+
+    # See `docs/api/endpoint-validations.md`.
+    HTTP_METHODS_WITHOUT_BODY = %i[get head trace]
+    HTTP_METHODS_WITH_BODY    = %i[post put patch delete]
+    HTTP_METHODS = HTTP_METHODS_WITHOUT_BODY + HTTP_METHODS_WITH_BODY
+
+    class << self
+      # Converts `/users/:id/friends` to `users_id_friends`
+      def normalize_name(name)
+        name.to_s.delete(":").gsub(/(\A\/+|\/+\z)/, '').tr('/', '_').to_sym
+      end
+    end
+
+    DEFAULT_OPTIONS = {
+      schema:      nil,
+      title:       nil,
+      description: nil,
+    }.freeze
+
+    attr_reader   :path, :name, :schema
+    attr_accessor :title, :description
+
+    def initialize(path, options = {}, &block)
+      options  = DEFAULT_OPTIONS.merge(options)
+      @schema  = options[:schema]
+      @path    = path
+      @name    = normalize_name(options[:name])
+      @methods = {}
+      @params  = nil
+      @block   = block
+      @loaded  = false
+      @title   = options[:title]
+      @description = options[:description]
+    end
+
+    # Defines http methods dynamically e.g. :get, :post ...
+    #   endpoint.define do
+    #     get :index, path: "/"
+    #     post :create
+    #   end
+    HTTP_METHODS.each do |method|
+      define_method method do |action, path: "/", **options|
+        create_method(method, action, path: path, **options)
+      end
+    end
+
+    # Lazily builds all params and return methods hash
+    def methods(resolver = nil)
+      ensure_loaded
+
+      @methods.each { |name, _| method(name, resolver: resolver) }
+    end
+
+    # Lazily builds params for speicified method
+    def method(name, resolver: nil)
+      ensure_loaded
+      assert_in @methods, name.to_sym
+
+      @methods[name.to_sym].tap { |method| method.build_params(params, resolver) }
+    end
+
+    # Returns default params
+    def params(&block)
+      ensure_loaded
+
+      @params ||= Tomyum::Endpoints::Params.new(:default, schema: schema, built: true, &block || -> {})
+    end
+
+    # Registers http verb method
+    #
+    #   create_method(:post, :create, path: "/")
+    def create_method(verb, action, path: "/", **options)
+      # Automatically adds it self as schema value
+      options[:schema] = options.fetch(:schema, schema)
+
+      @methods[action.to_sym] = Tomyum::Endpoints::Method.new(verb, action: action, path: path, **options)
+    end
+
+    private
+
+    def normalize_name(name)
+      (name || @schema || self.class.normalize_name(@path)).to_sym
+    end
+
+    # Lazily executes &block
+    def ensure_loaded
+      return if @loaded
+
+      # We need to set status here; otherwise, we'll have
+      # error when there's nested block.
+      @loaded = true
+
+      instance_exec(&@block) if @block
+    end
+  end
+end

data/lib/tomyum/endpoints/method.rb

@@ -0,0 +1,90 @@
+module Tomyum
+  module Endpoints
+    # Represents HTTP method
+    #
+    # @example Create new +POST+ {Method}
+    #   Method.new(:post, action: :create, path: "/", schema: :user, as: :list)
+    #
+    # @example
+    #   Method.new(:post, {
+    #     action: :create,
+    #     path: "/",
+    #     validators: [CustomValidator]
+    #   })
+    class Method
+      DEFAULT_OPTIONS = {
+        as:          nil,
+        params:      [],
+        exclude:     false,
+        schema:      nil,
+        status:      200,
+        title:       nil,
+        description: nil,
+        validators:  [],
+      }.freeze
+
+      attr_reader   :verb, :path, :action, :params, :schema, :status, :as
+      attr_accessor :title, :description
+
+      def initialize(verb, action:, path: "/", **options)
+        @options = DEFAULT_OPTIONS.merge(options)
+        @verb    = verb
+        @path    = path
+        @action  = action
+
+        # Create ParamsAttribute instance
+        @params  = create_params(action, **options.slice(:params, :schema, :exclude))
+        @schema  = @options[:schema]
+        @as      = @options[:as]
+        @status  = @options[:status]
+        @title   = @options[:title]
+        @description = @options[:description]
+        @validator   = nil
+        @validators  = @options[:validators]
+        @resolver    = nil
+        @result      = nil
+      end
+
+      def validate(params = {}, resolver = nil)
+        @validator = create_validator(@resolver || resolver)
+        @result    = @validator.validate(@params, params, validators: @validators)
+      end
+
+      def valid?(*args)
+        validate(*args)
+
+        @result&.errors&.empty?
+      end
+
+      def errors
+        @result&.errors
+      end
+
+      # Does it have request body? (only non GET verb can have request body)
+      def body?
+        Tomyum::Endpoint::HTTP_METHODS_WITH_BODY.include?(@verb) && @params.keys.any?
+      end
+
+      def build_params(default = {}, resolver = nil)
+        @resolver = resolver if resolver
+        @params   = @params.build(default, resolver)
+      end
+
+      def permit_params(params = {}, target = nil)
+        return params unless params.respond_to?(:permit)
+
+        params.permit(*@params.permit(params))
+      end
+
+      private
+
+      def create_params(action, **options)
+        Tomyum::Endpoints::Params.new(action, **options)
+      end
+
+      def create_validator(*args)
+        Tomyum::Validator.new(*args)
+      end
+    end
+  end
+end

data/lib/tomyum/endpoints/params.rb

@@ -0,0 +1,115 @@
+module Tomyum
+  module Endpoints
+    # Usage
+    #
+    #   Params.new(:create)
+    #   Params.new(:index, params: :list)
+    #   Params.new(:create, params: %i[amount currency])
+    #   Params.new(:create, params: %i[amount], exclude: true)
+    #   Params.new(:create, params: false)
+    #   Params.new :create, params: -> {
+    #     integer :amount
+    #   }
+    #   Params.new(:index, schema: :user, as: :list)
+    #
+    class Params < Attributes::Object
+      include Tomyum::Assertions
+      include Tomyum::Resolvable
+
+      InvalidType = Tomyum::Error.create("Invalid params type")
+      NotBuilt    = Tomyum::Error.create("Params need to be built first")
+
+      DEFAULT_OPTIONS = {
+        exclude: false,
+        schema: nil,
+        built: false,
+      }.freeze
+
+      attr_reader :action, :params, :schema
+
+      def initialize(action, params: false, **options, &block)
+        super(action, options.except(DEFAULT_OPTIONS.keys))
+
+        options  = DEFAULT_OPTIONS.merge(options)
+        @action  = action.to_sym
+        @exclude = options[:exclude]
+        @schema  = options[:schema]
+        @params  = block_given? ? block : params
+        @built   = options[:built]
+      end
+
+      def build(default = {}, resolver = nil)
+        # Flag as built
+        @built = true
+
+        case @params
+        when Params
+          @params
+        when true
+          # use default params
+          default
+        when false
+          # use no params
+          self
+        when Proc
+          instance_exec(&@params)
+          self
+        when Symbol
+          # use params from other service
+          resolver.endpoint(@params).params
+        when Array
+          assert_subset_of(default.keys, @params)
+
+          # override default params by using specified symbol
+          keys = @exclude ? default.keys - @params : @params
+          keys.each { |name| self[name] = default[name] }
+          self
+        else
+          raise InvalidType
+        end
+      end
+
+      def built?
+        @built
+      end
+
+      # Build permitted params for ActionController::Params
+      def permit(params = {})
+        raise NotBuilt unless built?
+
+        build_permitted_params(attributes, params)
+      end
+
+      private
+
+      def build_permitted_params(attrs, params = {})
+        attrs.map do |name, attr|
+          # permit array
+          # TODO: params.permit(:foo, array: [:key1, :key2])
+          next { name => [] } if attr.kind_of?(Tomyum::Attributes::Array)
+
+          # permit non-object
+          next name unless attr.kind_of?(Tomyum::Attributes::Object)
+
+          # Rails 5.0 doesn't support arbitary hash params
+          # 5.1+ supports this, via `key: {}` empty hash.
+          #
+          # The work around is to get hash keys from params
+          # and assign them to permit keys
+          # params = params&.fetch(name, {})
+          data = params&.fetch(name, {})
+          keys = build_permitted_params(attr.attributes, data)
+
+          { attr.name => normalize_permitted_params(keys, data) }
+        end
+      end
+
+      def normalize_permitted_params(keys, params = {})
+        return keys unless keys.empty?
+        return {} if params.empty?
+
+        params.keys
+      end
+    end
+  end
+end

data/lib/tomyum/error.rb

@@ -0,0 +1,17 @@
+module Tomyum
+  # @example
+  #   InvaldKey = Error.create("Invalid %s key")
+  #   raise InvalidKey, "id"
+  class Error < StandardError
+    def self.create(msg)
+      Class.new(Error) do
+        MESSAGE.replace msg
+      end
+    end
+
+    MESSAGE = "Error"
+    def initialize(*args)
+      super args.any? ? MESSAGE % args : MESSAGE
+    end
+  end
+end

data/lib/tomyum/functions.rb

@@ -0,0 +1,49 @@
+module Tomyum
+  # FP helpers
+  module Functions
+    class Result
+      attr_reader :value, :errors
+
+      def initialize(value, errors = nil)
+        @value  = value
+        @errors = errors
+      end
+
+      def compose(f)
+        return self if errors
+
+        f.(value)
+      end
+    end
+
+    def result(value, errors = nil)
+      Result.new(value, errors)
+    end
+
+    # Compose functions
+    # compose : (a -> b) -> (b -> c) -> a -> c
+    def compose(*fns)
+      ->(v) {
+        fns.reduce(fns.shift.(v)) do |x, f|
+          x.respond_to?(:compose) ? x.compose(f) : f.(x)
+        end
+      }
+    end
+
+    # A composition that early returns value
+    # f : a -> b
+    # g : a -> c
+    def compose_result(*fns)
+      ->(v) {
+        fns.reduce(fns.shift.(v)) do |x, f|
+          x ? x : f.(v)
+        end
+      }
+    end
+
+    # Curry instance method
+    def curry(method, *args)
+      self.method(method).curry[*args]
+    end
+  end
+end

data/lib/tomyum/generators/generator.rb

@@ -0,0 +1,16 @@
+module Tomyum
+  module Generators
+    class Generator
+      include Tomyum::Assertions
+      include Tomyum::Resolvable
+
+      def initialize(resolver = nil)
+        @resolver = resolver
+      end
+
+      def generate(*args)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/tomyum/generators/grpc/generator.rb

@@ -0,0 +1,10 @@
+module Tomyum
+  module API
+    module Generators
+      module Grpc
+        class Generator
+        end
+      end
+    end
+  end
+end

data/lib/tomyum/generators/open_api/generator.rb

@@ -0,0 +1,205 @@
+require "ostruct"
+
+module Tomyum
+  module Generators
+    module OpenAPI
+      # Generate Open API v3 Specifications
+      #
+      # @example
+      #   resolver  = Resolver.new(schemas: [])
+      #   generator = OpenApi::Generator.new(resolver, {
+      #     title: "Awesome API",
+      #     version: "1.0.0",
+      #     # other infos ...
+      #   })
+      #
+      #   generator = OpenApi::Generator.new(resolver) do
+      #     title "Awesome API"
+      #     version "1.0.0"
+      #     servers []
+      #   end
+      #
+      #   generator.generate # => {  }
+      class Generator < Tomyum::Generators::Generator
+        OPEN_API_VERSION  = "3.0.0".freeze
+        OPEN_API_ID_REGEX = /:([\w]+)/.freeze
+        EMPTY_RESPONSE    = "Response".freeze
+
+        OPTIONS = {
+          version: nil,
+          title: nil,
+          description: nil,
+          servers: []
+        }
+
+        def initialize(resolver = nil, options = {})
+          super(resolver)
+
+          @options = OPTIONS.merge(options)
+        end
+
+        def generate
+          {
+            openapi: OPEN_API_VERSION,
+            info: {
+              version: @options[:version],
+              title: @options[:title],
+              description: @options[:description],
+            },
+            servers: generate_server_urls(@options[:servers]),
+            paths: generate_paths(resolver.endpoints.keys),
+            components: {
+              schemas: generate_schemas(resolver.schemas.keys),
+            },
+          }
+        end
+
+        # share for both specs
+        def generate_params(method, base_url = nil)
+          generate_path_params(method, base_url) + generate_query_params(method)
+        end
+
+        def generate_param(param, in: :query, schema: nil)
+          return unless param.serializable?
+
+          {
+            name: param.name.to_s,
+            in: binding.local_variable_get(:in),
+            schema: PropertyGenerator.generate(param, schema: schema),
+          }.tap do |parameter|
+            parameter[:required]    = param.required if param.required
+            parameter[:deprecated]  = param.deprecated if param.deprecated
+            parameter[:description] = param.description if param.description
+          end
+        end
+
+        # path contains id? e.g. /users/:id
+        def generate_path_params(method, base_url = nil)
+          extract_ids(url(base_url, method.path))
+            .map { |id| Attributes::String.new(id, required: true) }
+            .map { |id| generate_param(id, in: :path) }
+        end
+
+        # convert request body to `query` params when HTTP verb is `GET`
+        def generate_query_params(method)
+          return [] unless method.verb == :get
+
+          method.params.attributes.values.each_with_object([]) do |param, params|
+            # include original schema when method.schema differs from params.schema
+            schema = method.params.schema if method.schema != method.params.schema
+            params << generate_param(param, schema: schema)
+          end.compact
+        end
+
+        def group_methods_by_path(methods)
+          methods.values.each_with_object({}) do |method, paths|
+            paths[method.path] ||= []
+            paths[method.path] << method
+          end
+        end
+
+        # -- end --
+        def generate_server_urls(urls = [])
+          urls.map { |name, url| { url: url, description: name } }
+        end
+
+        def generate_paths(services)
+          services.each_with_object({}) do |name, paths|
+            # no need to initialize
+            next unless (endpoint = resolver.endpoint(name))
+
+            generate_operations(endpoint, paths)
+          end
+        end
+
+        def generate_operations(endpoint, paths)
+          base_url = endpoint.path
+          group_methods_by_path(endpoint.methods(resolver)).each do |path, methods|
+            resource_url = convert_id_params(url(base_url, path))
+            paths[resource_url] = {}
+
+            methods.each do |method|
+              paths[resource_url][method.verb] = generate_operation(method, base_url)
+            end
+          end
+        end
+
+        # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject
+        def generate_operation(method, base_url = nil)
+          {
+            tags: [method.schema.to_s.humanize.pluralize],
+            parameters: generate_params(method, base_url),
+          }.tap do |operation|
+            operation[:requestBody] = generate_request_params(method) if method.body?
+            operation[:summary]     = method.description if method.description
+            operation[:responses]   = generate_responses(method)
+          end
+        end
+
+        def generate_request_params(method)
+          {
+            "content": {
+              "application/x-www-form-urlencoded": {
+                schema: generate_schema(method.params),
+              },
+            },
+          }
+        end
+
+        def generate_responses(method)
+          {
+            method.status => generate_response(method),
+          }
+        end
+
+        def generate_response(method)
+          {
+            description: method.schema&.to_s&.humanize || EMPTY_RESPONSE,
+          }.tap do |response|
+            response[:content] = generate_json_response(method) if method.schema.present?
+          end
+        end
+
+        def generate_json_response(method)
+          {
+            "application/json": {
+              schema: PropertyGenerator.generate(method.schema, as: method.as),
+            },
+          }
+        end
+
+        # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject
+        def generate_schemas(serializers)
+          serializers.each_with_object({}) do |name, schemas|
+            # no need to initialize
+            next unless (object = resolver.schema(name))
+
+            schemas[name] = generate_schema(object)
+          end
+        end
+
+        def generate_schema(object)
+          self.class.assert_kind_of Tomyum::Attributes::Attribute, object
+
+          PropertyGenerator.generate(object)
+        end
+
+        private
+
+        # convert :id to {id} format
+        def convert_id_params(url)
+          url.gsub(OPEN_API_ID_REGEX, '{\1}')
+        end
+
+        def extract_ids(path)
+          path.scan(OPEN_API_ID_REGEX).flatten
+        end
+
+        # join relative url
+        def url(*parts)
+          "/" + parts.compact.map { |part| part.gsub(/^\/|\/$/, "") }.reject(&:blank?).join("/")
+        end
+      end
+    end
+  end
+end