landline 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6713c809dcb1f2216afff7f05d00e932c85d36c1b205359a2c8f8655b79fbb1
-  data.tar.gz: 34846e521a08d55376a520a194417edf0cb66972bf6c052ac6fb5d888fea30f2
+  metadata.gz: 290ba72a21e71891ae33e361aea7afcff00d98429f96b303e061158c3bd34520
+  data.tar.gz: 545debbdab28e39eaa6f94e588bfcf371259cbcd6e33399517d7c3d3bd4393da
 SHA512:
-  metadata.gz: b54438875d8532e95858567f0305b03baf00a6c88a735851116be73ea2b7619031226624ff846d05a7439050deff1b02acfe5c5a7d1a8afdb8e67b2ea6b520a1
-  data.tar.gz: 03031f8d28c5e8657854cdff63e4f205d9b553cb03e34109b761a5f65207fd473005a61a5504a3f96517a37fe2d1f1b234b733916a3bd5f33f4de0e64a30fbab
+  metadata.gz: 3e0b7da7816dcfba10f2e3db537344b6057ca7377da5a6a9e3b8aa4892883d417339cce001935705ebf60816eb9a2965501de5adae111235e79c551b0ede6f5a
+  data.tar.gz: 2177431dd21d534a1936541f287647bb23ced5968bada8b7a642b44f5d21c16f4cc4690654a11ee6194d62dc7027511a819c69ab123ce81d562ee166cf20157f

data/README.md

@@ -194,7 +194,7 @@ For things to render correctly, please install the `redcarpet` gem.
 
 ```plain
     Landline - an HTTP request pattern matching system 
-    Copyright (C) 2022 yessiest (yessiest@text.512mb.org)
+    Copyright (C) 2023-2024 yessiest (yessiest@text.512mb.org)
 
     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

data/STRUCTURE.md

@@ -0,0 +1,129 @@
+# Landline library and application structure
+
+## File layout
+
+- `/landline/lib/*.rb` - core of the library
+- `/landline/lib/dsl/` - module namespaces for use by executable contexts
+- `/landline/lib/path/` - nodes that extend the Path class (traversable
+  node/setup execution context)
+- `/landline/lib/probe/` - nodes that extend the Probe class (executable
+  nodes/per-request execution context)
+- `/landline/lib/template/` - template engine adapters
+- `/landline/lib/util/` - utility classes and modules
+- `/landline/lib/pattern_matching/` - classes that implement path pattern
+  matching (i.e. globs, regex and static traversal paths)
+
+## Architecture overview
+
+The following chapter defines information that pertains to the overall
+structure and interaction of landline's core abstractions - Nodes, Paths
+and Probes.
+
+For context: Node is an element of the path tree, and is another name for a
+Probe (which is a leaf of the tree) or a path (which is an internal vertex
+of the tree)
+
+```plaintext
+Path +-> Path +-> Probe
+     |        |
+     |        +-> Probe
+     +-> Probe
+     |
+     |-> Path -> Probe
+```
+
+### Execution contexts
+
+In Sinatra, which this library takes most of its influence from, every
+request creates its own instance of the Sinatra application. This seemed
+like an excessive measure to solve a trivial problem of race conditions on a
+shared execution context, so to solve that, Landline introduces per-request
+execution contexts, which have a life time that spans the duration of
+request processing.
+
+In short, there are two distinct execution contexts:
+
+- Per-request execution context, which is used by blocks that process the
+  request and which is bound to that given request
+- Setup execution context, in which the Landline node tree is constructed
+
+For every Path-like node, the supplied block is executed in the setup
+context bound to that path.
+
+For every Probe-like node, the supplied block is executed in the per-request
+context of the request that is passed to the probe.
+
+These execution contexts also affect the receivers of the instance variable
+write and read operations. Additionally, the two types have different
+sets of available methods, and every DSL method has a description attached
+which describes in which context that method can be used (this is due to the
+limitations of the YARD parser and due to the need of showing method
+descriptions in the IDE)
+
+### Request traversal
+
+Requests in Landline traverse through a series of paths that determine
+which route the request would take. All nodes are organized in a tree
+structure, where the root of the tree is a Server object that handles
+things likes localized jumps, request/response conversion and response
+finalization, and root-level error/`die()` handling.
+
+Every path-like node can be supplied with callbacks that perform
+the following functions:
+
+- filters - callbacks that filter incoming request objects
+- preprocessors - callbacks that don't usually affect the routing decision
+  but can modify requests before they come through
+- postprocessors - callbacks that execute either when a request exits a
+  given path after not finding any suitable probe-like node or when a
+  response to a request is being finalized
+- pipeline - single callback that is injected in the execution stack that
+  can be used to catch throws and exceptions
+
+(see `/examples/logging.ru`, `/examples/norxondor_gorgonax/config.ru`)
+
+The execution contexts for every callback (except pipeline) are shared with
+those of the probe-like execution contexts, meaning that an instance
+variable written to in a filter or a preprocessor can be accessed from the
+probe node or a postprocessor callback.
+
+Once all preprocessors and filters are finished successfully, the request
+is passed to all subsequent graph elements (either other Paths or Probes)
+to check whether a given Node accepts that element.
+
+If the subtree of the path contains at least one probe that accepts the
+request, that probe finishes processing the request and either exits
+the tree immediately by throwing the `:finish` signal with a response
+or by returning a valid (not nil) response from the `process` method,
+in which case the response ascends from the probe back to the root.
+
+If none of the subsequent elements of a path accepted the request, the
+path executes `die(404)` if `bounce` is not enabled, and if `bounce` is
+enabled, the request exits from the path and proceeds to sibling
+(adjacent) paths. (see `/examples/dirbounce.ru`)
+
+A probe can finish the request by either throwing a response, by executing a
+jump to another path, by explicitly dying with a status code or by throwing
+an exception (which effectively causes `die(500)`)
+(see `/examples/errorpages.ru`, `/examples/jumps.ru`)
+
+If a jump is executed, the path of the request is rewritten locally, and the
+request is fed through the server again for processing. This is effectively
+a localized redirect which retains accumulated request processing
+information (i.e. instance variables)
+(see `/examples/jumps.ru`)
+
+The tree can be changed at runtime, but it's generally not advisable to
+depend on that fact. If, eventually, some solution will be found to
+optimizing trees into linear routing paths, and if that solution is proven
+to improve performance, this statement might become false.
+
+```plaintext
+                             +--------------------------------------+
+                             v                                      |
+run (obj) -> App#call -> Server#call +-> Path#go -> ... -> Probe#go +
+                             |       | (if app acts as a wrapper for another
+     <-----------------------+       | Rack server and if response is 404
+     (returns back to Rack server    | with x-cascade header set)
+      if no jumps occured)           +-> passthrough#call
+```

data/lib/landline/dsl/methods_common.rb

@@ -9,14 +9,17 @@ module Landline
       # @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
-            )
+      def die(errorcode, backtrace: nil, error: nil)
+        response = Landline::Response.convert(
+          (@origin.properties["handle.#{errorcode}"] or
+           @origin.properties["handle.default"]).call(
+             errorcode,
+             backtrace: backtrace,
+             error: error
+           )
         )
+        response.status = errorcode if response.status == 200
+        throw :finish, response
       end
 
       # (in Landline::Probe context)

data/lib/landline/extensions/session.rb

@@ -84,7 +84,7 @@ module Landline
         @session = Landline::Session::Session.new(
           request.cookies.dig('session', 0)&.value,
           proc do |value|
-            delete_cookie("session", value)
+            delete_cookie("session")
             cookie("session", value)
           end
         )

data/lib/landline/extensions/websocket.rb

@@ -24,28 +24,6 @@ module Landline
         @__listeners[event]&.delete(listener)
       end
 
-      # Await for an event
-      # @param event [Symbol, Array<Symbol>] event or array of events to wait for
-      # @return [Array]
-      # @sg-ignore
-      def await(event)
-        blocking = true
-        output = nil
-        listener = proc do |*data|
-          output = data
-          blocking = false
-        end
-        if event.is_a? Array
-          event.each { |x| on(x, &listener) }
-        else
-          on(event, &listener)
-        end
-        while blocking; end
-        return output[0] if output.is_a? Array and output.length == 1
-
-        output
-      end
-
       private
 
       # Trigger the queue clearing process
@@ -95,19 +73,6 @@ module Landline
         )
         @readable = true
         @writable = true
-        @data = Queue.new
-        on :message do |msg|
-          @data.enq(msg)
-        end
-      end
-
-      # Start the main loop for the eventifier
-      # @return [void]
-      def ready
-        return if @ready
-
-        _loop
-        @ready = true
       end
 
       # Send data through websocket
@@ -125,31 +90,33 @@ module Landline
           type: type
         )
         @io.write(frame.to_s)
+      rescue Errno::EPIPE => e
+        @writable = false
+        _emit :error, e
+        close if @readable
+        nil
       end
 
       # Read data from socket synchronously
-      # @return [String, nil] nil returned if socket closes
+      # @return [WebSocket::Frame::Base, nil] nil if socket received a close event
       def read
         unless @readable
           raise self.class::WebSocketError,
                 "socket closed for reading"
         end
 
-        @data.deq
+        _process_events(proc { _read })
       end
 
-      # Close the socket for reading
-      # @return [void]
-      def close_read
-        _emit :close
-        @readable = false
-        @io.close_read
-      end
+      # Read data from socket without blocking
+      # @return [WebSocket::Frame::Base, nil] nil if socket received a close event
+      def read_nonblock
+        unless @readable
+          raise self.class::WebSocketError,
+                "socket closed for reading"
+        end
 
-      # Close the socket for writing
-      def close_write
-        @writable = false
-        @io.close_write
+        _process_events(proc { _read_nonblock })
       end
 
       # Establish a connection through handshake
@@ -179,58 +146,88 @@ module Landline
         handshake
       end
 
-      # Close the socket
-      # @return [void]
-      def close
-        _close
-        @writable = false
+      # Close socket for reading
+      def close_read
+        raise WebSocketError, 'socket closed for reading' unless @readable
+
+        _emit :close
         @readable = false
+        @io.close_read
+      end
+
+      # Close socket for reading
+      def close_write
+        raise WebSocketError, 'socket closed for writing' unless @writable
+
+        write(nil, type: :close)
+        @writable = false
+        @io.close_write
+      end
+
+      # Close the socket entirely
+      def close
+        raise WebSocketError, 'socket closed' unless @writable or @readable
+
+        close_read if @readable
+        close_write if @writable
       end
 
+      # Obtain internal IO object
+      # @return [IO]
+      def to_io
+        io
+      end
+
+      attr_reader :io, :readable, :writable
+
       private
 
-      # Event reading loop
-      # @return [void]
-      def _loop
-        @thread = Thread.new do
-          loop do
-            msg = _read
-            if msg and [:text, :binary].include? msg.type
-              _emit :message, msg
-            elsif msg and msg.type == :close
-              _emit :__close, msg
-              break
-            end
+      # Process incoming websocket events
+      # @param next_frame [#call] callback to get the next frame
+      # @return [WebSocket::Frame::Base, nil]
+      def _process_events(next_frame)
+        loop do
+          frame = next_frame.call
+          return nil unless frame
+
+          case frame.type
+          when :binary, :text, :pong then return frame
+          when :ping
+            write frame.to_s, type: :pong
+          when :close
+            close_read
+            return nil
+          else raise WebSocketError, "unknown frame type #{frame.type}"
           end
-        rescue IOError => e
-          @writable = false
-          _emit :error, e
-          close
-        ensure
-          close_read
         end
       end
 
       # Receive data through websocket
       # @return [String] output from frame
       def _read
-        while (char = @io.getc)
+        while (char = @io.read(1))
           @frame_parser << char
           frame = @frame_parser.next
           return frame if frame
         end
+      rescue Errno::ECONNRESET => e
+        _emit :error, e
+        close if @readable or @writable
+        nil
       end
 
-      # Close the websocket
-      # @return [void]
-      def _close
-        frame = ::WebSocket::Frame::Outgoing::Server.new(
-          version: @version,
-          type: :close
-        )
-        @io.write(frame.to_s) if @writable
-        sleep 0.1
-        @io.close
+      # Receive data through websocket asynchronously
+      # @return [String] output from frame
+      def _read_nonblock
+        while (char = @io.read_nonblock(1))
+          @frame_parser << char
+          frame = @frame_parser.next
+          return frame if frame
+        end
+      rescue Errno::ECONNRESET => e
+        _emit :error, e
+        close if @readable or @writable
+        nil
       end
     end
   end
@@ -267,6 +264,7 @@ module Landline
             **@params
           )
         )
+        ""
       end
     end
   end

data/lib/landline/path.rb

@@ -37,6 +37,24 @@ module Landline
       context.instance_exec(&setup)
     end
 
+    # (see ::Landline::Node#go)
+    def go(request)
+      # This is done to allow pipeline to interject handlers
+      # I'm more than willing to admit that this is stupid,
+      # but it is well worth the logical flexibility.
+      if ['handle.default', 'handle.505'].any? do |x|
+           @properties.storage.include? x
+         end
+        begin
+          super(request)
+        rescue StandardError => e
+          _die(request, 500, backtrace: [e.to_s] + e.backtrace, error: e)
+        end
+      else
+        super(request)
+      end
+    end
+
     # Method callback on successful request navigation.
     # Finds the next appropriate path to go to.
     # @return [Boolean] true if further navigation will be done
@@ -138,8 +156,6 @@ module Landline
       return exit_stack(request, value) if value
 
       notfound(request)
-    rescue StandardError => e
-      _die(request, 500, backtrace: [e.to_s] + e.backtrace)
     end
 
     # Run enqueued postprocessors on navigation failure
@@ -175,16 +191,19 @@ module Landline
     # @param errorcode [Integer]
     # @param backtrace [Array(String), nil]
     # @raise [UncaughtThrowError] throws :finish to stop processing
-    def _die(request, errorcode, backtrace: nil)
+    def _die(request, errorcode, backtrace: nil, error: nil)
       proccontext = get_context(request)
-      throw :finish, [errorcode].append(
-        *proccontext.instance_exec(
+      response = Landline::Response.convert(
+        proccontext.instance_exec(
           errorcode,
           backtrace: backtrace,
+          error: error,
           &(@properties["handle.#{errorcode}"] or
             @properties["handle.default"])
         )
       )
+      response.status = errorcode if response.status == 200
+      throw :finish, response
     end
   end
 end

data/lib/landline/pattern_matching.rb

@@ -35,7 +35,7 @@ module Landline
     def match(input)
       if @pattern.is_a? String
         input = Landline::PatternMatching.canonicalize(input)
-        if input.start_with?(@pattern)
+        if _match?(input)
           [input.delete_prefix(@pattern), [], {}]
         else
           false
@@ -51,7 +51,8 @@ module Landline
     # @return [Boolean]
     def match?(input)
       if @pattern.is_a? String
-        Landline::PatternMatching.canonicalize(input).start_with? @pattern
+        input = Landline::PatternMatching.canonicalize(input)
+        _match?(input)
       else
         @pattern.match?(input)
       end
@@ -59,6 +60,13 @@ module Landline
 
     private
 
+    def _match?(input)
+      parts = input.split("/")
+      @pattern.split("/").map.with_index do |part, index|
+        parts[index] == part
+      end.all?(true)
+    end
+
     def patternify(pattern)
       classdomain = Landline::PatternMatching
       classdomain.constants

data/lib/landline/server.rb

@@ -58,14 +58,14 @@ module Landline
     def setup_properties(*_args, **_opts)
       {
         "index" => [],
-        "handle.default" => proc do |code, backtrace: nil|
+        "handle.default" => proc do |code, backtrace: nil, **_extra|
           page = Landline::Util.default_error_page(code, backtrace)
           headers = {
             "content-length": page.bytesize,
             "content-type": "text/html",
             "x-cascade": true
           }
-          [headers, page]
+          [code, headers, page]
         end,
         "path" => "/"
       }.each { |k, v| @properties[k] = v unless @properties[k] }

data/lib/landline/util/cookie.rb

@@ -115,6 +115,8 @@ module Landline
 
       data.split(";").map do |cookiestr|
         key, value = cookiestr.match(/([^=]+)=?(.*)/).to_a[1..].map(&:strip)
+        next unless key and value
+
         cookie = Cookie.new(key, value)
         if hash[cookie.key]
           hash[cookie.key].append(cookie)

data/lib/landline/util/lookup.rb

@@ -31,7 +31,7 @@ module Landline
         @storage[key] = value
       end
 
-      attr_accessor :parent
+      attr_accessor :parent, :storage
     end
 
     # Read-only lookup proxy

data/lib/landline/util/multipart.rb

@@ -28,7 +28,7 @@ module Landline
       # Decode charset parameter
       def decode(data)
         data = Landline::Util.unescape_html(data)
-        return data unless self.headers['charset']
+        return data.force_encoding("UTF-8") unless self.headers['charset']
 
         data.force_encoding(self.headers['charset']).encode("UTF-8")
       end

data/lib/landline/util/parseutils.rb

@@ -15,12 +15,16 @@ module Landline
       PRINTCHAR = /[\x2-\x7E]/
       # Matches 1 or more CHARs excluding CTLs
       PRINTABLE = /#{PRINTCHAR}+/o
+      # !! RFC 6265 IS PROPOSED AND NOT AN IMPLEMENTED STANDARD YET !!
       # Matches the RFC6265 definition of a cookie-octet
-      COOKIE_OCTET = /[\x21-\x7E&&[^",;\\]]*/
-      COOKIE_VALUE = /(?:#{QUOTED}|#{COOKIE_OCTET})/o
-      COOKIE_NAME = TOKEN
+      # COOKIE_VALUE = /(?:#{QUOTED}|#{COOKIE_OCTET})/o
+      # COOKIE_NAME = TOKEN
       # Matches the RFC6265 definition of cookie-pair.
       # Captures name (1) and value (2).
+      # !! RFC 6265 IS PROPOSED AND NOT AN IMPLEMENTED STANDARD YET !!
+      COOKIE_OCTET = /[\x21-\x7E&&[^",;\\]]*/
+      COOKIE_NAME = /[^;,=\s]*/
+      COOKIE_VALUE = /[^;,\s]*/
       COOKIE_PAIR = /\A(#{COOKIE_NAME})=(#{COOKIE_VALUE})\z/o
       # Matches a very abstract definition of a quoted header paramter.
       # Captures name (1) and value (2).
@@ -83,7 +87,7 @@ module Landline
         unless input.match? HeaderRegexp::PRINTABLE
           raise Landline::ParsingError, "input is not ascii printable"
         end
-        
+
         opts.each do |key, value|
           check_param(key, value)
           newparam = if [String, Integer].include? value.class

data/lib/landline.rb

@@ -12,11 +12,11 @@ require_relative 'landline/app'
 # Landline is a backend framework born as a by-product of experimentation
 module Landline
   # Landline version
-  VERSION = '0.12.1 "Concrete and Gold" (pre-alpha)'
+  VERSION = '0.13.0 "Realign" (pre-alpha)'
 
   # Landline branding and version
   VLINE = "Landline/#{Landline::VERSION} (Ruby/#{RUBY_VERSION}/#{RUBY_RELEASE_DATE})\n".freeze
 
   # Landline copyright
-  COPYRIGHT = "Copyright 2023 Yessiest"
+  COPYRIGHT = "Copyright 2023-2024 Yessiest"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: landline
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Yessiest
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-07 00:00:00.000000000 Z
+date: 2024-12-10 00:00:00.000000000 Z
 dependencies: []
 description: |
   Landline is a no-hard-dependencies HTTP routing DSL that was made entirely for fun.
@@ -21,10 +21,12 @@ extra_rdoc_files:
 - HACKING.md
 - LICENSE.md
 - README.md
+- STRUCTURE.md
 files:
 - HACKING.md
 - LICENSE.md
 - README.md
+- STRUCTURE.md
 - lib/landline.rb
 - lib/landline/app.rb
 - lib/landline/dsl/constructors_path.rb
@@ -82,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Elegant HTTP DSL