landline 0.9.3 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58106097aed53f3fb0edd51bf2d9ecf8ba9d976946ffd7e4570c7f1b5ecdafa7
-  data.tar.gz: 2b1a03b8a2afeb431a9afe0207a7f17a9ea5439372cccd2c7d2e02b50f544ff1
+  metadata.gz: d4924570720bd14c3d6149435782f59a64cd7c36727da5a204462653125de65d
+  data.tar.gz: 8f06e6d9194aee22eb39752047c548fda980964548b0f5c78f20200e7f441c6e
 SHA512:
-  metadata.gz: 9422f97e4310cea957b3c8ee6aed9ecc279bdffbb3e8578263a1f03316881d2833a3e3bdac42816a077702d3501d7c71027d6e7f5d72a8e1cf34ca4e114f66b8
-  data.tar.gz: ea8a961e1a6cbb755a8be74c75288932c736174fdef1a7c04c5ef5f6d5d3e0687f393ff5076a8435c1e6eb57978c4993f0152a38af5e5ec77c99adfdedfffe6c
+  metadata.gz: 353d30b81860f95e23d542e3b954e3fd1be308fa1cbd534017518a02238d5a79e886cd65e7237380be660286795cfe134c703fb5c2b19765420a065a5400f5d1
+  data.tar.gz: d9be7521e662b6ff25f5cf7ac9c98bfe7f6d38a174cf3b9d95110b2c8ff42c500cb0e916a4961dadb48263566aa58812e2b3b5973b0e15c458b69856d0460d25

data/HACKING.md

@@ -23,8 +23,3 @@ To keep things beautiful, consider following recommendations:
 - Document classes as if the next maintainer after you has you at gunpoint.
   Document thoroughly, use YARD tags and **never** skip on public method
   docs and class docs. As an example, consider Landline::PatternMatching::Glob.
-- Unit tests suck for many reasons. However, if you're writing a class that
-  does not have any dependents and which is frequently used, consider making
-  a unit test for it. People that might have to fix things further along
-  will be very thankful.
-

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,72 @@ 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
+
+  setup do
+    get "/hello" do
+      "Hello world!"
+    end
+  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,50 @@
+# frozen_string_literal: true
+
+module Landline
+  # Rack application interface
+  class App
+    # 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
+    class << self
+      # Duplicate used middleware for the subclassed app
+      def inherited(subclass)
+        super(subclass)
+        subclass.middleware = @middleware.dup
+      end
+
+      # Include a middleware in application
+      # @param middleware [Class]
+      def use(middleware)
+        @middleware ||= []
+        @middleware.append(middleware)
+      end
+
+      # Setup block
+      # @param block [#call]
+      def setup(&block)
+        @setup_block = block
+      end
+
+      attr_accessor :middleware, :setup_block
+    end
+
+    def initialize(*args, **opts)
+      @app = ::Landline::Server.new(*args, **opts, &self.class.setup_block)
+      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,8 +4,9 @@ module Landline
   module DSL
     # Probe (and subclasses) DSL construct
     module ProbeConstructors
+      # (in Landline::Probe context)
       # Create a new erb template
-      # @see {Landline::Template#new}
+      # @see Landline::Template#new
       def erb(input, vars = {})
         Landline::Templates::ERB.new(input,
                                      vars,
@@ -13,8 +14,9 @@ module Landline
                                      filename: caller_locations[0].path)
       end
 
+      # (in Landline::Probe context)
       # Create a new erb template using Erubi engine
-      # @see {Landline::Template#new}
+      # @see Landline::Template#new
       # @param freeze [Boolean] whether to use frozen string literal
       # @param capture [Boolean] whether to enable output capturing
       def erubi(input, vars = {}, freeze: true, capture: false)

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,6 +5,37 @@ 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
+      # @param block [#call] Block to run on given code
+      def handle(code = nil, &block)
+        @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).
+      # @param block [#call] block that yields request
+      def pipeline(&block)
+        @origin.pipeline = block
+      end
+
+      # (in Landline::Path context)
       # Set path index
       # @param index [Array,String]
       def index(index)
@@ -18,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]
@@ -39,6 +73,7 @@ module Landline
         block
       end
 
+      # (in Landline::Path context)
       # Add a postprocessor to the path.
       # @param block [#call]
       # @yieldparam request [Landline::Request]
@@ -48,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]
@@ -57,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
@@ -68,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(:break, [307, { "x-internal-jump": true }, []])
+      end
+
+      # (in Landline::Probe context)
+      # Do clientside request redirection via 302 code
+      # @param path [String]
+      def redirect(path)
+        throw(:break, [302, { "location": path }, []])
+      end
+
+      # (in Landline::Probe context)
+      # Do clientside request redirection via 307 code
+      # @param path [String]
+      def redirect_with_method(path)
+        throw(:break, [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,9 +7,19 @@ 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
       def import(filepath)
-        @parent_template.import(file(filepath)).run
+        template = if filepath.is_a? File
+                     filepath
+                   elsif filepath.start_with? "/"
+                     File.open(filepath)
+                   else
+                     file(filepath)
+                   end
+        @parent_template.import(template).run
       end
     end
   end