landline 0.9.2

data/README.md

@@ -0,0 +1,159 @@
+# Landline - an HTTP DSL
+
+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:
+
+- 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,
+but as of yet it's just an experiment revolving around Ruby Metaprogramming
+and its DSL capabilities.
+
+## Examples
+
+A simple "Hello, World!" app using Landline
+
+```ruby
+require 'landline'
+
+app = Landline::Server.new do
+  get "/hello" do
+    header "content-type", "text/plain"
+    "Hello world!"
+  end
+end
+
+run app
+```
+
+A push/pull stack as an app
+
+```ruby
+require 'landline'
+
+stack = []
+
+app = Landline::Server.new do
+  get "/pop" do
+    header 'content-type', 'text/plain'
+    stack.pop.to_s
+  end
+  post "/push" do
+    header 'content-type', 'text/plain'
+    stack.push(request.body)
+    request.body
+  end
+end
+
+run app
+```
+
+Several push/pull buckets
+
+```ruby
+require 'landline'
+
+stack = { "1" => [], "2" => [], "3" => [] }
+
+app = Landline::Server.new do
+  path "bucket_(1|2|3)" do
+    get "pop" do |bucket|
+      header "content-type", "text/plain"
+      stack[bucket].pop.to_s
+    end
+    post "push" do |bucket|
+      header "content-type", "text/plain"
+      stack[bucket].push(request.body)
+      request.body
+    end
+  end
+end
+
+run app
+```
+
+Static file serving
+(Note: index applies *only* to /var/www (to the path its defined in))
+
+```ruby
+require 'landline'
+
+app = Landline::Server.new do
+  root "/var/www"
+  index ["index.html","index.htm"]
+  serve "**/*.(html|htm)"
+end
+
+run app
+```
+
+Logging on a particular path
+
+```ruby
+require 'landline'
+
+app = Landline::Server.new do
+  path "unimportant" do
+    get "version" do
+      header "content-type", "text/plain"
+      "1337 (the best one)"
+    end
+  end
+  path "important" do
+    preprocess do |req|
+      # Implement logging logic here
+      puts "Client at #{req.headers['remote-addr']} wanted to access something /important!"
+    end
+    get "answer" do
+      header "content-type", "application/json"
+      '{"answer":42, "desc":"something important!"}'
+    end
+  end
+end
+
+run app
+```
+
+And a lot more to be found in /examples in this repo.
+
+## Name
+
+The name is, quite literally, a metaphor for request routing.
+
+## Documentation
+
+Documentation can be generated using `yard doc`.
+For things to render correctly, please install the `redcarpet` gem.
+
+## License
+
+```plain
+    Landline - an HTTP request pattern matching system 
+    Copyright (C) 2022 yessiest (yessiest@memeware.net)
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+```

data/lib/landline/dsl/constructors_path.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Landline
+  # Shared DSL methods
+  module DSL
+    # Path (and subclasses) DSL constructors
+    module PathConstructors
+      # Append a Node child object to the list of children
+      def register(obj)
+        unless obj.is_a? Landline::Node
+          raise ArgumentError, "register accepts node children only"
+        end
+
+        @origin.children.append(obj)
+      end
+
+      # Create a new {Landline::Path} object
+      def path(path, **args, &setup)
+        register(Landline::Path.new(path, parent: @origin, **args, &setup))
+      end
+
+      # Create a new {Landline::Handlers::Probe} object
+      def probe(path, **args, &_setup)
+        register(Landline::Handlers::Probe.new(path,
+                                               parent: @origin,
+                                               **args))
+      end
+
+      # Create a new {Landline::Handlers::GETHandler} object
+      def get(path, **args, &setup)
+        register(Landline::Handlers::GET.new(path,
+                                             parent: @origin,
+                                             **args,
+                                             &setup))
+      end
+
+      # create a new {Landline::Handlers::POSTHandler} object
+      def post(path, **args, &setup)
+        register(Landline::Handlers::POST.new(path,
+                                              parent: @origin,
+                                              **args,
+                                              &setup))
+      end
+
+      # Create a new {Landline::Handlers::PUTHandler} object
+      def put(path, **args, &setup)
+        register(Landline::Handlers::PUT.new(path,
+                                             parent: @origin,
+                                             **args,
+                                             &setup))
+      end
+
+      # Create a new {Landline::Handlers::HEADHandler} object
+      def head(path, **args, &setup)
+        register(Landline::Handlers::HEAD.new(path,
+                                              parent: @origin,
+                                              **args,
+                                              &setup))
+      end
+
+      # Create a new {Landline::Handlers::DELETEHandler} object
+      def delete(path, **args, &setup)
+        register(Landline::Handlers::DELETE.new(path,
+                                                parent: @origin,
+                                                **args,
+                                                &setup))
+      end
+
+      # Create a new {Landline::Handlers::CONNECTHandler} object
+      def connect(path, **args, &setup)
+        register(Landline::Handlers::CONNECT.new(path,
+                                                 parent: @origin,
+                                                 **args,
+                                                 &setup))
+      end
+
+      # Create a new {Landline::Handlers::TRACEHandler} object
+      def trace(path, **args, &setup)
+        register(Landline::Handlers::TRACE.new(path,
+                                               parent: @origin,
+                                               **args,
+                                               &setup))
+      end
+
+      # Create a new {Landline::Handlers::PATCHHandler} object
+      def patch(path, **args, &setup)
+        register(Landline::Handlers::PATCH.new(path,
+                                               parent: @origin,
+                                               **args,
+                                               &setup))
+      end
+
+      # Create a new {Landline::Handlers::OPTIONSHandler} object
+      def options(path, **args, &setup)
+        register(Landline::Handlers::OPTIONS.new(path,
+                                                 parent: @origin,
+                                                 **args,
+                                                 &setup))
+      end
+
+      # Create a new {Landline::Handlers::GETHandler} that serves static files
+      def serve(path)
+        register(Landline::Handlers::Serve.new(path, parent: @origin))
+      end
+    end
+  end
+end

data/lib/landline/dsl/constructors_probe.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Landline
+  module DSL
+    # Probe (and subclasses) DSL construct
+    module ProbeConstructors
+      # Create a new erb template
+      # @see {Landline::Template#new}
+      def erb(input, vars = {})
+        Landline::Templates::ERB.new(input,
+                                 vars,
+                                 parent: @origin)
+      end
+
+      # Create a new erb template using Erubi engine
+      # @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)
+        Landline::Templates::Erubi.new(input,
+                                   vars,
+                                   parent: @origin,
+                                   freeze: freeze,
+                                   capture: capture)
+      end
+    end
+  end
+end

data/lib/landline/dsl/methods_common.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Landline
+  module DSL
+    # Methods shared by probes, preprocessors and filters.
+    module CommonMethods
+      # Stop execution and generate a boilerplate response with the given code
+      # @param errorcode [Integer]
+      # @param backtrace [Array(String), nil]
+      # @raise [UncaughtThrowError] throws :finish to return back to Server
+      def die(errorcode, backtrace: nil)
+        throw :finish, [errorcode].append(
+          *(@origin.properties["handle.#{errorcode}"] or
+            @origin.properties["handle.default"]).call(
+              errorcode,
+              backtrace: backtrace
+            )
+        )
+      end
+
+      # Bounce request to the next handler
+      # @raise [UncaughtThrowError] throws :break to get out of the callback
+      def bounce
+        throw :break
+      end
+    end
+  end
+end

data/lib/landline/dsl/methods_path.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Landline
+  # Shared DSL methods
+  module DSL
+    # Common path methods
+    module PathMethods
+      # Set path index
+      # @param index [Array,String]
+      def index(index)
+        case index
+        when Array
+          @origin.properties['index'] = index
+        when String
+          @origin.properties['index'] = [index]
+        else
+          raise ArgumentError, "index should be an Array or a String"
+        end
+      end
+
+      # Set root path (appends matched part of the path).
+      # @param path [String]
+      def root(path)
+        @origin.root = path
+      end
+
+      # Set root path (without appending matched part).
+      # @param path [String]
+      def remap(path)
+        @origin.remap = path
+      end
+
+      # Add a preprocessor to the path.
+      # Does not modify path execution.
+      # @param block [#call]
+      # @yieldparam request [Landline::Request]
+      def preprocess(&block)
+        @origin.preprocess(&block)
+        block
+      end
+
+      # Add a postprocessor to the path.
+      # @param block [#call]
+      # @yieldparam request [Landline::Request]
+      # @yieldparam response [Landline::Response]
+      def postprocess(&block)
+        @origin.postprocess(&block)
+        block
+      end
+
+      # Add a filter to the path.
+      # Blocks path access if a filter returns false.
+      # @param block [#call]
+      # @yieldparam request [Landline::Request]
+      def filter(&block)
+        @origin.filter(&block)
+        block
+      end
+
+      # Include an application as a child of path.
+      # @param filename [String]
+      def plugin(filename)
+        self.define_singleton_method(:run) do |object|
+          unless object.is_a? Landline::Node
+            raise ArgumentError, "not a node instance or subclass instance"
+          end
+
+          object
+        end
+        @origin.children.append(self.instance_eval(File.read(filename)))
+        self.singleton_class.undef_method :run
+      end
+    end
+  end
+end

data/lib/landline/dsl/methods_probe.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative '../response'
+require_relative '../util/multipart'
+require_relative '../util/parseutils'
+require_relative '../util/html'
+
+module Landline
+  module DSL
+    # Common methods for Probe objects
+    module ProbeMethods
+      # Get the current request
+      # @return [Landline::Request]
+      def request
+        @origin.request
+      end
+
+      # Set response status (generate response if one doesn't exist yet)
+      # @param status [Integer] http status code
+      def status(status)
+        @origin.response = (@origin.response or Landline::Response.new)
+        @origin.response.status = status
+      end
+
+      alias code status
+
+      # Set response header (generate response if one doesn't exist yet)
+      # @param key [String] header name
+      # @param value [String] header value
+      def header(key, value)
+        return status(value) if key.downcase == "status"
+
+        unless key.match(Landline::Util::HeaderRegexp::TOKEN)
+          raise ArgumentError, "header key has invalid characters"
+        end
+
+        unless value&.match(Landline::Util::HeaderRegexp::PRINTABLE)
+          raise ArgumentError, "value key has invalid characters"
+        end
+
+        @origin.response = (@origin.response or Landline::Response.new)
+        key = key.downcase
+        @origin.response.add_header(key, value)
+      end
+
+      # Delete a header value from the headers hash
+      # If no value is provided, deletes all key entries
+      # @param key [String] header name
+      # @param value [String, nil] header value
+      def delete_header(key, value = nil)
+        return unless @origin.response
+
+        return if key.downcase == "status"
+
+        unless key.match(Landline::Util::HeaderRegexp::TOKEN)
+          raise ArgumentError, "header key has invalid characters"
+        end
+
+        unless value&.match(Landline::Util::HeaderRegexp::PRINTABLE)
+          raise ArgumentError, "value key has invalid characters"
+        end
+
+        @origin.response.delete_header(key, value)
+      end
+
+      # Set response cookie
+      # @see Landline::Cookie.new
+      def cookie(*params, **options)
+        @origin.response = (@origin.response or Landline::Response.new)
+        @origin.response.add_cookie(
+          Landline::Cookie.new(*params, **options)
+        )
+      end
+
+      # Delete a cookie
+      # If no value is provided, deletes all cookies with the same key
+      # @param key [String] cookie key
+      # @param value [String, nil] cookie.value
+      def delete_cookie(key, value = nil)
+        return unless @origin.response
+
+        @origin.response.delete_cookie(key, value)
+      end
+
+      # 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
+      end
+
+      # Returns formdata
+      # @return [Hash{String=>(String,Landline::Util::FormPart)}]
+      def form
+        _, opts = Landline::Util::ParserCommon.parse_value(
+          request.headers["content-type"]
+        )
+        Landline::Util::MultipartParser.new(
+          request.input, opts["boundary"]
+        ).to_h
+      end
+
+      # 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
+
+      # Escape HTML entities
+      # @see Landline::Util.escape_html
+      def escape_html(text)
+        Landline::Util.escape_html(text)
+      end
+
+      # Unescape HTML entities
+      # @see Landline::Util.escape_html
+      def unescape_html(text)
+        Landline::Util.unescape_html(text)
+      end
+    end
+  end
+end

data/lib/landline/dsl/methods_template.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'securerandom'
+
+module Landline
+  module DSL
+    # Common methods for template contexts
+    module TemplateMethods
+      # Import a template part
+      def import(filepath)
+        @parent_template.import(file(filepath)).run
+      end
+    end
+  end
+end

data/lib/landline/node.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'pattern_matching/util'
+
+module Landline
+  # Abstract class that reacts to request navigation.
+  # Does nothing by default, behaviour should be overriden through
+  # #reject and #process
+  # @abstract
+  class Node
+    # @param path [Object]
+    # @param filepath [Boolean] should Node modify request.filepath.
+    def initialize(path, parent:, filepath: true)
+      @pattern = Pattern.new(path).freeze
+      @properties = Landline::Util::Lookup.new(parent&.properties)
+      @root = nil
+      @remap = false
+      @modify_filepath = filepath
+    end
+
+    # Set Node file root (like root in Nginx)
+    # @param path [String]
+    def root=(path)
+      raise ArgumentError, "path should be a String" unless path.is_a? String
+
+      @properties["path"] = File.expand_path(path)
+      @root = File.expand_path(path)
+    end
+
+    # Set Node absolute file path (like alias in Nginx)
+    # @param path [String]
+    def remap=(path)
+      self.root = path
+      @remap = true
+    end
+
+    # Try to navigate the path. Run method callback in response.
+    # @param [Landline::Request]
+    # @return [Boolean]
+    def go(request)
+      # rejected at pattern
+      return reject(request) unless @pattern.match?(request.path)
+
+      request.push_state
+      path, splat, param = @pattern.match(request.path)
+      do_filepath(request, request.path.delete_suffix(path))
+      request.path = path
+      request.splat.append(*splat)
+      request.param.merge!(param)
+      value = process(request)
+      # rejected at callback - restore state
+      request.pop_state unless value
+      # finally, return process value
+      value
+    end
+
+    # Method callback on failed request navigation
+    # @param _request [Landline::Request]
+    # @return false
+    def reject(_request)
+      false
+    end
+
+    # Method callback on successful request navigation
+    # @param _request [Landline::Request]
+    # @return true
+    def process(_request)
+      true
+    end
+
+    attr_reader :remap, :root
+
+    private
+
+    # Process filepath for request
+    def do_filepath(request, path)
+      return unless @modify_filepath
+
+      if @root
+        request.filepath = "#{@root}/#{@remap ? '' : path}/"
+      else
+        request.filepath += "/#{path}/"
+      end
+      request.filepath.gsub!(/\/+/, "/")
+    end
+  end
+end