landline 0.10.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3032701a4da46a02233ca8b0f1a6c48a484dc068de78b0b82ea15381bc7950f1
-  data.tar.gz: ab0eba5a84fb6ba20fff26baf741cdd249c018cb74301b682d74b9d8b8bc043d
+  metadata.gz: a6713c809dcb1f2216afff7f05d00e932c85d36c1b205359a2c8f8655b79fbb1
+  data.tar.gz: 34846e521a08d55376a520a194417edf0cb66972bf6c052ac6fb5d888fea30f2
 SHA512:
-  metadata.gz: a60a9110562ad5098f1bb3b93daf6449df72ff1bacb08ea6bc93684e528e7787fde92c53cd3d7ac1da5b800dada5672224329e72d31acf6b092a30208e463b61
-  data.tar.gz: ed7cf7655fe04a805da5079d793a4c2102b926d6d854206991c706221b65ca3f50c1dd441c223aca34196b713adb58ad92a642146302bd0480c2197affd29383
+  metadata.gz: b54438875d8532e95858567f0305b03baf00a6c88a735851116be73ea2b7619031226624ff846d05a7439050deff1b02acfe5c5a7d1a8afdb8e67b2ea6b520a1
+  data.tar.gz: 03031f8d28c5e8657854cdff63e4f205d9b553cb03e34109b761a5f65207fd473005a61a5504a3f96517a37fe2d1f1b234b733916a3bd5f33f4de0e64a30fbab

data/README.md

@@ -2,25 +2,15 @@
 
 Landline is a library that provides a minimalistic DSL for creating
 web services. It doesn't include patterns, middleware, or anything that
-could be considered application logic. It does a few things, and hopefully
-it does them well:
+could be considered application logic, besides the basic primitives
+It does a few things, and hopefully it does them well.
 
-- Routing HTTP requests to handlers
-- Processing HTTP requests (cookies, headers, etc.)
-- Filtering, preprocessing and postprocessing requests
-- Creating responses from templates using various template engines
-- Parsing and handling forms and queries
-- Connecting multiple Landline applications together
-
-As such, the library is pretty thin and can be used to build more complex
-applications.
-
-As of now it is using Rack as the webserver adapter, but ideally it
-shouldn't take much work to make it run on top of any webserver.
-
-Landline was made mostly for fun. Ideally it will become something more,
+Landline was made mostly for fun. ~~Ideally it will become something more,
 but as of yet it's just an experiment revolving around Ruby Metaprogramming
-and its DSL capabilities.
+and its DSL capabilities.~~ Since then, it has somewhat matured, and while
+it's still not entirely advisable to use in production due to the experimental
+nature of the framework, you're free to test it, see if it works, and if it
+doesn't, supply (hopefully constructive) criticism and/or suggestions.
 
 ## Examples
 
@@ -85,7 +75,7 @@ end
 run app
 ```
 
-Static file serving
+Static file serving with nginx-like syntax and file globbing
 (Note: index applies *only* to /var/www (to the path its defined in))
 
 ```ruby
@@ -100,7 +90,7 @@ end
 run app
 ```
 
-Logging on a particular path
+Preprocessing requests on a subset of handlers
 
 ```ruby
 require 'landline'
@@ -127,8 +117,70 @@ end
 run app
 ```
 
+Class interface with middleware support
+
+```ruby
+require 'landline'
+
+class TimerMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(*data)
+    puts("Request accepted")
+    before = Time.now
+    output = @app.call(*data)
+    puts("Time elapsed: #{(Time.now - before) * 1000}ms")
+    output
+  end
+end
+
+class Application < Landline::App
+  use TimerMiddleware
+
+  get "/hello" do
+    "Hello world!"
+  end
+end
+
+run Application.new
+```
+
 And a lot more to be found in /examples in this repo.
 
+
+## Design goals
+
+Out of the box, Landline is designed to do the following:
+
+- Routing HTTP requests to handlers
+- Processing HTTP requests (cookies, headers, etc.)
+- Filtering, preprocessing, postprocessing requests
+- Deferring block execution until after the request gets processed
+- Creating responses from templates using various template engines
+- Parsing and handling forms and queries
+- Connecting multiple ~~Landline~~ Rack applications together
+- Sending files using nginx-style configuration system
+- A lot of basic Rack things such as plugging in middleware, BEING middleware,
+  or sending Rack-compatible environment to another Rack application
+
+As such, the library is pretty thin and can be used to build more complex
+applications. This is intentional, and hopefully will remain that way.
+
+Additionally, there are a few extra things landline can do, which can be used
+by `require`ing from the `landline/extensions` directory. Please note, however,
+that some of that functionality may require additional dependencies, which
+would otherwise be optional. This functionality includes:
+
+- PHP-like Session handling (via `landline/extensions/session`)
+- Websockets (via `landline/extensions/websockets`) (available for testing)
+- (Probably something else eventually)
+
+Landline is built entirely on Rack webserver interface, while being agnostic
+to any and all underlying webservers (such as Puma, Thin, Unicorn and such).
+For the foreseeable future, this design decision will not change.
+
 ## Name
 
 The name is, quite literally, a metaphor for request routing.

data/lib/landline/app.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Landline
+  # Rack application interface
+  class App
+    class << self
+      # TODO: fix this mess somehow (probably impossible)
+      # @!parse include Landline::DSL::PathMethods
+      # @!parse include Landline::DSL::PathConstructors
+      # @!parse include Landline::DSL::ProbeConstructors
+      # @!parse include Landline::DSL::ProbeMethods
+      # @!parse include Landline::DSL::CommonMethods
+
+      # Duplicate used middleware for the subclassed app
+      def inherited(subclass)
+        super(subclass)
+        @setup_chain ||= []
+        subclass.middleware = @middleware.dup
+        subclass.setup_chain = @setup_chain.dup
+      end
+
+      # Include a middleware in application
+      # @param middleware [Class]
+      def use(middleware)
+        @middleware ||= []
+        @middleware.append(middleware)
+      end
+
+      # Check if Server can respond to given symbol
+      def respond_to_missing?(symbol, _include_private)
+        Landline::ServerContext.instance_methods.include?(symbol) || super
+      end
+
+      # Store applied app manipulations
+      def method_missing(symbol, *args, **params, &callback)
+        if Landline::ServerContext.instance_methods.include? symbol
+          @setup_chain.append([symbol, args, params, callback])
+        else
+          super(symbol, *args, **params, &callback)
+        end
+      end
+
+      attr_accessor :middleware, :setup_chain
+    end
+
+    def initialize(*args, **opts)
+      setup_chain = self.class.setup_chain
+      @app = ::Landline::Server.new(*args, **opts) do
+        setup_chain.each do |symbol, cargs, cparams, callback|
+          send(symbol, *cargs, **cparams, &callback)
+        end
+      end
+      self.class.middleware&.reverse_each do |cls|
+        @app = cls.new(@app)
+      end
+    end
+
+    # Rack ingress point.
+    # @param env [Hash]
+    # @return [Array(Integer,Hash,Array)]
+    def call(env)
+      @app.call(env)
+    end
+  end
+end

data/lib/landline/dsl/constructors_path.rb

@@ -5,6 +5,7 @@ module Landline
   module DSL
     # Path (and subclasses) DSL constructors
     module PathConstructors
+      # (in Landline::Path context)
       # Append a Node child object to the list of children
       def register(obj)
         unless obj.is_a? Landline::Node
@@ -14,11 +15,13 @@ module Landline
         @origin.children.append(obj)
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Path} object
       def path(path, **args, &setup)
         register(Landline::Path.new(path, parent: @origin, **args, &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::Probe} object
       def probe(path, **args, &_setup)
         register(Landline::Handlers::Probe.new(path,
@@ -26,6 +29,7 @@ module Landline
                                                **args))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::GETHandler} object
       def get(path, **args, &setup)
         register(Landline::Handlers::GET.new(path,
@@ -34,6 +38,7 @@ module Landline
                                              &setup))
       end
 
+      # (in Landline::Path context)
       # create a new {Landline::Handlers::POSTHandler} object
       def post(path, **args, &setup)
         register(Landline::Handlers::POST.new(path,
@@ -42,6 +47,7 @@ module Landline
                                               &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::PUTHandler} object
       def put(path, **args, &setup)
         register(Landline::Handlers::PUT.new(path,
@@ -50,6 +56,7 @@ module Landline
                                              &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::HEADHandler} object
       def head(path, **args, &setup)
         register(Landline::Handlers::HEAD.new(path,
@@ -58,6 +65,7 @@ module Landline
                                               &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::DELETEHandler} object
       def delete(path, **args, &setup)
         register(Landline::Handlers::DELETE.new(path,
@@ -66,6 +74,7 @@ module Landline
                                                 &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::CONNECTHandler} object
       def connect(path, **args, &setup)
         register(Landline::Handlers::CONNECT.new(path,
@@ -74,6 +83,7 @@ module Landline
                                                  &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::TRACEHandler} object
       def trace(path, **args, &setup)
         register(Landline::Handlers::TRACE.new(path,
@@ -82,6 +92,7 @@ module Landline
                                                &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::PATCHHandler} object
       def patch(path, **args, &setup)
         register(Landline::Handlers::PATCH.new(path,
@@ -90,6 +101,7 @@ module Landline
                                                &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::OPTIONSHandler} object
       def options(path, **args, &setup)
         register(Landline::Handlers::OPTIONS.new(path,
@@ -98,10 +110,19 @@ module Landline
                                                  &setup))
       end
 
+      # (in Landline::Path context)
       # Create a new {Landline::Handlers::GETHandler} that serves static files
       def serve(path)
         register(Landline::Handlers::Serve.new(path, parent: @origin))
       end
+
+      # (in Landline::Path context)
+      # Create a new application crosscall link (acts like #call in probe context and strips its path from request)
+      def link(path, application)
+        register(Landline::Handlers::Link.new(path,
+                                              application,
+                                              parent: @origin))
+      end
     end
   end
 end

data/lib/landline/dsl/constructors_probe.rb

@@ -4,6 +4,7 @@ module Landline
   module DSL
     # Probe (and subclasses) DSL construct
     module ProbeConstructors
+      # (in Landline::Probe context)
       # Create a new erb template
       # @see Landline::Template#new
       def erb(input, vars = {})
@@ -13,6 +14,7 @@ module Landline
                                      filename: caller_locations[0].path)
       end
 
+      # (in Landline::Probe context)
       # Create a new erb template using Erubi engine
       # @see Landline::Template#new
       # @param freeze [Boolean] whether to use frozen string literal

data/lib/landline/dsl/methods_common.rb

@@ -4,6 +4,7 @@ module Landline
   module DSL
     # Methods shared by probes, preprocessors and filters.
     module CommonMethods
+      # (in Landline::Probe context)
       # Stop execution and generate a boilerplate response with the given code
       # @param errorcode [Integer]
       # @param backtrace [Array(String), nil]
@@ -18,6 +19,7 @@ module Landline
         )
       end
 
+      # (in Landline::Probe context)
       # Bounce request to the next handler
       # @raise [UncaughtThrowError] throws :break to get out of the callback
       def bounce

data/lib/landline/dsl/methods_path.rb

@@ -5,11 +5,19 @@ module Landline
   module DSL
     # Common path methods
     module PathMethods
+      # (in Landline::Path context)
       # Bounce request if no handler found instead of issuing 404
       def bounce
         @origin.bounce = true
       end
 
+      # (in Landline::Path context)
+      # Unset bounce
+      def nobounce
+        @origin.bounce = false
+      end
+
+      # (in Landline::Path context)
       # Create a status code handler on path.
       # Recursively applies to all paths unless overridden.
       # @param code [Integer, nil] Specify a status code to handle
@@ -18,6 +26,7 @@ module Landline
         @origin.properties["handle.#{code || 'default'}"] = block
       end
 
+      # (in Landline::Path context)
       # Insert a pass-through pipeline into request processing
       # (i.e. for error handling purposes).
       # Passed block should yield request (and return yielded data back).
@@ -26,6 +35,7 @@ module Landline
         @origin.pipeline = block
       end
 
+      # (in Landline::Path context)
       # Set path index
       # @param index [Array,String]
       def index(index)
@@ -39,18 +49,21 @@ module Landline
         end
       end
 
+      # (in Landline::Path context)
       # Set root path (appends matched part of the path).
       # @param path [String]
       def root(path)
-        @origin.root = path
+        @origin.root = File.expand_path(path)
       end
 
+      # (in Landline::Path context)
       # Set root path (without appending matched part).
       # @param path [String]
       def remap(path)
-        @origin.remap = path
+        @origin.remap = File.expand_path(path)
       end
 
+      # (in Landline::Path context)
       # Add a preprocessor to the path.
       # Does not modify path execution.
       # @param block [#call]
@@ -60,6 +73,7 @@ module Landline
         block
       end
 
+      # (in Landline::Path context)
       # Add a postprocessor to the path.
       # @param block [#call]
       # @yieldparam request [Landline::Request]
@@ -69,6 +83,10 @@ module Landline
         block
       end
 
+      alias before preprocess
+      alias after postprocess
+
+      # (in Landline::Path context)
       # Add a filter to the path.
       # Blocks path access if a filter returns false.
       # @param block [#call]
@@ -78,10 +96,12 @@ module Landline
         block
       end
 
+      # (in Landline::Path context)
       # Include an application as a child of path.
+      # @deprecated this method is being deprecated due to strong dependency on the framework
       # @param filename [String]
       def plugin(filename)
-        self.define_singleton_method(:run) do |object|
+        define_singleton_method(:run) do |object|
           unless object.is_a? Landline::Node
             raise ArgumentError, "not a node instance or subclass instance"
           end
@@ -89,9 +109,9 @@ module Landline
           object
         end
         @origin.children.append(
-          self.instance_eval(File.read(filename), filename)
+          instance_eval(File.read(filename), filename)
         )
-        self.singleton_class.undef_method :run
+        singleton_class.undef_method :run
       end
     end
   end

data/lib/landline/dsl/methods_probe.rb

@@ -4,17 +4,20 @@ require_relative '../response'
 require_relative '../util/multipart'
 require_relative '../util/parseutils'
 require_relative '../util/html'
+require 'json'
 
 module Landline
   module DSL
     # Common methods for Probe objects
     module ProbeMethods
+      # (in Landline::Probe context)
       # Get the current request
       # @return [Landline::Request]
       def request
         @origin.request
       end
 
+      # (in Landline::Probe context)
       # Set response status (generate response if one doesn't exist yet)
       # @param status [Integer] http status code
       def status(status)
@@ -22,8 +25,59 @@ module Landline
         @origin.response.status = status
       end
 
+      # (in Landline::Probe context)
+      # Add a finalizer callable to the response
+      # @param callable [#call]
+      def defer(&callable)
+        rack = @origin.request.rack
+        if rack.respond_to?(:response_finished)
+          rack.response_finished.append(callable)
+        end
+        # puma for some reason isn't compatible with the 3.0.0 spec on this
+        rack.after_reply.append(callable) if rack.respond_to?(:after_reply)
+      end
+
+      # (in Landline::Probe context)
+      # Do serverside request redirection
+      # @note this essentially reprocesses the whole request - be mindful of processing time!
+      # @param path [String]
+      def jump(path)
+        @origin.request.path = path
+        throw(:finish, [307, { "x-internal-jump": true }, []])
+      end
+
+      # (in Landline::Probe context)
+      # Do clientside request redirection via 302 code
+      # @param path [String]
+      def redirect(path)
+        throw(:finish, [302, { "location": path }, []])
+      end
+
+      # (in Landline::Probe context)
+      # Do clientside request redirection via 307 code
+      # @param path [String]
+      def redirect_with_method(path)
+        throw(:finish, [307, { "location": path }, []])
+      end
+
       alias code status
 
+      # (in Landline::Probe context)
+      # Set a partial hijack callback
+      # @param block [#call] Callable block
+      def partial_hijack(&block)
+        @origin.response ||= Landline::Response.new
+        @origin.response.add_header("rack.hijack", block)
+      end
+
+      # (in Landline::Probe context)
+      # Fully hijack IO
+      # @return [IO]
+      def hijack
+        @origin.request.hijack.call
+      end
+
+      # (in Landline::Probe context)
       # Set response header (generate response if one doesn't exist yet)
       # @param key [String] header name
       # @param value [String] header value
@@ -39,10 +93,11 @@ module Landline
         end
 
         @origin.response = (@origin.response or Landline::Response.new)
-        key = key.downcase
+        key = key.downcase.to_s
         @origin.response.add_header(key, value)
       end
 
+      # (in Landline::Probe context)
       # Delete a header value from the headers hash
       # If no value is provided, deletes all key entries
       # @param key [String] header name
@@ -60,9 +115,10 @@ module Landline
           raise ArgumentError, "value key has invalid characters"
         end
 
-        @origin.response.delete_header(key, value)
+        @origin.response.delete_header(key.to_s, value)
       end
 
+      # (in Landline::Probe context)
       # Set response cookie
       # @see Landline::Cookie.new
       def cookie(*params, **options)
@@ -72,6 +128,7 @@ module Landline
         )
       end
 
+      # (in Landline::Probe context)
       # Delete a cookie
       # If no value is provided, deletes all cookies with the same key
       # @param key [String] cookie key
@@ -82,21 +139,17 @@ module Landline
         @origin.response.delete_cookie(key, value)
       end
 
+      # (in Landline::Probe context)
       # Checks if current request has multipart/form-data associated with it
       # @return [Boolean]
       def form?
-        value, opts = Landline::Util::ParserCommon.parse_value(
-          request.headers["content-type"]
-        )
-        if value == "multipart/form-data" and
-           opts["boundary"]
-          true
-        else
-          false
-        end
+        value, opts = _verify_content_type('multipart/form-data')
+        !!(value && opts && opts['boundary'])
       end
 
+      # (in Landline::Probe context)
       # Returns formdata
+      # @note reads request.input - may nullify request.body.
       # @return [Hash{String=>(String,Landline::Util::FormPart)}]
       def form
         _, opts = Landline::Util::ParserCommon.parse_value(
@@ -107,23 +160,88 @@ module Landline
         ).to_h
       end
 
+      # (in Landline::Probe context)
+      # Checks if current request has urlencoded query string
+      # @return [Boolean]
+      def query?
+        !!_verify_content_type("application/x-www-form-urlencode")
+      end
+
+      # (in Landline::Probe context)
+      # Returns parsed query hash
+      # @note reads request.body - may nullify .input, .body data is memoized
+      # @return [Hash{String => Object}] query data
+      def query
+        Landline::Util::Query.new(request.body).parse
+      end
+
+      # (in Landline::Probe context)
+      # Returns shallow parsed query hash
+      # @note reads request.body - may nullify .input, .body data is memoized
+      # @return [Hash{String => Object}] query data
+      def query_shallow
+        Landline::Util::Query.new(request.body).parse_shallow
+      end
+
+      # (in Landline::Probe context)
+      # Check if body is a JSON object
+      # @return [Boolean]
+      def json?
+        !!_verify_content_type('application/json')
+      end
+
+      # (in Landline::Probe context)
+      # Return parse JSON object
+      # @note reads request.input - may nullify request.body.
+      # @return [Object]
+      def json
+        JSON.parse(request.input)
+      end
+
+      # (in Landline::Probe context)
       # Open a file relative to current filepath
       # @see File.open
       def file(path, mode = "r", *all, &block)
         File.open("#{request.filepath}/#{path}", mode, *all, &block)
       end
 
+      # (in Landline::Probe context)
       # Escape HTML entities
       # @see Landline::Util.escape_html
       def escape_html(text)
         Landline::Util.escape_html(text)
       end
 
+      # (in Landline::Probe context)
       # Unescape HTML entities
       # @see Landline::Util.escape_html
       def unescape_html(text)
         Landline::Util.unescape_html(text)
       end
+
+      # (in Landline::Path context)
+      # Pass the requested environment to a different application
+      # @param application [#call] Rack application
+      # @return [Array(Integer, Hash{String => Object}, Object)] response
+      def call(application)
+        application.call(@origin.request.env)
+      end
+
+      private
+
+      def _verify_content_type(type)
+        return false unless request.headers['content-type']
+
+        value, opts = Landline::Util::ParserCommon.parse_value(
+          request.headers["content-type"]
+        )
+        if value == type and
+           request.input
+          [value, opts]
+        else
+          false
+        end
+      end
     end
   end
 end

data/lib/landline/dsl/methods_template.rb

@@ -7,6 +7,7 @@ module Landline
   module DSL
     # Common methods for template contexts
     module TemplateMethods
+      # (in Landline::Template context)
       # Import a template part
       # @param filepath [String, File] path to the file (or the file itself)
       # @return [String] compiled template