ratalada 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d0e58c60b99a4b05777a6089c484f2104f85924694cfe0b5c0ef543a03634c7
-  data.tar.gz: d04a10b62a3f33a00489234bbb0db780517a54c7569c83dfd098cee69a3b2f5f
+  metadata.gz: 1da8d4c6eff98bad680c6e3da80c2d452b54711c1d2e2fe5b9de11500640f0a9
+  data.tar.gz: 9fae4c8b7aa84cc4ccf69017779f24fb011491a7143c3abb9332483db25489e5
 SHA512:
-  metadata.gz: 616cb51549da081369ce6df606e8c9188900b20fc7dc5344b045eaf8ab0618edc8f1cba92fd21be24c59cae0370b2fdfe6729e56e1bf93562b118ebd2f75f4e4
-  data.tar.gz: f834abb138626a902d8c4947183bca135d0ddf6ab9c8ed92a68b6ba08cc45666edb5f9f55611b50f365e4adbb23c20d621c8fdab2a532a1721c0d0e06e0642e3
+  metadata.gz: 6af7b845bd465ede4788967478ad9e67be55e3a2708000f2678a3a4ded46d3b024778d2828bb546e01f9e618fd8a43c1566bf46bdac2b1dff760d65105f3892a
+  data.tar.gz: '08bc22a824af6bacdfadc7b6546d0b8c9f116b22c8efc358f4cd7bc97cbe7652a59f23a9beb44616e87b5a3ae8f90a22628d02a1fd6dbf9b7460533336b137c1'

data/README.md

@@ -253,6 +253,11 @@ gem kit changelog --write --gem ratalada-roda
 gem kit release --gem ratalada-roda      # gate, build, push, tag
 ```
 
+## Why
+
+Spurred on by things like [this post](https://blainsmith.com/articles/just-fucking-use-go/), and just how easy it is to create servers with [hono](https://hono.dev/) or agents with [volt](https://github.com/voltagent/voltagent), which makes me irrationally angry that ruby hasn't more libraries like this considering it's WELL beyond javascript in it's flexibility as a language.
+[This post is great](https://www.toptal.com/developers/ruby/api-with-sinatra-and-sequel-ruby-tutorial), but it shuold be even simpler.
+
 ## License
 
 [MIT](LICENSE)

data/lib/ratalada/async.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "async/http/server"
+require "async/http/endpoint"
+require "protocol/http"
+require "protocol/url"
+require "protocol/rack/adapter"
+require_relative "protocol_http_ext"
+require_relative "../ratalada"
+
+module Ratalada
+  module Frontends
+    # Frontends::Routes, in Protocol::HTTP terms: the same Server.run block,
+    # the same handler kinds, no rack in the middle. Requiring ratalada/async
+    # installs it in place of the rack router, because Async::HTTP::Server
+    # already speaks this protocol and the adapter between them exists only to
+    # translate for a frontend that does not.
+    #
+    # The block is handed the server's own Protocol::HTTP::Request. It sees
+    # the same [verb, path] and {verb:, path:, query:} it sees on any other
+    # backend (ratalada/protocol_http_ext teaches that class the patterns),
+    # and #body is the body as it arrived rather than a String read out of it.
+    # What it does not see is Rack::Request: no cookies, no session, no
+    # form-body params, no Rack::Utils helpers in scope. Query params are
+    # there as #params; the rest is rack's, so require a rack frontend --
+    # ratalada/sinatra, or Frontends::Routes back again -- if you want them.
+    module ProtocolRoutes
+      # Tells the async backend to hand the app to Async::HTTP::Server whole
+      # rather than wrapping it in Protocol::Rack::Adapter.
+      def self.rack? = false
+
+      def self.build(block) = App.new(block)
+
+      # Server.use needs nothing special here: it chains
+      # `klass.new(inner, *args)`, which is exactly
+      # Protocol::HTTP::Middleware's interface -- `new(delegate)` answering
+      # `call(request)`. So middleware on this frontend is Protocol::HTTP
+      # middleware, chained with no adapter anywhere. Rack middleware belongs
+      # to a rack frontend, where the backend adapts the lot in one go.
+
+      class App
+        def initialize(router)
+          @router = router
+        end
+
+        # The request is the server's own Protocol::HTTP::Request, handed to
+        # the router as it arrived -- it patterns on [verb, path] and carries
+        # #params, #headers and a #body that streams, so there is nothing for
+        # a wrapper to add.
+        def call(request)
+          begin
+            handler = @router.call(request)
+          rescue NoMatchingPatternError
+            handler = nil
+          end
+          respond(handler, request)
+        end
+
+        # Middleware#close delegates down the chain on shutdown, and this is
+        # the bottom of it.
+        def close = nil
+
+        private
+
+          # Callable is #call, not Proc -- a handler object with a #call is as
+          # callable as a lambda. It is tested last for a reason that bites
+          # here specifically: Body::Readable#call(stream) is how a body
+          # writes itself out, so a Readable answers #call. Tested any earlier
+          # and `->(req) { req.body }` would have that body called with the
+          # request instead of becoming the response.
+          def respond(handler, request)
+            case handler
+            when nil
+              ::Protocol::HTTP::Response[404, { "content-type" => "text/plain" }, ["not found"]]
+            when String
+              ::Protocol::HTTP::Response[200, { "content-type" => "text/plain" }, [handler]]
+            # A body handed back as-is -- most usefully the request's own,
+            # which makes an echo or a proxy a pass-through, nothing buffered.
+            when ::Protocol::HTTP::Body::Readable
+              ::Protocol::HTTP::Response[200, {}, handler]
+            when Array
+              status, headers, body = handler
+              ::Protocol::HTTP::Response[status, headers, body.is_a?(String) ? [body] : body]
+            else
+              if handler.respond_to?(:call)
+                respond(handler.call(request), request)
+              else
+                handler
+              end
+            end
+          end
+      end
+    end
+  end
+
+  module Backends
+    # Falcon without falcon: one Async::HTTP::Server in this process, no
+    # container, no supervision, no restarts. Use ratalada/falcon when you
+    # want those; this is the fiber-based server on its own.
+    #
+    # Named for the server it runs rather than the gem, because `Async` here
+    # would shadow the async gem for every sibling in this namespace: an
+    # unqualified `Async::Service` inside Backends::Falcon resolved to
+    # `Ratalada::Backends::Async::Service` and broke that backend outright.
+    module AsyncHTTP
+      module_function
+
+      def run(app, host:, port:, count: 1)
+        if count > 1
+          warn "ratalada: async backend ignores count: (single process — use ratalada/falcon)"
+        end
+
+        endpoint = ::Async::HTTP::Endpoint.parse("http://#{host}:#{port}")
+        server = ::Async::HTTP::Server.new(adapt(app), endpoint)
+
+        warn "ratalada: async listening on http://#{host}:#{port}"
+        # #run wraps itself in Async{}, which outside a reactor starts one and
+        # blocks until the accept loop ends.
+        server.run
+      rescue Interrupt
+        # clean shutdown
+      end
+
+      # Async::HTTP::Server speaks Protocol::HTTP natively, so the adapter is
+      # only in the way when the frontend does too -- which ProtocolRoutes,
+      # installed below, does. Every other frontend (Routes, Builder, Sinatra,
+      # Grape, Hanami, Roda) is rack and gets wrapped, without having to
+      # declare anything: Ratalada.rack_frontend? assumes rack unless a
+      # frontend says `def self.rack? = false`.
+      def adapt(app)
+        if Ratalada.rack_frontend?
+          ::Protocol::Rack::Adapter.new(app)
+        else
+          app
+        end
+      end
+    end
+  end
+
+  config.backend = Backends::AsyncHTTP
+
+  # Only the default is replaced. A frontend require sets config.frontend
+  # itself, so `require "ratalada/sinatra"` on either side of this one keeps
+  # Sinatra (and its rack adapter) rather than racing with it.
+  if config.frontend == Frontends::Routes
+    config.frontend = Frontends::ProtocolRoutes
+  end
+end

data/lib/ratalada/falcon.rb

@@ -9,6 +9,12 @@ require_relative "../ratalada"
 
 module Ratalada
   module Backends
+    # Every Async:: below is rooted at ::. The async backend used to be
+    # Backends::Async, and an unqualified lookup found that sibling first:
+    # `Async::Service` resolved to `Ratalada::Backends::Async::Service` and
+    # took this backend down with it in any process that had required both.
+    # It is Backends::AsyncHTTP now, so nothing shadows the gem -- the `::`
+    # stays so the next sibling cannot do it again.
     module Falcon
       module_function
 
@@ -26,7 +32,7 @@ module Ratalada
       def run(app, host:, port:, count: 1, cache: false)
         middleware = ::Falcon::Server.rack_middleware(app, cache: cache)
 
-        environment = Async::Service::Environment.new(::Falcon::Environment::Server).with(
+        environment = ::Async::Service::Environment.new(::Falcon::Environment::Server).with(
           name:              "ratalada",
           url:               "http://#{host}:#{port}",
           middleware:        -> { middleware },
@@ -37,7 +43,7 @@ module Ratalada
           root:              Dir.pwd,
         )
 
-        configuration = Async::Service::Configuration.new
+        configuration = ::Async::Service::Configuration.new
         configuration.add(environment)
 
         if count > 1
@@ -47,7 +53,10 @@ module Ratalada
         end
 
         warn "ratalada: falcon listening on http://#{host}:#{port}#{workers}"
-        Async::Service::Controller.run(configuration, container_class: Async::Container.best_container_class)
+        ::Async::Service::Controller.run(
+          configuration,
+          container_class: ::Async::Container.best_container_class,
+        )
       rescue Interrupt
         # clean shutdown
       end

data/lib/ratalada/protocol_http_ext.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "protocol/http"
+require "protocol/url"
+
+# Pattern matching for Protocol::HTTP::Request, so the router matches the
+# request the server actually built instead of a wrapper standing in for it.
+# `case request in ["GET", "/"]` needs #deconstruct and the class has none --
+# unpatched, every pattern raises NoMatchingPatternError and every route 404s.
+#
+# Additions only: #path still returns the raw target ("/users/1?a=b"), which
+# is what protocol-http1 writes and what anything else reading a request
+# expects. The split path is what the patterns see, because a route is a path
+# and "/hi" should match a request for "/hi?name=x".
+module Protocol
+  module HTTP
+    class Request
+      # The class overrides #method as a reader for the verb, so there is no
+      # Object#method here to collide with -- and `in {verb:}` reads better
+      # than `in {method:}` would.
+      def verb = self.method
+
+      def reference = @reference ||= ::Protocol::URL::Reference.parse(path)
+
+      # "" rather than nil with no query string, so `in {query: ""}` means the
+      # same here as on the rack router.
+      def query = reference.query || ""
+
+      def params
+        if query.empty?
+          @params ||= {}
+        else
+          @params ||= ::Protocol::URL::Encoding.decode(query)
+        end
+      end
+
+      # Enables `in ["GET", "/"]`
+      def deconstruct = [verb, reference.path.to_s]
+
+      # Enables `in {verb: "GET", path: "/users"}`
+      def deconstruct_keys(_keys) = { verb:, path: reference.path.to_s, query:, params:, headers:, body: }
+    end
+  end
+end

data/lib/ratalada/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ratalada
-  VERSION = "3.0.0"
+  VERSION = "4.0.0"
 end

data/lib/ratalada/webrick.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rackup/handler/webrick"
+require_relative "../ratalada"
+
+module Ratalada
+  module Backends
+    # Stdlib WEBrick via rackup's handler, which already does the rack env
+    # translation. Single process, one thread per connection — fine for
+    # development and tests, not what you ship.
+    module Webrick
+      module_function
+
+      def run(app, host:, port:, count: 1)
+        if count > 1
+          warn "ratalada: webrick backend ignores count: (single process)"
+        end
+
+        warn "ratalada: webrick listening on http://#{host}:#{port}"
+        ::Rackup::Handler::WEBrick.run(app, Host: host, Port: port)
+      rescue Interrupt
+        ::Rackup::Handler::WEBrick.shutdown
+      end
+    end
+  end
+
+  config.backend = Backends::Webrick
+end

data/lib/ratalada.rb

@@ -18,8 +18,10 @@ module Ratalada
       super(msg || <<~MSG)
         No server backend selected. Require one before calling Server.run:
 
-          require "ratalada/puma"    # or
-          require "ratalada/falcon"
+          require "ratalada/puma"     # or
+          require "ratalada/falcon"   # or
+          require "ratalada/async"    # or
+          require "ratalada/webrick"
       MSG
     end
   end
@@ -34,6 +36,15 @@ module Ratalada
     end
 
     def frontend = config.frontend
+
+    # A frontend is rack unless it says otherwise (`def self.rack? = false`),
+    # so every existing one counts without declaring anything. The async
+    # backend reads this to decide whether its app needs Protocol::Rack::Adapter.
+    def rack_frontend?
+      frontend = config.frontend
+
+      !(frontend.respond_to?(:rack?) && !frontend.rack?)
+    end
   end
 
   # Rack::Request plus just enough sugar to pattern match on, so everything
@@ -101,19 +112,25 @@ module Ratalada
 
         private
 
+          # Callable is #call, not Proc -- a handler object with a #call is as
+          # callable as a lambda, and was being handed back as the response.
+          # It is tested last, after every shape that is already a response,
+          # because some of those answer #call too for reasons of their own.
           def respond(handler, request)
             case handler
             when nil
               [404, { "content-type" => "text/plain" }, ["not found"]]
-            when Proc, Method
-              respond(handler.call(request), request)
             when String
               [200, { "content-type" => "text/plain" }, [handler]]
             when Array
               status, headers, body = handler
               [status, headers, body.is_a?(String) ? [body] : body]
             else
-              handler
+              if handler.respond_to?(:call)
+                respond(handler.call(request), request)
+              else
+                handler
+              end
             end
           end
       end
@@ -177,6 +194,12 @@ module Ratalada
       end
 
       # First `use` in the chain is the outermost, as in Rack::Builder.
+      #
+      # `klass.new(inner, *args)` is rack's middleware contract and
+      # Protocol::HTTP::Middleware's alike -- `new(delegate)`, then `call`
+      # with whatever that frontend passes -- so one chain serves both: rack
+      # middleware on a rack frontend, Protocol::HTTP middleware on
+      # Frontends::ProtocolRoutes.
       def to_app(block)
         @middleware.reverse.inject(Ratalada.frontend.build(block)) do |inner, (klass, args, blk)|
           klass.new(inner, *args, &blk)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratalada
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Nathan K
@@ -107,6 +107,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: lefthook
   requirement: !ruby/object:Gem::Requirement
@@ -135,10 +149,13 @@ files:
 - README.md
 - exe/ratalada
 - lib/ratalada.rb
+- lib/ratalada/async.rb
 - lib/ratalada/builder.rb
 - lib/ratalada/falcon.rb
+- lib/ratalada/protocol_http_ext.rb
 - lib/ratalada/puma.rb
 - lib/ratalada/version.rb
+- lib/ratalada/webrick.rb
 homepage: https://github.com/n-at-han-k/ratalada
 licenses:
 - MIT