rails_ninja 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 99a76115680edb87523d0a819db195e01041bd3ed09d6bfabc0226963505f2fc
+  data.tar.gz: bedb6982e08bd7c32864052ef14d130d0f555503006ceef2a3a0f557e6165912
+SHA512:
+  metadata.gz: e21f4e9ea17198535d38b26a0f7e46d522cb09f84885eee3a92dc4e6c73e16606d446784262bff3841cae1578d3d88ce46ae1c66a6615564f1d2b4139a2ae891
+  data.tar.gz: dd8f2cbee49dd08ecbbd95fb86ebb2aef82db49eb37f477db1094441e9c39104e7c15b793bba91abf1f6310ecf7e76237994bf16f60bc1ecaa113d57d8d1c31f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fintual Open Source
+
+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,276 @@
+# Rails Ninja
+
+Rails Ninja is a small Rails API framework inspired by
+[Django Ninja](https://django-ninja.dev). It provides a route DSL, schema-based
+request validation and response serialization, and generated OpenAPI
+documentation.
+
+Rails Ninja requires Ruby 3 or newer and Rails 7 or newer.
+
+## Installation
+
+```ruby
+gem "rails_ninja"
+```
+
+Then run `bundle install`.
+
+## Structure
+
+Rails Ninja has three building blocks:
+
+- `RailsNinja::API` is the root Rack application and OpenAPI document.
+- `RailsNinja::EndpointGroup` groups related routes under a prefix and tag.
+- `RailsNinja::Endpoint` keeps one endpoint and its schemas in a standalone
+  class.
+
+An API can define routes inline, include standalone Endpoints, and mount
+EndpointGroups. An API cannot mount another API: mount independent APIs
+separately in Rails when they need separate documentation.
+
+### Endpoint
+
+```ruby
+# app/api/endpoints/list_users.rb
+class ListUsers < RailsNinja::Endpoint
+  schema :UserOut do
+    field :id, RailsNinja::Types::Int
+    field :name, RailsNinja::Types::String
+    field :email, RailsNinja::Types::String
+  end
+
+  get "/", response: [UserOut]
+  def handle
+    User.all
+  end
+end
+```
+
+### EndpointGroup
+
+```ruby
+# app/api/endpoint_groups/users_group.rb
+class UsersGroup < RailsNinja::EndpointGroup
+  tags "Users"
+  ninja_headers "X-Request-ID"
+
+  include_endpoint ListUsers
+end
+```
+
+Groups may also define routes directly or mount other EndpointGroups.
+
+### API
+
+```ruby
+# app/api/application_api.rb
+class ApplicationApi < RailsNinja::API
+  title "My Service"
+  version "1.0"
+
+  mount UsersGroup, prefix: "/users"
+end
+```
+
+Mount the API in Rails:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount ApplicationApi => "/api"
+end
+```
+
+Rails Ninja adds `app/api` to Rails' autoload and eager-load paths. The example
+exposes:
+
+- `GET /api/users`
+- `GET /api/openapi.json`
+- `GET /api/docs`
+
+The endpoint verbs are `get`, `post`, `put`, `patch`, and `delete`. A
+verb declaration applies to the method defined immediately after it.
+
+## Schemas
+
+```ruby
+schema :ItemIn do
+  field :name, RailsNinja::Types::String
+  field :price, RailsNinja::Types::Float
+  field :active, RailsNinja::Types::Boolean, required: false, default: true
+  field :tags, [RailsNinja::Types::String], required: false, default: []
+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.
+
+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
+requests return `422` with an `errors` array, and validated values are merged
+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.
+
+Schemas may also be standalone:
+
+```ruby
+class ItemOut < RailsNinja::Schema::Base
+  field :id, RailsNinja::Types::Int
+  field :name, RailsNinja::Types::String
+end
+```
+
+Use `one_of` for polymorphic response fields and OpenAPI schemas:
+
+```ruby
+schema :Pet do
+  field :animal, one_of(Cat, Dog, discriminator: :kind)
+end
+```
+
+The discriminator is optional. Each variant needs a default value for its
+discriminator field to appear in the OpenAPI mapping.
+
+## Requests and responses
+
+```ruby
+post "/items", request: ItemIn, response: ItemOut
+def create_item
+  Item.create!(params.slice(:name, :price, :active, :tags))
+end
+```
+
+`response: ItemOut` serializes one object; `response: [ItemOut]` serializes a
+collection. Without a response schema, a normal return value is not rendered.
+Use `render_json` or `head` for explicit responses:
+
+```ruby
+get "/health"
+def health
+  render_json({ status: "ok" })
+end
+
+delete "/items/:id"
+def delete_item
+  Item.find(params[:id]).destroy!
+  head 204
+end
+```
+
+Document multiple statuses with `responses:`:
+
+```ruby
+get "/items/:id", responses: { 200 => ItemOut, 404 => ErrorOut }
+def show_item
+  item = Item.find_by(id: params[:id])
+  return render_json({ error: "Not found" }, status: 404) unless item
+
+  item
+end
+```
+
+Only the `200` schema is serialized automatically. Other statuses must be
+committed with `render_json` or `head`.
+
+## Callbacks, headers, and tags
+
+Before actions run from the API through the matched group branch to the
+Endpoint. They may halt processing with `head` or `render_json`:
+
+```ruby
+class InternalApi < RailsNinja::API
+  before_action :authenticate!
+  ninja_headers "X-API-Key"
+
+  def authenticate!
+    head 401 unless valid_api_key?(request.headers["X-API-Key"])
+  end
+end
+```
+
+Headers can also be declared per route:
+
+```ruby
+get "/items", headers: [{ name: "X-Request-ID", required: false }]
+def list_items
+  # ...
+end
+```
+
+Endpoint-level headers override class-level headers with the same name. Tags on
+an EndpointGroup apply to its included Endpoints and determine their Swagger UI
+group and `operationId` prefix.
+
+## OpenAPI authorization
+
+Declare security metadata on the root API. Runtime authentication remains the
+responsibility of a before action.
+
+```ruby
+class InternalApi < RailsNinja::API
+  openapi_security_scheme(
+    :ApiKeyAuth,
+    type: "apiKey",
+    in: "header",
+    name: "X-API-Key"
+  )
+  openapi_security :ApiKeyAuth
+end
+```
+
+HTTP bearer schemes are also supported:
+
+```ruby
+openapi_security_scheme :UserAuth, type: "http", scheme: "bearer"
+openapi_security :UserAuth
+```
+
+## Endpoint options
+
+Routes accept `summary:`, `tags:`, `headers:`, and `deprecated_paths:`:
+
+```ruby
+get "/items",
+  summary: "List items",
+  deprecated_paths: ["/old_items"]
+def list_items
+  # ...
+end
+```
+
+Deprecated paths remain routable and are marked as deprecated in OpenAPI.
+
+Set `server "https://api.example.com"` on an API to declare its server URL, or
+`docs false` to disable `/docs` and `/openapi.json`.
+
+## Static OpenAPI files
+
+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
+```
+
+The default output directory is `public/openapi`. File names come from the API
+class name, such as `PublicApi` to `public_api.json`.
+
+## Development
+
+Install dependencies and run the test suite:
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+CI tests every compatible combination of Action Pack and Active Support 7.0
+through 8.1 with MRI Ruby 3.0 through 4.0. Each lane resolves the latest patch
+release in its minor series.
+
+## License
+
+MIT

data/lib/rails_ninja/api.rb

@@ -0,0 +1,388 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  class API < EndpointGroup
+    FORM_MEDIA_TYPES = %w[application/x-www-form-urlencoded multipart/form-data].freeze
+
+    abstract!
+    include ActionController::Instrumentation
+
+    # --- Class-level DSL ---
+
+    class << self
+      # Config DSL
+      def title(value = nil)
+        if value
+          @_title = value
+        else
+          @_title
+        end
+      end
+
+      def _title
+        @_title
+      end
+
+      def version(value = nil)
+        if value
+          @_version = value
+        else
+          @_version
+        end
+      end
+
+      def _version
+        @_version
+      end
+
+      def server(value = nil)
+        if value
+          @_server = value
+        else
+          @_server
+        end
+      end
+
+      def _server
+        @_server
+      end
+
+      def docs(enabled = nil)
+        if enabled.nil?
+          @_docs_enabled
+        else
+          @_docs_enabled = enabled
+        end
+      end
+
+      def _docs_enabled?
+        return @_docs_enabled unless @_docs_enabled.nil?
+
+        true
+      end
+
+      def openapi_security_scheme(name, **options)
+        _openapi_security_schemes[name.to_s] = options
+      end
+
+      def _openapi_security_schemes
+        @_openapi_security_schemes ||= {}
+      end
+
+      def openapi_security(*names)
+        if names.any?
+          @_openapi_security = names.flatten.map(&:to_s)
+        else
+          @_openapi_security
+        end
+      end
+
+      def _openapi_security
+        @_openapi_security || []
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@_openapi_security_schemes, _openapi_security_schemes.transform_values(&:dup))
+        subclass.instance_variable_set(:@_openapi_security, _openapi_security.dup)
+        RailsNinja.registered_apis << subclass
+      end
+
+      # Rack interface — makes this class usable with Rack::Test and as a Rack app
+      def call(env)
+        path = env["PATH_INFO"] || "/"
+        verb = env["REQUEST_METHOD"]
+
+        if _docs_enabled?
+          return Response.html(Swagger::UI.html(spec_url: "./openapi.json")) if verb == "GET" && path == "/docs"
+          return Response.json(OpenAPI::Generator.new(self).to_hash) if verb == "GET" && path == "/openapi.json"
+        end
+
+        match = _match_route(verb, path)
+        return Response.error("Not Found", status: 404) unless match
+
+        endpoint, full_path, dispatch_name, _regex, mount_path = match
+        path_params = _extract_path_params(full_path, path)
+        env["action_dispatch.request.path_parameters"] = path_params.merge(
+          controller: controller_path || "rails_ninja",
+          action: dispatch_name.to_s
+        )
+        env["rails_ninja.endpoint"] = endpoint
+        env["rails_ninja.mount_path"] = mount_path
+
+        req = ActionDispatch::Request.new(env)
+        res = make_response!(req)
+        dispatch(dispatch_name.to_s, req, res)
+      end
+
+      def _match_route(verb, path)
+        _cached_dispatch_table.find do |_ep, _full_path, _dispatch_name, regex|
+          _ep.verb.to_s.upcase == verb.upcase && regex.match?(path)
+        end
+      end
+
+      def _cached_dispatch_table
+        @_cached_dispatch_table ||= _dispatch_table
+      end
+
+      def _extract_path_params(full_path, actual_path)
+        regex = _path_to_regex(full_path)
+        match = regex.match(actual_path)
+        match ? match.named_captures.transform_keys(&:to_sym) : {}
+      end
+
+      # Builds a flat dispatch table: [operation, full_path, dispatch_name, regex, mount_path]
+      # For the API's own endpoints, dispatch_name == handler.
+      # For endpoints of mounted groups, dispatch_name is the unique method defined on the API.
+      # mount_path is the branch of group classes leading to the operation — the same operation
+      # object can appear on several branches when a group is mounted more than once.
+      def _dispatch_table(group_class = self, prefix = "/", mount_path = nil)
+        mount_path ||= [group_class]
+        results = []
+
+        group_class._endpoints.each do |endpoint|
+          full_path = normalize_route_path("#{prefix}/#{endpoint.path}")
+          regex = _path_to_regex(full_path)
+          dispatch_name = if group_class == self
+                            endpoint.handler
+                          else
+                            _unique_handler_name(endpoint.api_class, endpoint.display_handler)
+                          end
+          results << [endpoint, full_path, dispatch_name, regex, mount_path]
+        end
+
+        group_class._mounted_groups.each do |mounted|
+          sub_prefix = normalize_route_path("#{prefix}/#{mounted[:prefix]}")
+          results.concat(_dispatch_table(mounted[:group_class], sub_prefix, mount_path + [mounted[:group_class]]))
+        end
+
+        results
+      end
+
+      def _path_to_regex(path)
+        pattern = "^" + path.gsub(/:(\w+)/, '(?<\1>[^/]+)') + "$"
+        Regexp.new(pattern)
+      end
+
+      # Draw Rails routes for all endpoints in this API (including mounted groups)
+      def draw_routes(router_context, prefix: "/")
+        register_as_controller!
+
+        _dispatch_table(self, prefix).each do |endpoint, full_path, dispatch_name, _regex|
+          router_context.match full_path,
+                               to: "#{controller_path}##{dispatch_name}",
+                               via: endpoint.verb
+        end
+
+        draw_docs_routes(router_context, prefix) if _docs_enabled?
+      end
+
+      # Register this class so Rails can find it via controller_path + "Controller"
+      def register_as_controller!
+        return if @_registered_as_controller
+
+        # Rails looks up "controller_path_controller".camelize, so we register an alias
+        controller_class_name = "#{name}Controller"
+        parts = controller_class_name.split("::")
+        const_name = parts.pop
+        namespace = parts.empty? ? Object : parts.join("::").constantize
+        namespace.const_set(const_name, self) unless namespace.const_defined?(const_name, false)
+        @_registered_as_controller = true
+      end
+
+      private
+
+      def draw_docs_routes(router_context, prefix)
+        api_class = self
+        docs_path = normalize_route_path("#{prefix}/docs")
+        openapi_path = normalize_route_path("#{prefix}/openapi.json")
+
+        router_context.match docs_path, to: ->(_env) {
+          body = Swagger::UI.html(spec_url: "./openapi.json")
+          [200, { "content-type" => "text/html" }, [body]]
+        }, via: :get
+
+        router_context.match openapi_path, to: ->(_env) {
+          generator = OpenAPI::Generator.new(api_class)
+          [200, { "content-type" => "application/json" }, [generator.to_json]]
+        }, via: :get
+      end
+
+      def normalize_route_path(path)
+        "/" + path.squeeze("/").gsub(%r{^/|/$}, "")
+      end
+    end
+
+    # Let Instrumentation wrap this so "Processing"/"Completed" logs appear
+    def process_action(action_name, *args)
+      @_ninja_endpoint, @_ninja_mount_path = find_route(action_name)
+
+      unless @_ninja_endpoint
+        head(:not_found)
+        return
+      end
+
+      super
+    rescue ValidationError => e
+      self.status = 422
+      self.content_type = "application/json"
+      self.response_body = [MultiJson.dump({ errors: e.errors })]
+    rescue NotFoundError => e
+      self.status = 404
+      self.content_type = "application/json"
+      self.response_body = [MultiJson.dump({ error: e.message })]
+    end
+
+    # Override send_action (called by AbstractController::Base#process_action via super chain)
+    # to inject before_actions, validation, and result rendering
+    def send_action(action_name)
+      endpoint = @_ninja_endpoint
+
+      @_ninja_handler_instance = build_group_instance(endpoint.api_class) unless endpoint.api_class == self.class
+      run_ancestor_before_actions(endpoint)
+      unless performed?
+        run_before_actions(endpoint)
+      end
+      unless performed?
+        validate_request!(endpoint)
+      end
+      unless performed?
+        result = super
+        render_result(result, endpoint) unless performed?
+      end
+    end
+
+    private
+
+    def find_route(action_name)
+      # When dispatched via API.call, the exact route is stored in the env
+      stored = request.env["rails_ninja.endpoint"]
+      return [stored, request.env["rails_ninja.mount_path"]] if stored
+
+      # When dispatched via Rails routes, match by the dispatch method name
+      action_sym = action_name.to_sym
+      rows = self.class._cached_dispatch_table.select do |_op, _path, dispatch_name, _regex, _mount_path|
+        dispatch_name == action_sym
+      end
+      row = rows.one? ? rows.first : disambiguate_row(rows)
+      return [nil, nil] unless row
+
+      [row[0], row[4]]
+    end
+
+    # A dispatch name can map to several table rows (a group mounted more than
+    # once, or deprecated path aliases); pick the row whose path matches the
+    # Rails route that dispatched this request.
+    def disambiguate_row(rows)
+      pattern = request.respond_to?(:route_uri_pattern) && request.route_uri_pattern&.delete_suffix("(.:format)")
+      return rows.first unless pattern
+
+      rows.select { |_op, full_path, _dispatch_name, _regex, _mount_path| pattern.end_with?(full_path) }
+        .max_by { |_op, full_path, _dispatch_name, _regex, _mount_path| full_path.length } || rows.first
+    end
+
+    def run_ancestor_before_actions(endpoint)
+      groups = @_ninja_mount_path || [self.class]
+      groups.each do |group|
+        next if group == endpoint.api_class
+        next if group._before_actions.empty?
+
+        break if run_actions_list(group._before_actions, build_group_instance(group))
+      end
+    end
+
+    def run_before_actions(endpoint)
+      if endpoint.api_class == self.class
+        run_actions_list(endpoint.api_class._before_actions)
+      else
+        run_actions_list(endpoint.api_class._before_actions, @_ninja_handler_instance)
+      end
+    end
+
+    def build_group_instance(group)
+      instance = group.new
+      instance.set_request!(request)
+      instance.set_response!(response)
+      instance
+    end
+
+    def run_actions_list(actions, group_instance = nil)
+      actions.each do |action|
+        if group_instance && action.is_a?(Symbol)
+          group_instance.public_send(action)
+
+          if group_instance.performed?
+            self.status = group_instance.status
+            self.content_type = group_instance.content_type
+            self.response_body = group_instance.response_body
+          end
+        elsif action.is_a?(Symbol)
+          public_send(action)
+        else
+          instance_exec(&action)
+        end
+
+        break if performed?
+      end
+
+      performed?
+    end
+
+    def validate_request!(endpoint)
+      return unless endpoint.request_schema
+
+      input = request_input(endpoint.request_schema)
+      validated, errors = endpoint.request_schema.validate(input)
+
+      if errors.empty?
+        params.merge!(validated)
+        return
+      end
+
+      self.status = 422
+      self.content_type = "application/json"
+      self.response_body = [MultiJson.dump({ errors: errors })]
+    end
+
+    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)
+               decode_parameters(schema_class, request.request_parameters)
+             else
+               request.request_parameters.deep_symbolize_keys
+             end
+
+      path.merge(query).merge(body)
+    end
+
+    def decode_parameters(schema_class, parameters)
+      Schema::ParameterDecoder.new(schema_class, parameters).call
+    end
+
+    def render_result(result, endpoint)
+      if result.is_a?(Array) && result.length == 3 && result[0].is_a?(Integer)
+        self.status = result[0]
+        result[1].each { |k, v| headers[k] = v }
+        self.response_body = result[2]
+      elsif result.is_a?(Integer) && result.between?(100, 599)
+        head result
+      elsif endpoint.response_schema
+        body = if endpoint.response_is_array?
+                 endpoint.response_schema.first.serialize_many(result)
+               else
+                 endpoint.response_schema.serialize(result)
+               end
+        self.status = 200
+        self.content_type = "application/json"
+        self.response_body = [MultiJson.dump(body)]
+      else
+        # Nothing was rendered explicitly and no response schema is declared:
+        # return an empty body instead of serializing whatever the handler
+        # happened to return (e.g. a job object from perform_later).
+        self.status = 200
+        self.response_body = []
+      end
+    end
+  end
+end

data/lib/rails_ninja/endpoint.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RailsNinja
+  class Endpoint < EndpointGroup
+  end
+end