ratalada 3.1.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '079378d0ea4867145471fa730a8d2eb6ec20513d50e7bfcb52b643cd99bbf6e2'
-  data.tar.gz: 228276a9a88b32c152a4e84eb12f267f62b8cde567d7d9dab9fae4734e207ab9
+  metadata.gz: 1da8d4c6eff98bad680c6e3da80c2d452b54711c1d2e2fe5b9de11500640f0a9
+  data.tar.gz: 9fae4c8b7aa84cc4ccf69017779f24fb011491a7143c3abb9332483db25489e5
 SHA512:
-  metadata.gz: 5fa8af50cdf2da52fcc5e35d4a8f9acdd97307a6b1c5a7afd09d2971889331ec7af9f16a9472991db768fc71bb195174bf7c77e45fec50dded0b7696eef37c03
-  data.tar.gz: 939a4d0b6d7f9b1434561607ba7d02e44ab93a471abb8d7565e223a2b103434177648d648901fa65a75b001ced4a926aef14f95478cffeb1c1c1c885dbcfbb84
+  metadata.gz: 6af7b845bd465ede4788967478ad9e67be55e3a2708000f2678a3a4ded46d3b024778d2828bb546e01f9e618fd8a43c1566bf46bdac2b1dff760d65105f3892a
+  data.tar.gz: '08bc22a824af6bacdfadc7b6546d0b8c9f116b22c8efc358f4cd7bc97cbe7652a59f23a9beb44616e87b5a3ae8f90a22628d02a1fd6dbf9b7460533336b137c1'

data/lib/ratalada/async.rb

@@ -2,15 +2,107 @@
 
 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.
-    module Async
+    #
+    # 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)
@@ -19,7 +111,7 @@ module Ratalada
         end
 
         endpoint = ::Async::HTTP::Endpoint.parse("http://#{host}:#{port}")
-        server = ::Async::HTTP::Server.new(::Protocol::Rack::Adapter.new(app), endpoint)
+        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
@@ -28,8 +120,29 @@ module Ratalada
       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::Async
+  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.1.0"
+  VERSION = "4.0.0"
 end

data/lib/ratalada.rb

@@ -36,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
@@ -103,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
@@ -179,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.1.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Nathan K
@@ -152,6 +152,7 @@ files:
 - 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