ratalada-contrib 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d30cdd4308ec4495bd965180994b34d26439ba7f0127398562eb381cc8eccc95
-  data.tar.gz: bec8c448d5e15fb2b25478f1cb31e299514fdd2ef9067c81681244e54a0bdae1
+  metadata.gz: 684119c7ffaadc33fd820a4afad88d7c814e20d95cb397e3b7f200a48b89c252
+  data.tar.gz: de2d2c52778288e334bb95a5bb27420e062714d35924a8db5ab98d4b15491f93
 SHA512:
-  metadata.gz: e72898aabde80621c44d55d2f12a13dcd9210d65c5690aaa444f0b867b81354300e2c6904fbb60e6ddf9c97a784b918616c8dfd3c45ad55ffd84df5fb2d4e19f
-  data.tar.gz: 97151f7ad7867f3856c7da8971b2d9b63318716bb10319f9865a7c12b92dc61c1559756d5a50db14c4c846ed9f777307e091629545e7ad8a68d676c860636b6d
+  metadata.gz: c22ec36581b747dbeccacca95a0ae3d492286682365c5b79d234bfc9ad5dbaed4fb9fd9af5fe1f18933f7823109ce887bde7b6da6f3742636e11e9d91fdd743f
+  data.tar.gz: 5aeb45e1b6984aef2523b41a929d5c7bf3e90df94442c8dc7c5ca8f4366c0aa5feb46e7cb4695171fd922bb0bbe4074cc7bed3cc69f1694f9f48a93b68499370

data/lib/ratalada/contrib/router/file_based/grape_adapter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "grape"
+
+require_relative "../file_based"
+
+module Ratalada
+  module Contrib
+    module Router
+      module FileBased
+        # The Grape half of file-based routing. Each route file is built the way
+        # `Server.run`'s block is — class_eval'd into a Grape::API subclass, file
+        # contents in place of the block — and Grape then re-hosts that built API
+        # under the prefix its path spelled:
+        #
+        #   parent.mount(file_api => "/teams/:team/settings")
+        #
+        # `mount` is Grape's own (DSL::Routing#mount): it stores the mount path on
+        # the child's settings and replays its endpoints into the parent, so the
+        # file's `get "/members"` compiles as "/teams/:team/settings/members" with
+        # :team in params. Nothing about Grape's path handling is reimplemented.
+        module GrapeAdapter
+          module_function
+
+          # Returns the Grape::API subclass with every route file mounted.
+          def build(directory)
+            Class.new(::Grape::API).tap do |app|
+              FileBased.build_map(directory).each do |prefix, paths|
+                app.mount(build_file(paths) => mount_path(prefix))
+              end
+            end
+          end
+
+          # One route file and the layouts above it, built exactly like a
+          # Server.run block: the layouts' `helpers`, `before` blocks and `use`
+          # calls land in the same API as the file's own routes.
+          def build_file(paths)
+            Class.new(::Grape::API).tap do |api|
+              paths.each { |path| api.class_eval(File.read(path), path, 1) }
+            end
+          end
+
+          # A root file has no prefix; Grape spells that mount point "/".
+          def mount_path(prefix)
+            case prefix
+            when "" then "/"
+            else prefix
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratalada/contrib/router/file_based/hanami_adapter.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "hanami/api"
+
+require_relative "../file_based"
+
+module Ratalada
+  module Contrib
+    module Router
+      module FileBased
+        # The Hanami half of file-based routing. Hanami::API compiles routes
+        # straight into the router's trie, so there is no route list to rewrite
+        # afterwards the way Sinatra's Mustermann patterns can be — what it has
+        # instead is `scope`, the prefix its own router applies while routes are
+        # being defined (Hanami::Router#scope). So the file is evaluated inside
+        # the scope its path spells, which is the same result one step earlier:
+        #
+        #   # app/teams/[team]/settings/index.rb
+        #   get "/members" do
+        #     "members of #{params[:team]}"
+        #   end
+        #
+        # becomes "/teams/:team/settings/members". The file's blocks still run in
+        # the app's own Block::Context, so `params`, `halt` and any `helpers` are
+        # the ones the app defines.
+        module HanamiAdapter
+          module_function
+
+          # Returns the rack app: a Hanami::API subclass instance, as the Hanami
+          # frontend builds it, with every route file evaluated into it.
+          def build(directory)
+            app = Class.new(::Hanami::API)
+
+            FileBased.build_map(directory).each do |prefix, paths|
+              mount_route_file(app, prefix, paths)
+            end
+
+            app.new
+          end
+
+          # The layouts above the file are evaluated in the same scope, ahead of
+          # it, so what they add (`use`, extra routes) applies to that prefix.
+          def mount_route_file(app, prefix, paths)
+            sources = paths.map { |path| [File.read(path), path] }
+
+            # `scope` instance_evals its block on the router, so the file's own
+            # `get`/`post` calls are the router's, under the prefix.
+            app.router.scope(prefix) do
+              sources.each { |source, path| instance_eval(source, path, 1) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratalada/contrib/router/file_based/sinatra_adapter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "mustermann"
+require "rack"
+require "sinatra/base"
+
+require_relative "../file_based"
+
+module Ratalada
+  module Contrib
+    module Router
+      module FileBased
+        # The Sinatra half of file-based routing: each route file is built the
+        # same way `Server.run`'s block is — class_eval'd into a Sinatra::Base
+        # subclass — with the file's contents as the input instead of a block. So
+        # a file is ordinary Sinatra:
+        #
+        #   # app/teams/[team]/settings/index.rb
+        #   get "/members" do
+        #     "members of #{params[:team]}"
+        #   end
+        #
+        # Building it yields an app object whose compiled routes are Mustermann
+        # patterns, and those are what the prefix from FileBased gets prepended
+        # to — Mustermann concatenates patterns itself, so "/teams/:team" +
+        # "/members" stays one pattern with both captures.
+        #
+        # The rewritten apps are then chained: a Sinatra app used as rack
+        # middleware forwards the request onward when none of its own routes
+        # matched (Base#route_missing), so the first file that spells the path
+        # answers and the last one falls through to a plain 404.
+        module SinatraAdapter
+          NOT_FOUND = lambda do |_env|
+            [404, { "content-type" => "text/plain" }, ["Not Found"]]
+          end
+
+          module_function
+
+          def build(directory)
+            apps = FileBased.build_map(directory).map do |prefix, paths|
+              prefix_routes(build_file(paths), prefix)
+            end
+
+            # ponytail: one Sinatra app (and its middleware stack) per file, walked
+            # in order per request. Collapse into one app class if a fat tree ever
+            # shows up in a profile.
+            ::Rack::Builder.new.tap do |builder|
+              apps.each { |app| builder.use(app) }
+              builder.run(NOT_FOUND)
+            end.to_app
+          end
+
+          # One route file and the layouts above it, built exactly like a
+          # Server.run block: the layouts' `helpers`, `before` filters and `use`
+          # calls land in the same class as the file's own routes.
+          def build_file(paths)
+            Class.new(::Sinatra::Base).tap do |app|
+              paths.each { |path| app.class_eval(File.read(path), path, 1) }
+            end
+          end
+
+          # Rewrites every route the built app holds to sit under `prefix`.
+          def prefix_routes(app, prefix)
+            pattern = ::Mustermann.new(prefix, type: :sinatra)
+
+            app.routes.each_value do |signatures|
+              signatures.map! do |(route, conditions, wrapper)|
+                [nest(pattern, route), conditions, wrapper]
+              end
+            end
+
+            app
+          end
+
+          # A file's own "/" is the prefix itself, not the prefix with a trailing
+          # slash, so it is the one pattern that replaces rather than extends —
+          # as is any route in a file that sits at the root, where the prefix is
+          # empty.
+          def nest(prefix, route)
+            case [prefix.to_s, route.to_s]
+            in ["", _] then route
+            in [_, "/"] then prefix
+            else prefix + route
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratalada/contrib/router/file_based.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Ratalada
+  module Contrib
+    module Router
+      # Turns an expo-router style directory of route files into an ordered map
+      # of `prefix => path`. The prefix is what the file's own routes hang off:
+      # a file says `get "/members" do ... end` and the adapter mounts that under
+      # the prefix its path spells, so each adapter only has to decide how it
+      # loads a file and how it spells a placeholder.
+      #
+      #   Ratalada::Contrib::Router::FileBased.build_map("app")
+      #   # => { "" => "app/index.rb",
+      #   #      "/organizations/:slug" => "app/organizations/[slug]/index.rb", ... }
+      #
+      #   FileBased.join("/organizations/:slug", "/users")  # => "/organizations/:slug/users"
+      #   FileBased.join("/organizations/:slug", "/")       # => "/organizations/:slug"
+      #   FileBased.join("", "/")                           # => "/"
+      #
+      # Conventions, all borrowed from expo-router:
+      #
+      #   index.rb          the directory itself           app/teams/index.rb => /teams
+      #   [slug].rb         a single dynamic segment       => /:slug
+      #   [...rest].rb      a catch-all                    => /*rest
+      #   (group)/          grouping only, not a segment   app/(marketing)/docs.rb => /docs
+      #   +not-found.rb     the fallback                   => /*
+      #   _layout.rb        not a route of its own: its contents are evaluated
+      #                     into every route file below it, outermost first, so
+      #                     a layout is whatever the file could have written for
+      #                     itself (helpers, filters, middleware, extra routes).
+      #                     Any other `_` file or directory is ignored outright.
+      #
+      # A map value is the list of files to evaluate, in order: the `_layout.rb`
+      # of each directory from the root down, then the route file itself.
+      #
+      # The map is ordered most specific first (static segments before dynamic,
+      # dynamic before catch-all, +not-found last), so an adapter can define the
+      # routes in iteration order under a first-match-wins router.
+      module FileBased
+        NOT_FOUND = "+not-found"
+        LAYOUT = "_layout.rb"
+
+        module_function
+
+        def build_map(directory, placeholder: ":%s", catch_all: "*%s")
+          root = File.expand_path(directory)
+
+          entries = Dir.glob("**/*.rb", base: root).filter_map do |relative|
+            segments = route_segments(relative)
+
+            unless segments.nil?
+              [pattern(segments, placeholder, catch_all), files(root, relative), segments]
+            end
+          end
+
+          entries
+            .sort_by { |(pattern, _files, segments)| [specificity(segments), pattern] }
+            .to_h { |(pattern, paths, _segments)| [pattern, paths] }
+        end
+
+        # The route file, with the `_layout.rb` of every directory above it in
+        # front — outermost first, so an inner layout is evaluated last and can
+        # override what an outer one set up.
+        def files(root, relative)
+          directories = relative.split("/")[0..-2]
+
+          layouts = directories.each_index.map do |index|
+            File.join(root, *directories[0..index], LAYOUT)
+          end
+
+          [File.join(root, LAYOUT), *layouts].select { |path| File.file?(path) }
+            .push(File.join(root, relative))
+        end
+
+        # The route segments of a file, or nil when the file is not a route.
+        def route_segments(relative)
+          unless relative.split("/").any? { |segment| segment.start_with?("_") }
+            "/#{relative.delete_suffix(".rb")}"
+              .delete_suffix("/index")
+              .split("/")
+              .drop(1)
+              .reject { |segment| segment.match?(/\A\(.*\)\z/) }
+          end
+        end
+
+        def pattern(segments, placeholder, catch_all)
+          spelled = segments.map do |segment|
+            case segment
+            when /\A\[\.\.\.(.+)\]\z/ then format(catch_all, Regexp.last_match(1))
+            when /\A\[(.+)\]\z/ then format(placeholder, Regexp.last_match(1))
+            when NOT_FOUND then format(catch_all, "unmatched")
+            else segment
+            end
+          end
+
+          spelled.map { |segment| "/#{segment}" }.join
+        end
+
+        # Hangs one of a file's own routes off the prefix its path spelled.
+        def join(prefix, route)
+          "#{prefix}#{route.delete_suffix("/")}".sub(/\A\z/, "/")
+        end
+
+        # Sorts static segments ahead of dynamic ones at the same depth, and the
+        # +not-found fallback behind everything.
+        def specificity(segments)
+          segments.map do |segment|
+            case segment
+            when NOT_FOUND then 3
+            when /\A\[\.\.\..+\]\z/ then 2
+            when /\A\[.+\]\z/ then 1
+            else 0
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratalada/contrib/version.rb

@@ -2,6 +2,6 @@
 
 module Ratalada
   module Contrib
-    VERSION = "2.0.1"
+    VERSION = "2.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratalada-contrib
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Nathan K
@@ -41,6 +41,10 @@ files:
 - lib/ratalada/contrib/inertia/helpers.rb
 - lib/ratalada/contrib/inertia/middleware.rb
 - lib/ratalada/contrib/inertia/response.rb
+- lib/ratalada/contrib/router/file_based.rb
+- lib/ratalada/contrib/router/file_based/grape_adapter.rb
+- lib/ratalada/contrib/router/file_based/hanami_adapter.rb
+- lib/ratalada/contrib/router/file_based/sinatra_adapter.rb
 - lib/ratalada/contrib/version.rb
 - lib/ratalada/contrib/vite.rb
 homepage: https://github.com/n-at-han-k/ratalada