rails_ninja 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99a76115680edb87523d0a819db195e01041bd3ed09d6bfabc0226963505f2fc
-  data.tar.gz: bedb6982e08bd7c32864052ef14d130d0f555503006ceef2a3a0f557e6165912
+  metadata.gz: 3c11362d2af26f7b911e310e2c67e603b5dfd63fd62e5758ce8936da06b1bb36
+  data.tar.gz: fb2bd66b8af63055d31a8c1cfc5eb2023883bc46f244c6f77fed0e0668dad4a8
 SHA512:
-  metadata.gz: e21f4e9ea17198535d38b26a0f7e46d522cb09f84885eee3a92dc4e6c73e16606d446784262bff3841cae1578d3d88ce46ae1c66a6615564f1d2b4139a2ae891
-  data.tar.gz: dd8f2cbee49dd08ecbbd95fb86ebb2aef82db49eb37f477db1094441e9c39104e7c15b793bba91abf1f6310ecf7e76237994bf16f60bc1ecaa113d57d8d1c31f
+  metadata.gz: e541dbca84d3e26df63229509abc3b5d70bae9da3ce6e8aa31da8c3a97a7df5d0f81ffd7e790820d96a019f0c16b984e2b329fc09fef5d0ea5b55c136c5b844c
+  data.tar.gz: '0381a91dd66a8c50be828018978d88d48e95b4f607325e94f1e4fb152d6714c79a79b2e6ef98e6c224c2d6a0409b96a061d748890edf188574e269a8a610b7d8'

data/README.md

@@ -5,7 +5,7 @@ Rails Ninja is a small Rails API framework inspired by
 request validation and response serialization, and generated OpenAPI
 documentation.
 
-Rails Ninja requires Ruby 3 or newer and Rails 7 or newer.
+Rails Ninja requires Ruby 3 or newer and Rails 7.1 or newer.
 
 ## Installation
 
@@ -103,8 +103,8 @@ end
 ```
 
 Fields are required by default. Available scalar types are `String`, `Int`,
-`Float`, and `Boolean` under `RailsNinja::Types`. A field may also contain a
-nested schema or a one-element array of a scalar or schema.
+`Float`, `Boolean`, and `File` under `RailsNinja::Types`. A field may also
+contain a nested schema or a one-element array of a scalar or schema.
 
 JSON input is strictly type-checked. Canonical path, query, and form values are
 decoded first, so an integer query value such as `"20"` becomes `20`. Invalid
@@ -114,6 +114,24 @@ into `params` as symbol keys.
 For `GET` and `DELETE`, a request schema is read from and documented as query
 parameters. `POST`, `PUT`, and `PATCH` use a request body.
 
+### File uploads
+
+```ruby
+schema :DocumentIn do
+  field :title, RailsNinja::Types::String
+  field :attachments, [RailsNinja::Types::File]
+  field :metadata, DocumentMetadata, required: false
+end
+```
+
+A request schema with a `File` field is documented as `multipart/form-data`
+and its values arrive as `ActionDispatch::Http::UploadedFile`. Arrays of files
+accept both `attachments[]` and repeated bare `attachments` parts, which is what
+OpenAPI generated clients send. Nested schema fields may be sent as JSON
+strings in their own part; they are validated with JSON types, not form
+coercion. `File` fields are only supported at the top level of a request
+schema and cannot appear in responses.
+
 Schemas may also be standalone:
 
 ```ruby
@@ -253,10 +271,13 @@ Generate an OpenAPI 3.2 JSON file for every API:
 ```sh
 bundle exec rake rails_ninja:openapi:generate
 bundle exec rake rails_ninja:openapi:generate OUTPUT=docs/api
+bundle exec rake rails_ninja:openapi:generate OPENAPI_VERSION=3.1.0
 ```
 
-The default output directory is `public/openapi`. File names come from the API
-class name, such as `PublicApi` to `public_api.json`.
+The default OpenAPI version is 3.2.0. Set `OPENAPI_VERSION` to a 3.0.x, 3.1.x,
+or 3.2.x version when a consumer requires another dialect. The default output
+directory is `public/openapi`. File names come from the API class name, such as
+`PublicApi` to `public_api.json`.
 
 ## Development
 
@@ -267,7 +288,7 @@ bundle install
 bundle exec rake test
 ```
 
-CI tests every compatible combination of Action Pack and Active Support 7.0
+CI tests every compatible combination of Action Pack and Active Support 7.1
 through 8.1 with MRI Ruby 3.0 through 4.0. Each lane resolves the latest patch
 release in its minor series.
 

data/lib/rails_ninja/api.rb

@@ -336,6 +336,8 @@ module RailsNinja
 
       if errors.empty?
         params.merge!(validated)
+        # Mounted groups / included endpoints run on their own instance with its own params
+        @_ninja_handler_instance&.params&.merge!(validated)
         return
       end
 
@@ -347,7 +349,9 @@ module RailsNinja
     def request_input(schema_class)
       path = decode_parameters(schema_class, request.path_parameters)
       query = decode_parameters(schema_class, request.query_parameters)
-      body = if FORM_MEDIA_TYPES.include?(request.media_type)
+      body = if request.media_type == "multipart/form-data"
+               Schema::ParameterDecoder.new(schema_class, multipart_parameters(schema_class), wrap_arrays: true).call
+             elsif FORM_MEDIA_TYPES.include?(request.media_type)
                decode_parameters(schema_class, request.request_parameters)
              else
                request.request_parameters.deep_symbolize_keys
@@ -356,6 +360,48 @@ module RailsNinja
       path.merge(query).merge(body)
     end
 
+    # Rack keeps only the last part when a multipart name repeats without "[]",
+    # but OpenAPI clients send arrays exactly that way ("files", "files").
+    # Re-parse the body so repeated bare names accumulate into arrays.
+    module RepeatedMultipartNames
+      def normalize_params(params, name, value, *rest)
+        return super unless params.key?(name) && !name.include?("[")
+
+        existing = params[name]
+        params[name] = existing.is_a?(Array) ? existing << value : [existing, value]
+        params
+      end
+    end
+
+    def multipart_parameters(schema_class)
+      rails_params = request.request_parameters
+      io = request.env["rack.input"]
+      # Rails' parse is already complete unless a list field could have lost repeated parts
+      list_fields = schema_class._fields.values.any? { |f| f.type.is_a?(Array) }
+      return rails_params if io.nil? || rails_params.empty? || !list_fields
+
+      parser = Rack::Utils.default_query_parser.dup.extend(RepeatedMultipartNames)
+
+      raw = if (pairs = request.env["rack.request.form_pairs"])
+              params = parser.make_params
+              pairs.each { |name, value| parser.normalize_params(params, name, value) }
+              params.to_params_hash
+            elsif io.respond_to?(:rewind)
+              io.rewind
+              # parse_multipart replaces the tempfile cleanup list; keep the ones from Rails' parse
+              earlier_tempfiles = Array(request.env["rack.tempfiles"])
+              parsed = Rack::Multipart.parse_multipart(request.env, parser) || {}
+              request.env["rack.tempfiles"] = earlier_tempfiles | Array(request.env["rack.tempfiles"])
+              parsed
+            else
+              raise Error, "multipart bodies need Rack >= 3.1 or a rewindable rack.input " \
+                           "(wrap the app in Rack::RewindableInput::Middleware)"
+            end
+
+      # Same step Rails applies to POST params: turns Rack's file hashes into UploadedFile.
+      ActionDispatch::Request::Utils.normalize_encode_params(raw)
+    end
+
     def decode_parameters(schema_class, parameters)
       Schema::ParameterDecoder.new(schema_class, parameters).call
     end

data/lib/rails_ninja/openapi/generator.rb

@@ -3,8 +3,16 @@
 module RailsNinja
   module OpenAPI
     class Generator
-      def initialize(api_class)
+      DEFAULT_VERSION = "3.2.0"
+      SUPPORTED_VERSION_PATTERN = /\A3\.(?:0|1|2)\.\d+\z/
+
+      def initialize(api_class, openapi_version: DEFAULT_VERSION)
+        unless openapi_version.match?(SUPPORTED_VERSION_PATTERN)
+          raise ArgumentError, "unsupported OpenAPI version: #{openapi_version.inspect} (expected 3.0.x, 3.1.x, or 3.2.x)"
+        end
+
         @api_class = api_class
+        @openapi_version = openapi_version
       end
 
       def to_hash
@@ -16,7 +24,7 @@ module RailsNinja
         end
 
         spec = {
-          openapi: "3.2.0",
+          openapi: @openapi_version,
           info: {
             title: @api_class._title || @api_class.name || "API",
             version: @api_class._version || "0.1.0",
@@ -124,14 +132,32 @@ module RailsNinja
       end
 
       def build_request_body(schema)
-        {
-          required: true,
-          content: {
-            "application/json" => {
-              schema: schema_ref(schema),
-            },
-          },
-        }
+        multipart = schema._fields.values.any? { |f| file_type?(f.type) }
+        reject_nested_files!(schema)
+        media_type = multipart ? "multipart/form-data" : "application/json"
+
+        { required: true, content: { media_type => { schema: schema_ref(schema) } } }
+      end
+
+      def file_type?(type)
+        type = type.first if type.is_a?(Array)
+        type.is_a?(Class) && type <= Types::File
+      end
+
+      # Nested objects travel as JSON strings inside multipart, which cannot carry a file.
+      def reject_nested_files!(schema, path = [], seen = Set.new)
+        return unless seen.add?(schema)
+
+        schema._fields.each do |name, field|
+          nested = Array(field.type).first
+          next unless nested.is_a?(Class) && nested <= Schema::Base
+
+          if nested._fields.values.any? { |f| file_type?(f.type) }
+            raise Error, "File fields are only supported at the top level of a request schema " \
+                         "(found under #{(path + [name]).join('.')})"
+          end
+          reject_nested_files!(nested, path + [name], seen)
+        end
       end
 
       def schema_ref(type)

data/lib/rails_ninja/schema/parameter_decoder.rb

@@ -8,9 +8,12 @@ module RailsNinja
 
       attr_reader :schema_class, :data
 
-      def initialize(schema_class, data)
+      # wrap_arrays: treat a lone value as a one-element list. Only safe for
+      # multipart, the one source where repeated names are preserved.
+      def initialize(schema_class, data, wrap_arrays: false)
         @schema_class = schema_class
         @data = data || {}
+        @wrap_arrays = wrap_arrays
       end
 
       def call
@@ -26,9 +29,13 @@ module RailsNinja
 
       def decode_value(value, type)
         if type.is_a?(Array)
+          value = Array.wrap(value) if @wrap_arrays
           value.is_a?(Array) ? value.map { |item| decode_value(item, type.first) } : value
         elsif type.is_a?(Class) && type <= Schema::Base
-          value.is_a?(Hash) ? self.class.new(type, value).call : value
+          # JSON already carries native types: validate it as-is, no form coercion.
+          return decode_json_object(value) if value.is_a?(::String)
+
+          value.is_a?(Hash) ? self.class.new(type, value, wrap_arrays: @wrap_arrays).call : value
         elsif type.is_a?(Class) && type <= Types::BaseScalar
           decode_scalar(value, type)
         else
@@ -47,6 +54,13 @@ module RailsNinja
         end
       end
 
+      # OpenAPI clients send nested objects in multipart/form bodies as JSON strings.
+      def decode_json_object(value)
+        MultiJson.load(value)
+      rescue MultiJson::ParseError
+        value
+      end
+
       def decode_integer(value)
         INTEGER_PATTERN.match?(value) ? Kernel.Integer(value, 10) : value
       end

data/lib/rails_ninja/schema/validator.rb

@@ -11,6 +11,8 @@ module RailsNinja
       end
 
       def call
+        return [{}, ["Expected object, got #{data.class}"]] unless data.respond_to?(:key?)
+
         errors = []
         validated = {}
 
@@ -77,6 +79,8 @@ module RailsNinja
       end
 
       def validate_schema(value, type)
+        return [nil, [": Expected object, got #{value.class}"]] unless value.respond_to?(:key?)
+
         result, errors = type.validate(value)
         [result, errors.map { |err| ".#{err}" }]
       end

data/lib/rails_ninja/tasks.rake

@@ -5,8 +5,9 @@ namespace :rails_ninja do
     desc "Generate OpenAPI JSON spec files for all registered APIs"
     task generate: :environment do
       output = ENV.fetch("OUTPUT", "public/openapi")
-      RailsNinja.generate_openapi(output: output)
-      puts "Generated OpenAPI specs in #{output}/"
+      openapi_version = ENV.fetch("OPENAPI_VERSION", RailsNinja::OpenAPI::Generator::DEFAULT_VERSION)
+      RailsNinja.generate_openapi(output: output, openapi_version: openapi_version)
+      puts "Generated OpenAPI #{openapi_version} specs in #{output}/"
     end
   end
 end

data/lib/rails_ninja/types/file.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  module Types
+    class File < BaseScalar
+      class << self
+        def ruby_classes
+          [ActionDispatch::Http::UploadedFile]
+        end
+
+        def openapi_schema
+          { type: "string", format: "binary" }
+        end
+      end
+    end
+  end
+end

data/lib/rails_ninja/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsNinja
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/rails_ninja.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "action_controller/metal"
+require "active_support/core_ext/array/wrap"
 require "active_support/core_ext/enumerable"
 require "rack"
 require "multi_json"
@@ -9,6 +10,7 @@ require_relative "rails_ninja/version"
 require_relative "rails_ninja/errors"
 require_relative "rails_ninja/types/base_scalar"
 require_relative "rails_ninja/types/boolean"
+require_relative "rails_ninja/types/file"
 require_relative "rails_ninja/types/float"
 require_relative "rails_ninja/types/int"
 require_relative "rails_ninja/types/string"
@@ -34,12 +36,12 @@ module RailsNinja
     @registered_apis ||= []
   end
 
-  def self.generate_openapi(output: "public/openapi")
+  def self.generate_openapi(output: "public/openapi", openapi_version: OpenAPI::Generator::DEFAULT_VERSION)
     require "fileutils"
     FileUtils.mkdir_p(output)
 
     registered_apis.each do |api_class|
-      generator = OpenAPI::Generator.new(api_class)
+      generator = OpenAPI::Generator.new(api_class, openapi_version: openapi_version)
 
       filename = api_class.name.split("::").last
         .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')

data/rails_ninja.gemspec

@@ -26,10 +26,10 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "actionpack", ">= 7.0"
-  spec.add_dependency "activesupport", ">= 7.0"
+  spec.add_dependency "actionpack", ">= 7.1"
+  spec.add_dependency "activesupport", ">= 7.1"
   spec.add_dependency "multi_json", "~> 1.15"
-  spec.add_dependency "rack", ">= 2.0"
+  spec.add_dependency "rack", ">= 2.2.4"
 
   spec.add_development_dependency "minitest", ">= 5.0"
   spec.add_development_dependency "rack-test", ">= 2.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_ninja
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Benjamin Urrutia
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.2.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.2.4
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -137,6 +137,7 @@ files:
 - lib/rails_ninja/tasks.rake
 - lib/rails_ninja/types/base_scalar.rb
 - lib/rails_ninja/types/boolean.rb
+- lib/rails_ninja/types/file.rb
 - lib/rails_ninja/types/float.rb
 - lib/rails_ninja/types/int.rb
 - lib/rails_ninja/types/string.rb