syntropy 0.32.0 → 0.34.0

data/lib/syntropy/request/mock_adapter.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Syntropy
+  # Implements a mock adapter for testing
   class MockAdapter
     attr_reader :response_body, :response_headers, :calls
 
@@ -19,14 +20,13 @@ module Syntropy
     end
 
     def initialize(request_body)
-      case request_body
-      when Array
-        @request_body_chunks = request_body
-      when nil
-        @request_body_chunks = []
-      else
-        @request_body_chunks = [request_body]
-      end
+      @request_body_chunks =
+        case request_body
+        when Array then request_body
+        when nil   then []
+        else            [request_body]
+        end
+
       @calls = []
     end
 
@@ -47,6 +47,8 @@ module Syntropy
       response_headers[':status'] || HTTP::OK
     end
 
+    def respond_to_missing?(sym) = true
+
     def method_missing(sym, *args)
       calls << [sym, *args]
     end

data/lib/syntropy/request/request_info.rb

@@ -3,36 +3,61 @@
 require 'uri'
 
 module Syntropy
+  # Request information extension methods.
   module RequestInfoMethods
+    # Returns the request host.
+    #
+    # @return [String, nil]
     def host
       @headers['host'] || @headers[':authority']
     end
     alias_method :authority, :host
 
+    # Returns the connection header value.
+    #
+    # @return [String, nil]
     def connection
       @headers['connection']
     end
 
+    # Returns the upgrade protocol.
+    #
+    # @return [String, nil]
     def upgrade_protocol
       connection == 'upgrade' && @headers['upgrade']&.downcase
     end
 
+    # Returns the websocket version.
+    #
+    # @return [String, nil]
     def websocket_version
       headers['sec-websocket-version'].to_i
     end
 
+    # Returns the protocol.
+    #
+    # @return [String, nil]
     def protocol
       @protocol ||= @adapter.protocol
     end
 
+    # Returns the HTTP method in lower case.
+    #
+    # @return [String]
     def method
       @method ||= @headers[':method'].downcase
     end
 
+    # Returns the request scheme.
+    #
+    # @return [String, nil]
     def scheme
       @scheme ||= @headers[':scheme']
     end
 
+    # Returns the request content type.
+    #
+    # @return [String, nil]
     def content_type
       ct = @headers['content-type']
       return nil if !ct
@@ -59,22 +84,37 @@ module Syntropy
       self
     end
 
+    # Returns the parsed request URI.
+    #
+    # @return [URI::Generic]
     def uri
       @uri ||= URI.parse(@headers[':path'] || '')
     end
 
+    # Returns the parsed full request URI.
+    #
+    # @return [URI::HTTP]
     def full_uri
       @full_uri = "#{scheme}://#{host}#{uri}"
     end
 
+    # Returns the request path.
+    #
+    # @return [String]
     def path
       @path ||= uri.path
     end
 
+    # Returns the request (unparsed) query string.
+    #
+    # @return [String, nil]
     def query_string
       @query_string ||= uri.query
     end
 
+    # Returns the parsed query hash.
+    #
+    # @return [Hash]
     def query
       return @query if @query
 
@@ -83,6 +123,10 @@ module Syntropy
 
     QUERY_KV_REGEXP = /([^=]+)(?:=(.*))?/
 
+    # Converts a query string into a query hash
+    #
+    # @param query [String]
+    # @return [Hash]
     def parse_query(query)
       query.split('&').each_with_object({}) do |kv, h|
         k, v = kv.match(QUERY_KV_REGEXP)[1..2]
@@ -90,10 +134,16 @@ module Syntropy
       end
     end
 
+    # Returns the request ID.
+    #
+    # @return [String, nil]
     def request_id
       @headers['x-request-id']
     end
 
+    # Returns the forwarded for value.
+    #
+    # @return [String, nil]
     def forwarded_for
       @headers['x-forwarded-for']
     end
@@ -107,6 +157,9 @@ module Syntropy
       encoding.split(',').map { |i| i.strip }
     end
 
+    # Returns the parsed cookie values.
+    #
+    # @return [String, nil]
     def cookies
       @cookies ||= parse_cookies(headers['cookie'])
     end
@@ -114,6 +167,10 @@ module Syntropy
     COOKIE_RE = /^([^=]+)=(.*)$/.freeze
     SEMICOLON = ';'
 
+    # Parses the cookie string.
+    #
+    # @param cookies [String]
+    # @return [Hash]
     def parse_cookies(cookies)
       return {} unless cookies
 
@@ -139,6 +196,9 @@ module Syntropy
       raise Syntropy::Error.new('Invalid form data', HTTP::BAD_REQUEST)
     end
 
+    # Returns true if the user-agent is a browser.
+    #
+    # @return [bool]
     def browser?
       user_agent = headers['user-agent']
       user_agent && user_agent =~ /^Mozilla\//
@@ -156,6 +216,9 @@ module Syntropy
       @accept_parts.include?(mime_type)
     end
 
+    # Returns the bearer token.
+    #
+    # @return [String, nil]
     def auth_bearer_token
       auth = headers['authorization']
       if auth && (m = auth.match(/Bearer\s+([^\w]+)/))
@@ -167,12 +230,22 @@ module Syntropy
 
     private
 
+    # Parses an accept string into an array of accepted MIME types.
+    #
+    # @param accept [string]
+    # @return [Array<String>]
     def parse_accept_parts(accept)
       accept.split(',').map { it.match(/^\s*([^\s;]+)/)[1] }
     end
   end
 
+  # Request info class methods
   module RequestInfoClassMethods
+    # Parses form data into a hash
+    #
+    # @param body [String]
+    # @param headers [Hash]
+    # @return [Hash]
     def parse_form_data(body, headers)
       case (content_type = headers['content-type'])
       when /^multipart\/form\-data; boundary=([^\s]+)/
@@ -185,6 +258,11 @@ module Syntropy
       end
     end
 
+    # Parses a multipart form body.
+    #
+    # @param body [String]
+    # @param boundary [String]
+    # @return [Hash]
     def parse_multipart_form_data(body, boundary)
       parts = body.split(boundary)
       raise BadRequestError, 'Invalid form data' if parts.size < 2
@@ -197,6 +275,11 @@ module Syntropy
       end
     end
 
+    # Parses a multipart form data part.
+    #
+    # @param body [String]
+    # @param hash [Hash] output hash
+    # @return [void]
     def parse_multipart_form_data_part(part, hash)
       body, headers = parse_multipart_form_data_part_headers(part)
       disposition = headers['content-disposition'] || ''
@@ -211,6 +294,10 @@ module Syntropy
       end
     end
 
+    # Parses a multipart form data part headers.
+    #
+    # @param part [String]
+    # @return [Hash]
     def parse_multipart_form_data_part_headers(part)
       headers = {}
       while true
@@ -234,6 +321,10 @@ module Syntropy
     MAX_PARAMETER_NAME_SIZE = 256
     MAX_PARAMETER_VALUE_SIZE = 2**20 # 1MB
 
+    # Parses a URL-encoded form.
+    #
+    # @param body [String]
+    # @return [Hash]
     def parse_urlencoded_form_data(body)
       return {} unless body
 

data/lib/syntropy/request/response.rb

@@ -7,18 +7,7 @@ require_relative '../http/status'
 require_relative '../mime_types'
 
 module Syntropy
-  module StaticFileCaching
-    class << self
-      def file_stat_to_etag(stat)
-        "#{stat.mtime.to_i.to_s(36)}#{stat.size.to_s(36)}"
-      end
-
-      def file_stat_to_last_modified(stat)
-        stat.mtime.httpdate
-      end
-    end
-  end
-
+  # Response methods.
   module ResponseMethods
     WEBSOCKET_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
 
@@ -105,8 +94,8 @@ module Syntropy
       adapter.set_response_headers(headers)
     end
 
-    def set_cookie(*)
-      adapter.set_cookie(*)
+    def set_cookie(k, v)
+      adapter.set_cookie(k, v)
     end
 
     def upgrade(protocol, custom_headers = nil, &block)

data/lib/syntropy/request/validation.rb

@@ -3,6 +3,7 @@
 require 'uri'
 
 module Syntropy
+  # Request validation methods.
   module RequestValidationMethods
 
     # Checks the request's HTTP method against the given accepted values. If not

data/lib/syntropy/request.rb

@@ -3,19 +3,26 @@
 require_relative './request/request_info'
 require_relative './request/validation'
 require_relative './request/response'
+require_relative './session'
 require_relative './http/status'
 
 module Syntropy
+  # Syntropy::Request represents an HTTP request. By interacting with the
+  # request, the app can extract request information and respond to the request.
   class Request
     include RequestInfoMethods
     include RequestValidationMethods
     include ResponseMethods
-
     extend RequestInfoClassMethods
 
     attr_reader :headers, :adapter, :start_stamp, :route_params
     attr_accessor :route
 
+    # Initializes the request.
+    #
+    # @param headers [Hash] request headers
+    # @param adapter [Object] connection adapter
+    # @return [void]
     def initialize(headers, adapter)
       @headers  = headers
       @adapter  = adapter
@@ -25,37 +32,62 @@ module Syntropy
       @ctx = nil
     end
 
-    # Returns the request context
+    # Returns the request context, used to store auxiliary information.
+    #
+    # @return [Hash] request context hash
     def ctx
       @ctx ||= {}
     end
 
+    # Returns the next request body chunk.
+    #
+    # @return [String, nil]
     def next_chunk
       @adapter.get_body_chunk(self)
     end
 
+    # Reads request body chunks until the entire body is consumed, yielding each
+    # chunk to the given block.
+    #
+    # @return [void]
     def each_chunk
       while (chunk = @adapter.get_body_chunk(self))
         yield chunk
       end
     end
 
+    # Reads the request body.
+    #
+    # @return [String, nil] request body
     def read
       @adapter.get_body(self)
     end
     alias_method :body, :read
 
+    # Returns true if the request body has been consumed.
+    #
+    # @return [bool]
     def complete?
       @adapter.complete?(self)
     end
 
     EMPTY_HEADERS = {}.freeze
 
+    # Sends a response.
+    #
+    # @param body [String, nil] response body
+    # @param headers [Hash] response headers
+    # @return [void]
     def respond(body, headers = EMPTY_HEADERS)
       @adapter.respond(self, body, headers)
       @headers_sent = true
     end
 
+    # Sends response headers.
+    #
+    # @param headers [Hash] response headers
+    # @param empty_response [bool] body should be sent
+    # @return [void]
     def send_headers(headers = EMPTY_HEADERS, empty_response = false)
       return if @headers_sent
 
@@ -63,6 +95,11 @@ module Syntropy
       @adapter.send_headers(self, headers, empty_response: empty_response)
     end
 
+    # Sends a response body chunk.
+    #
+    # @param body [String] response body chunk
+    # @param done [bool] body is complete
+    # @return [void]
     def send_chunk(body, done: false)
       send_headers({}) unless @headers_sent
 
@@ -70,30 +107,34 @@ module Syntropy
     end
     alias_method :<<, :send_chunk
 
+    # Finish response.
+    #
+    # @return [void]
     def finish
       send_headers({}) unless @headers_sent
 
       @adapter.finish(self)
     end
 
+    # Returns true if response headers were sent.
+    #
+    # @return [bool]
     def headers_sent?
       @headers_sent
     end
 
-    def rx_incr(count)
-      headers[':rx'] ? headers[':rx'] += count : headers[':rx'] = count
-    end
-
-    def tx_incr(count)
-      headers[':tx'] ? headers[':tx'] += count : headers[':tx'] = count
-    end
-
-    def transfer_counts
-      [headers[':rx'], headers[':tx']]
+    # Returns the request session.
+    #
+    # @return [Syntropy::Session]
+    def session
+      @session ||= Session.new(self)
     end
 
-    def total_transfer
-      (headers[':rx'] || 0) + (headers[':tx'] || 0)
+    # Returns the request flash session storage.
+    #
+    # @return [Syntropy::Session::Flash]
+    def flash
+      session.flash
     end
   end
 end

data/lib/syntropy/routing_tree.rb

@@ -5,7 +5,7 @@ module Syntropy
   # static files, markdown files, ruby modules, parametric routes, subtree routes,
   # nested middleware and error handlers.
   #
-  # A RoutingTree instance takes the given directory (root_dir) and constructs a
+  # A RoutingTree instance takes the given directory (app_root) and constructs a
   # tree of route entries corresponding to the directory's contents. Finally, it
   # generates an optimized router proc, which is used by the application to return
   # a route entry for each incoming HTTP request.
@@ -41,15 +41,15 @@ module Syntropy
   #   allows you to prevent access through the HTTP server to protected or
   #   internal modules or files.
   class RoutingTree
-    attr_reader :root_dir, :mount_path, :static_map, :dynamic_map, :root
+    attr_reader :app_root, :mount_path, :static_map, :dynamic_map, :root
 
     # Initializes a new RoutingTree instance and computes the routing tree
     #
-    # @param root_dir [String] root directory of file tree
+    # @param app_root [String] root directory of file tree
     # @param mount_path [String] base URL path
     # @return [void]
-    def initialize(root_dir:, mount_path:, **env)
-      @root_dir = root_dir
+    def initialize(app_root:, mount_path:, **env)
+      @app_root = app_root
       @mount_path = mount_path
       @static_map = {}
       @dynamic_map = {}
@@ -72,7 +72,7 @@ module Syntropy
     # @param fn [String] file path
     # @return [String] clean path
     def compute_clean_url_path(fn)
-      rel_path = fn.sub(@root_dir, '')
+      rel_path = fn.sub(@app_root, '')
       case rel_path
       when /^(.*)\/index\.(md|rb|html)$/
         Regexp.last_match(1).then { it == '' ? '/' : it }
@@ -88,7 +88,7 @@ module Syntropy
     # @param fn [String] filename
     # @return [String] relative path
     def fn_to_rel_path(fn)
-      fn.sub(/^#{Regexp.escape(@root_dir)}\//, '').sub(/\.[^\.]+$/, '')
+      fn.sub(/^#{Regexp.escape(@app_root)}\//, '').sub(/\.[^\.]+$/, '')
     end
 
     # Mounts the given applet on the routng tree at the given (absolute) mount
@@ -142,7 +142,7 @@ module Syntropy
     #
     # @return [Hash] root entry
     def compute_tree
-      compute_route_directory(dir: @root_dir, rel_path: '/', parent: nil)
+      compute_route_directory(dir: @app_root, rel_path: '/', parent: nil)
     end
 
     # Converts the given absolute path to a relative one (relative to the
@@ -233,7 +233,7 @@ module Syntropy
     # @return [String, nil] file path if found
     def find_aux_module_entry(dir, name)
       fn = File.join(dir, name)
-      File.file?(fn) ? ({ kind: :module,  fn: }) : nil
+      File.file?(fn) ? { kind: :module,  fn: } : nil
     end
 
     # Returns a hash mapping file/dir names to route entries.
@@ -247,10 +247,10 @@ module Syntropy
 
         rel_path = compute_clean_url_path(fn)
         child = if File.file?(fn)
-          compute_route_file(fn:, rel_path:, parent:)
-        elsif File.directory?(fn)
-          compute_route_directory(dir: fn, rel_path:, parent:)
-        end
+                  compute_route_file(fn:, rel_path:, parent:)
+                elsif File.directory?(fn)
+                  compute_route_directory(dir: fn, rel_path:, parent:)
+                end
         map[child_key(child)] = child if child
       }
     end
@@ -317,7 +317,6 @@ module Syntropy
       set_index_route_target(parent:, path:, kind:, fn:, handle_subtree:)
     end
 
-
     # Sets an index route target for the given parent entry. Index files are
     # applied as targets to the immediate containing directory. HTML index files
     # are considered static and therefore not added to the routing tree.
@@ -329,7 +328,7 @@ module Syntropy
     # @param handle_subtree [bool] whether the target handles the subtree
     # @return [nil] (prevents addition of an index route)
     def set_index_route_target(parent:, path:, kind:, fn:, handle_subtree: nil)
-      if is_parametric_route?(parent) || handle_subtree
+      if parametric_route?(parent) || handle_subtree
         @dynamic_map[path] = parent
         parent[:target] = { kind:, fn: }
         parent[:handle_subtree] = handle_subtree
@@ -383,7 +382,7 @@ module Syntropy
     # @param entry [Hash] route entry
     def make_route_entry(entry)
       path = entry[:path]
-      if is_parametric_route?(entry) || entry[:handle_subtree]
+      if parametric_route?(entry) || entry[:handle_subtree]
         @dynamic_map[path] = entry
       else
         entry[:static] = true
@@ -394,8 +393,8 @@ module Syntropy
     # returns true if the route or any of its ancestors are parametric.
     #
     # @param entry [Hash] route entry
-    def is_parametric_route?(entry)
-      entry[:param] || (entry[:parent] && is_parametric_route?(entry[:parent]))
+    def parametric_route?(entry)
+      entry[:param] || (entry[:parent] && parametric_route?(entry[:parent]))
     end
 
     # Converts a relative URL path to absolute URL path.
@@ -468,7 +467,7 @@ module Syntropy
         emit_router_proc_postlude(buffer, default_route_path: wildcard_root && @root[:path])
       end
 
-      buffer#.tap { puts '*' * 40; puts it; puts }
+      buffer # .tap { puts '*' * 40; puts it; puts }
     end
 
     # Emits optimized code for a childless wildcard router.
@@ -540,7 +539,7 @@ module Syntropy
         return
       end
 
-      if is_void_route?(entry)
+      if void_route?(entry)
         parent = entry[:parent]
         parametric_sibling = parent && parent[:children] && parent[:children]['[]']
         if parametric_sibling
@@ -580,7 +579,7 @@ module Syntropy
     # @param entry [Hash] route entry
     # @return [Hash, nil] route target if exists
     def find_target_in_subtree(entry)
-      entry[:children]&.values&.each { |e|
+      entry[:children]&.each_value { |e|
         target = e[:target] || find_target_in_subtree(e)
         return target if target
       }
@@ -593,14 +592,14 @@ module Syntropy
     #
     # @param entry [Hash] route entry
     # @return [bool]
-    def is_void_route?(entry)
+    def void_route?(entry)
       return false if entry[:param] || entry[:target]
+      return true if entry[:static]
 
-      if entry[:children]
-        return true if !entry[:children]['[]'] && entry[:children]&.values&.all? { is_void_route?(it) }
-      else
-        return true if entry[:static]
-      end
+      children = entry[:children]
+      return false if !children
+
+      return true if !children['[]'] && children.values.all? { void_route?(it) }
 
       false
     end
@@ -640,7 +639,7 @@ module Syntropy
 
         elsif has_children
           # otherwise look at the next segment
-          next if is_void_route?(child_entry) && !param_entry
+          next if void_route?(child_entry) && !param_entry
 
           when_buffer = +''
           visit_routing_tree_entry(buffer: when_buffer, entry: child_entry, indent: indent + 1, segment_idx: segment_idx + 1)