syntropy 0.33.0 → 0.34.0

data/lib/syntropy/module_loader.rb

@@ -28,7 +28,7 @@ module Syntropy
     # @return [void]
     def initialize(env)
       @env = env
-      @root_dir = env[:root_dir]
+      @app_root = env[:app_root]
       @modules = {} # maps ref to module entry
       @fn_map = {} # maps filename to ref
     end
@@ -55,8 +55,8 @@ module Syntropy
     # @param dir [String] relative module directory
     # @return [Array<String>] list of modules
     def list(dir)
-      fns = Dir[File.join(@root_dir, dir, '*.rb')]
-      fns.map { it.match(/^#{@root_dir}\/(.+)\.rb$/)[1] }.sort
+      fns = Dir[File.join(@app_root, dir, '*.rb')]
+      fns.map { it.match(/^#{@app_root}\/(.+)\.rb$/)[1] }.sort
     end
 
     # Invalidates a module by its filename, normally following a change to the
@@ -89,10 +89,13 @@ module Syntropy
       entry[:reverse_deps].each { invalidate_ref(it) }
     end
 
+    # Invalidates a collection module.
+    #
+    # @return [void]
     def invalidate_collection_modules
       refs = []
       @modules.each do |ref, entry|
-        refs << ref if entry[:module].is_collection_module?
+        refs << ref if entry[:module].collection_module?
       end
       refs.each { invalidate_ref(it) }
     end
@@ -118,7 +121,7 @@ module Syntropy
     # @return [Hash] module entry
     def load_module(ref, raise_on_missing: true)
       ref = "/#{ref}" if ref !~ /^\//
-      fn = File.expand_path(File.join(@root_dir, "#{ref}.rb"))
+      fn = File.expand_path(File.join(@app_root, "#{ref}.rb"))
       if !File.file?(fn)
         raise Syntropy::Error, "File not found #{fn}" if raise_on_missing
 
@@ -142,6 +145,10 @@ module Syntropy
       }
     end
 
+    # Cleans up a module reference specifier, turning /index into /
+    #
+    # @param ref [String] input ref
+    # @return [String] clean ref
     def clean_ref(ref)
       return '/' if ref =~ /^index(\+)?$/
 
@@ -222,7 +229,7 @@ module Syntropy
     # #collection_module!
     #
     # @return [bool]
-    def is_collection_module?
+    def collection_module?
       @collection_module_p
     end
 
@@ -258,6 +265,10 @@ module Syntropy
       self
     end
 
+    # Normalize an import reference, turning a relative path into an absolute one.
+    #
+    # @param ref [String] input ref
+    # @return [String] normalized ref
     def normalize_import_ref(ref)
       base = @ref == '' ? '/' : @ref
       if ref =~ /^\//
@@ -274,7 +285,7 @@ module Syntropy
     # @return [Papercraft::Template] template
     def template(proc = nil, &block)
       proc ||= block
-      raise "No template block/proc given" if !proc
+      raise 'No template block/proc given' if !proc
 
       Papercraft::Template.new(proc)
     end
@@ -286,10 +297,10 @@ module Syntropy
     # @return [Papercraft::Template] template
     def template_xml(proc = nil, &block)
       proc ||= block
-      raise "No template block/proc given" if !proc
+      raise 'No template block/proc given' if !proc
 
       Papercraft::Template.new(proc, mode: :xml)
-    rescue => e
+    rescue StandardError => e
       p e
       p e.backtrace
       raise

data/lib/syntropy/papercraft_extensions.rb

@@ -4,12 +4,12 @@ require 'papercraft'
 
 Papercraft.extension(
   'auto_refresh!': ->(loc = '/.syntropy') {
-    if $syntropy_dev_mode
+    if Syntropy.dev_mode
       script(src: File.join(loc, 'auto_refresh/watch.js'), type: 'module')
     end
   },
   'debug_template!': ->(loc = '/.syntropy') {
-    if $syntropy_dev_mode
+    if Syntropy.dev_mode
       script(src: File.join(loc, 'debug/debug.js'), type: 'module')
     end
   }

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'
 

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,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