syntropy 0.33.0 → 0.34.1

data/lib/syntropy/request.rb

@@ -3,20 +3,26 @@
 require_relative './request/request_info'
 require_relative './request/validation'
 require_relative './request/response'
-require_relative './request/session'
+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
@@ -26,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
 
@@ -64,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
 
@@ -71,36 +107,32 @@ 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']]
-    end
-
-    def total_transfer
-      (headers[':rx'] || 0) + (headers[':tx'] || 0)
-    end
-
+    # Returns the request session.
+    #
+    # @return [Syntropy::Session]
     def session
       @session ||= Session.new(self)
     end
 
+    # Returns the request flash session storage.
+    #
+    # @return [Syntropy::Session::Flash]
     def flash
       session.flash
     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)

data/lib/syntropy/session.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'securerandom'
+
+module Syntropy
+  # A Session object serves as storage for data associated with the user's
+  # browser session, such as flash data (for communicating notices and alerts).
+  # The session is modeled as a key-value store, where keys are strings, and
+  # values can be any value that can be represented in JSON, including arrays
+  # and hashes.
+  #
+  # The session data is stored as an HTTP cookie.
+  class Session
+    # Initializes the session.
+    #
+    # @param request [Syntropy::Request] associated request
+    # @return [void]
+    def initialize(request)
+      @request = request
+      @data = nil
+    end
+
+    # Returns the value associated with the given key.
+    #
+    # @param key [String]
+    # @return [any] value
+    def [](key)
+      @data ||= load
+      @data[key]
+    end
+
+    # Sets the value for the given key and updates the response session cookie.
+    #
+    # @param key [String]
+    # @param value [any]
+    # @return [void]
+    def []=(key, value)
+      @data ||= load
+      @data[key] = value
+      save(@data)
+    end
+
+    # Deletes the given key-value pair and updates the response session cookie.
+    #
+    # @param key [String]
+    # @return [any] deleted value
+    def delete(key)
+      @data ||= load
+      value = @data.delete(key)
+      save(@data.empty? ? nil : @data)
+      value
+    end
+
+    # Discards the session data, updating the response session cookie by
+    # emptying it.
+    #
+    # @return [void]
+    def discard
+      save(nil)
+    end
+
+    # Returns the flash storage for the session.
+    #
+    # @return [Syntropy::Session::Flash]
+    def flash
+      @data ||= load
+      @flash ||= Flash.new(self)
+    end
+
+    private
+
+    # Loads session data from the request session cookie.
+    #
+    # @return [Hash] session data
+    def load
+      data = @request.cookies['__syntropy_session__']
+      return {} if !data
+
+      JSON.parse(Base64.decode64(data))
+    rescue JSON::ParserError
+      {}
+    ensure
+      @loaded = true
+    end
+
+    # Saves session data to the response session cookie.
+    #
+    # @param data [Hash] session data
+    # @return [void]
+    def save(data)
+      cookie = data ? "#{Base64.strict_encode64(JSON.dump(data))}; Path=/; HttpOnly" : nil
+      @request.set_cookie('__syntropy_session__', cookie)
+    end
+  end
+
+  # NowFlash holds flash data for the current request.
+  class NowFlash
+    def initialize
+      @data = {}
+    end
+
+    # Returns the value for the given key.
+    #
+    # @param key [Symbol]
+    # @return [any] flash value
+    def [](key)
+      @data[key.to_s]
+    end
+
+    # Sets the value for the given key.
+    #
+    # @param key [Symbol]
+    # @param value [any]
+    # @return [any] value
+    def []=(key, value)
+      @data[key.to_s] = value
+    end
+
+    # Iterates through the flash storage, yielding each key-value pair to the
+    # given block.
+    #
+    # @return [void]
+    def each(&block)
+      @data.each { |k, v| block.(k.to_sym, v) }
+    end
+  end
+
+  # Flash acts as a special storage mechanism for transient information that
+  # can be passsed between consecutive requests in the same session. Flash
+  # values can be set in order to be retrieved in the next response. Reading
+  # from flash storage will return data that was set in the previous request.
+  # Data written to the flash storage will only be available to the next
+  # request. You can also set flash data that will be available to the current
+  # request by using Flash#now.
+  #
+  # In order to keep the read flash data (set in the previous request) and
+  # make it available to the next request, use Flash#keep.
+  class Flash
+    # Initializes the flash storage.
+    #
+    # @return [void]
+    def initialize(session)
+      @session = session
+      @current_flash_data = @session['_flash']
+      @session.delete('_flash') if @current_flash_data
+      @current_flash_data ||= {}
+      @future_flash_data = {}
+      @now_flash_data = NowFlash.new
+    end
+
+    # Reads data from flash storage for the given key. The value would have
+    # been set in the previous request.
+    #
+    # @param key [Symbol]
+    # @return [any] value
+    def [](key)
+      key = key.to_s
+      @now_flash_data[key] || @current_flash_data[key]
+    end
+
+    # Sets the flash storage value for the given key. The value would be
+    # available to the next request.
+    #
+    # @param key [Symbol]
+    # @param value [any]
+    # @return [void]
+    def []=(key, value)
+      key = key.to_s
+      @future_flash_data[key] = value
+      @session['_flash'] = @future_flash_data
+    end
+
+    # Iterates through the flash storage, passing each key-value pair to the
+    # given block.
+    #
+    # @return [void]
+    def each(&block)
+      @current_flash_data.each_pair { |k, v| block.(k.to_sym, v) }
+    end
+
+    # Persists any flash data set in the previous request to the next request.
+    #
+    # @return [void]
+    def keep
+      @future_flash_data = @current_flash_data.merge!(@future_flash_data)
+      @session['_flash'] = @future_flash_data
+    end
+
+    # Returns the flash storage for the current request.
+    #
+    # @return [Syntropy::NowFlash]
+    def now
+      @now_flash_data
+    end
+  end
+end

data/lib/syntropy/side_run.rb

@@ -3,8 +3,16 @@
 require 'etc'
 
 module Syntropy
+  # SideRun implements running an operation on a separate thread.
   module SideRun
     class << self
+      # Runs the given block on a separate thread, using UringMachine to wait
+      # for the operation to complete. If the operation results in a raised
+      # exception, that exception will be reraised in the context of the waiting
+      # fiber.
+      #
+      # @param machine [UringMachine] machine instance
+      # @return [any] operation return value
       def call(machine, &block)
         setup if !@queue
 
@@ -15,6 +23,11 @@ module Syntropy
         result.is_a?(Exception) ? (raise result) : result
       end
 
+      private
+
+      # Sets up a thread pool for side-running operations.
+      #
+      # @return [void]
       def setup
         @queue = UM::Queue.new
         count = (Etc.nprocessors - 1).clamp(2..6)
@@ -23,9 +36,13 @@ module Syntropy
         }
       end
 
+      # Runs worker loop for running side-run operations.
+      #
+      # @param queue [UringMachine::Queue] queue for pulling operations
+      # @return [void]
       def side_run_worker(queue)
         machine = UM.new
-        loop { handle_request(machine, queue) }
+        loop { run_op(machine, queue) }
       rescue UM::Terminate
         # # We can also add a timeout here
         # t0 = Time.now
@@ -34,7 +51,13 @@ module Syntropy
         # end
       end
 
-      def handle_request(machine, queue)
+      # Pulls an operation from the given queue and runs it, pushing its return
+      # value to the corresponding mailbox.
+      #
+      # @param machine [UringMachine] machine instance
+      # @param queue [UringMachine::Queue] op queue
+      # @return [void]
+      def run_op(machine, queue)
         response_mailbox, closure = machine.shift(queue)
         result = closure.call
         machine.push(response_mailbox, result)