syntropy 0.38.1 → 0.40.0

data/lib/syntropy/request/response.rb

@@ -11,6 +11,10 @@ module Syntropy
   module ResponseMethods
     WEBSOCKET_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
 
+    # Upgrades a request to  the WebSocket protocol.
+    #
+    # @param custom_headers [Hash, nil] additional response headers
+    # @return [void]
     def upgrade_to_websocket(custom_headers = nil)
       key = "#{headers['sec-websocket-key']}#{WEBSOCKET_GUID}"
       upgrade_headers = {
@@ -22,20 +26,42 @@ module Syntropy
       adapter.websocket_connection(self)
     end
 
+    # Responds with a redirect to the given URL. If a relative path is provided
+    # as the URL, the absolute URL path will be calculated relative to the
+    # current request's path.
+    #
+    # @param url [String] redirect URL
+    # @param status [Integer] HTTP status code
+    # @return [void]
     def redirect(url, status = HTTP::FOUND)
+      url = File.expand_path(File.join(path, url)) if url =~ /^\./
       respond(nil, ':status' => status, 'Location' => url)
     end
 
+    # Redirects to the same URL, except with HTTPS.
+    #
+    # @param status [Integer] HTTP status code
+    # @return [void]
     def redirect_to_https(status = HTTP::MOVED_PERMANENTLY)
       secure_uri = "https://#{host}#{uri}"
       redirect(secure_uri, status)
     end
 
+    # Redirect to the same path and query, on a different host.
+    #
+    # @param new_host [String] new host name
+    # @param status [Integer] HTTP status code
+    # @return [void]
     def redirect_to_host(new_host, status = HTTP::FOUND)
       secure_uri = "//#{new_host}#{uri}"
       redirect(secure_uri, status)
     end
 
+    # Serves a static file as a response, with cache headers.
+    #
+    # @param path [String] file path
+    # @param opts [Hash] options
+    # @return [void]
     def serve_file(path, opts = {})
       full_path = file_full_path(path, opts)
       stat = File.stat(full_path)
@@ -58,6 +84,12 @@ module Syntropy
       respond(nil, ':status' => HTTP::NOT_FOUND)
     end
 
+    # Validates a static file cache against the request cache headers. Returns
+    # true if cache headers are valid.
+    #
+    # @param etag [String] ETag
+    # @param last_modified [String] last-modified value
+    # @return [bool] are cache headers valid
     def validate_static_file_cache(etag, last_modified)
       if (none_match = headers['if-none-match'])
         return true if none_match == etag
@@ -69,6 +101,11 @@ module Syntropy
       false
     end
 
+    # Returns a fully qualified file path based on the given options.
+    #
+    # @param path [String] file path
+    # @param opts [Hash] options hash
+    # @return [String] qualified file path
     def file_full_path(path, opts)
       if (base_path = opts[:base_path])
         File.join(opts[:base_path], path)
@@ -77,10 +114,13 @@ module Syntropy
       end
     end
 
-    def serve_io(io, opts)
-      respond(io.read, opts[:headers] || {})
-    end
-
+    # Renders a static file response.
+    #
+    # @param path [String] file path
+    # @param etag [String] ETag
+    # @param last_modified [String] last-modified value
+    # @param opts [Hash] options
+    # @return [void]
     def respond_with_static_file(path, etag, last_modified, opts)
       cache_headers = (etag || last_modified) ? {
         'etag' => etag,
@@ -90,14 +130,29 @@ module Syntropy
       adapter.respond_with_static_file(self, path, opts, cache_headers)
     end
 
+    # Set additional response headers.
+    #
+    # @param headers [Hash] response headers
+    # @return [void]
     def set_response_headers(headers)
       adapter.set_response_headers(headers)
     end
 
-    def set_cookie(k, v)
-      adapter.set_cookie(k, v)
+    # Sets a response cookie.
+    #
+    # @param key [String] cookie name
+    # @param value [String] cookie value
+    # @return [void]
+    def set_cookie(key, value)
+      adapter.set_cookie(key, value)
     end
 
+    # Upgrades the connection to the given protocol, yielding the connection to
+    # the given block.
+    #
+    # @param protocol [String] upgraded protocol
+    # @param custom_headers [Hash, nil] additional response headers
+    # @return [void]
     def upgrade(protocol, custom_headers = nil, &block)
       upgrade_headers = {
         ':status' => HTTP::SWITCHING_PROTOCOLS,
@@ -168,6 +223,11 @@ module Syntropy
       end
     end
 
+    # Renders an HTML repsonse with HTML content type.
+    #
+    # @param html [String] HTML response body
+    # @param headers [Hash] additional response headers
+    # @return [void]
     def respond_html(html, **headers)
       respond(
         html,
@@ -176,6 +236,11 @@ module Syntropy
       )
     end
 
+    # Renders a JSON repsonse with JSON content type.
+    #
+    # @param obj [any] obj to render into JSON
+    # @param headers [Hash] additional response headers
+    # @return [void]
     def respond_json(obj, **headers)
       respond(
         JSON.dump(obj),
@@ -184,6 +249,11 @@ module Syntropy
       )
     end
 
+    # Renders a nicely-formatted JSON repsonse with JSON content type.
+    #
+    # @param obj [any] obj to render into JSON
+    # @param headers [Hash] additional response headers
+    # @return [void]
     def json_pretty_response(obj, **headers)
       respond(
         JSON.pretty_generate(obj),

data/lib/syntropy/request/validation.rb

@@ -18,6 +18,12 @@ module Syntropy
       raise Syntropy::Error.method_not_allowed
     end
 
+    # Validates the request's content-type against the given accepted content
+    # types. If the content type does not match the given accepted list, raises
+    # an error.
+    #
+    # @param accepted [Array<String>] array of accepted content types
+    # @return [String] accepted content type
     def validate_content_type(*accepted)
       ct = content_type
       return ct if accepted.include?(ct)

data/lib/syntropy/storage/connection_pool.rb

@@ -8,6 +8,12 @@ module Syntropy
     class ConnectionPool
       attr_reader :count
 
+      # Initializes the connection pool.
+      #
+      # @param machine [UringMachine] machine instance
+      # @param fn [String] database filename
+      # @param max_conn [Integer] maximum number of connections
+      # @return [void]
       def initialize(machine, fn, max_conn)
         @machine = machine
         @fn = fn
@@ -17,6 +23,11 @@ module Syntropy
         @key = :"connection_pool_#{object_id}"
       end
 
+      # Checks out a database connection, passing it to the given block. This
+      # method is reentrant - called from the same fiber, it will yield the same
+      # database connection.
+      #
+      # @return [Extralite::Database] database connection
       def with_db
         if (db = Thread.current[@key])
           @machine.snooze
@@ -33,14 +44,27 @@ module Syntropy
         end
       end
 
+      # Performs the given query by acquiring a database connection and running
+      # the query.
+      #
+      # @param sql [String] SQL query
+      # @return [Array<Hash>] result rows
       def query(sql, *, **, &)
         with_db { it.query(sql, *, **, &) }
       end
 
+      # Executes the given query by acquiring a database connection and running
+      # the query.
+      #
+      # @param sql [String] SQL query
+      # @return [Integer] number of changed rows
       def execute(sql, *, **)
         with_db { it.execute(sql, *, **) }
       end
 
+      # Closes the connection pool by removing all connections.
+      #
+      # @return [void]
       def close
         while @queue.count > 0
           db = @machine.shift(@queue)
@@ -51,16 +75,26 @@ module Syntropy
 
       private
 
+      # Checks out a connection from the pool.
+      #
+      # @return [Extralite::Database] database connection
       def checkout
         return make_db_instance if @queue.count == 0 && @count < @max_conn
 
         @machine.shift(@queue)
       end
 
+      # Checks in a connection to the pool.
+      #
+      # @param db [Extralite::Database] database connection
+      # @return [void]
       def checkin(db)
         @machine.push(@queue, db)
       end
 
+      # Creates a database connection.
+      #
+      # @return [Extralite::Database] database connection
       def make_db_instance
         Extralite::Database.new(@fn, wal: true).tap do
           @count += 1

data/lib/syntropy/test.rb

@@ -12,6 +12,14 @@ module Syntropy
     HTTP = Syntropy::HTTP
 
     class << self
+      def global_env=(env)
+        @@global_env = env
+      end
+
+      def global_env
+        @@global_env
+      end
+
       # Gets/sets app environment for tests
       attr_accessor :env
     end
@@ -22,15 +30,16 @@ module Syntropy
     #
     # @return [Hash] test app environment
     def env
-      self.class.env
+      klass = self.class
+      klass.env || klass.global_env
     end
 
     # Loads and returns a module with the given reference.
     #
     # @param ref [String] module reference
     # @return [any] module
-    def load_module(ref, raise_on_missing: true)
-      app.module_loader.load(ref, raise_on_missing:)
+    def load_module(ref, raise_on_missing_export: true)
+      app.module_loader.load(ref, raise_on_missing_export:)
     end
 
     # Makes an HTTP request to the test app.
@@ -122,7 +131,7 @@ module Syntropy
     #
     # @return [void]
     def setup
-      env = self.class.env
+      env = self.env
       raise 'Environment not set' if !env
 
       Syntropy.load_config(env)
@@ -136,7 +145,7 @@ module Syntropy
       )
       @test_harness = Syntropy::TestHarness.new(@app)
 
-      @db = load_module('/_lib/storage', raise_on_missing: false)
+      @db = load_module('/_lib/storage', raise_on_missing_export: false)
       @db&.migrate! if @db.respond_to?(:migrate!)
     end
 

data/lib/syntropy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Syntropy
-  VERSION = '0.38.1'
+  VERSION = '0.40.0'
 end

data/lib/syntropy.rb

@@ -72,15 +72,22 @@ module Syntropy
       end
     end
 
+    # Loads the app config module based on the environment's config root and
+    # mode: (test, dev, production). The module's exported value is assigned to
+    # env[:config].
+    #
+    # @param env [Hash] app environment
+    # @return [void]
     def load_config(env)
       return if !env[:config_root]
 
       loader_env = env.merge(
         app_root: env[:config_root],
-        logger: nil
+        logger: nil,
+        machine: UM.new(size: 8)
       )
       loader = ModuleLoader.new(loader_env)
-      if (config = loader.load(env[:mode], raise_on_missing: false))
+      if (config = loader.load(env[:mode], raise_on_missing_export: false))
         env[:config] = config
       end
     end

data/syntropy.gemspec

@@ -21,9 +21,9 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 3.4'
   s.executables = ['syntropy']
 
-  s.add_dependency 'extralite',     '~>2.14'
-  s.add_dependency 'papercraft',    '~>3.2.0'
-  s.add_dependency 'uringmachine',  '~>1.0.2'
+  s.add_dependency 'extralite',     '~>3.0.1'
+  s.add_dependency 'papercraft',    '~>3.2.2'
+  s.add_dependency 'uringmachine',  '~>1.0.4'
 
   s.add_dependency 'json'
   s.add_dependency 'base64'
@@ -31,6 +31,6 @@ Gem::Specification.new do |s|
   s.add_dependency 'irb'
   s.add_dependency 'minitest'
 
-  s.add_development_dependency 'rake',      '~>13.3.1'
+  s.add_development_dependency 'rake'
   s.add_development_dependency 'solargraph'
 end

data/test/fixtures/app/_layout/default.rb

@@ -3,6 +3,6 @@ export template { |**props|
     h1 'Foo'
   }
   content {
-    render_yield(**props)
+    render_children(**props)
   }
 }

data/test/fixtures/app/_layout/kuku.rb

@@ -0,0 +1,8 @@
+export template { |**props|
+  header {
+    h1 'Kuku'
+  }
+  content {
+    render_children(**props)
+  }
+}

data/test/fixtures/app/_lib/circular/a.rb

@@ -0,0 +1,2 @@
+export self
+B = import './b'

data/test/fixtures/app/_lib/circular/b.rb

@@ -0,0 +1,2 @@
+export self
+C = import './c'

data/test/fixtures/app/_lib/circular/c.rb

@@ -0,0 +1,2 @@
+export self
+A = import './a'

data/test/fixtures/app/mod/concurrent.rb

@@ -0,0 +1,9 @@
+export self
+
+@machine.sleep(rand(0.001..0.01))
+
+@env[:concurrent_counter][:count] += 1
+
+def id
+  object_id
+end

data/test/test_app.rb

@@ -100,7 +100,7 @@ class AppTest < Minitest::Test
     assert_equal 'About', req.response_body.chomp
 
     req = @test_harness.request(':method' => 'GET', ':path' => '/test/about/foo')
-    assert_equal '<!DOCTYPE html><html><head><title></title></head><body><p>Hello from Markdown</p></body></html>', req.response_body.gsub(/\n/, '')
+    assert_equal '<!DOCTYPE html><html><head></head><body><p>Hello from Markdown</p></body></html>', req.response_body.gsub(/\n/, '')
 
     req = @test_harness.request(':method' => 'HEAD', ':path' => '/test/about/foo')
     assert_nil req.response_body

data/test/test_caching.rb

@@ -75,7 +75,7 @@ class CachingTest < Minitest::Test
     @adapter.serve_request
     response = read_client_side
 
-    expected = "HTTP/1.1 200\r\nTransfer-Encoding: chunked\r\nCache-Control: max-age=3600\r\nEtag: #{etag}\r\nLast-Modified: #{last_modified}\r\nContent-Type: text/css\r\n\r\n#{size.to_s(16)}\r\n#{content}\r\n0\r\n\r\n"
+    expected = "HTTP/1.1 200\r\nTransfer-Encoding: chunked\r\nCache-Control: max-age=604800\r\nEtag: #{etag}\r\nLast-Modified: #{last_modified}\r\nContent-Type: text/css\r\n\r\n#{size.to_s(16)}\r\n#{content}\r\n0\r\n\r\n"
     assert_equal expected, response
   end
 
@@ -92,7 +92,7 @@ class CachingTest < Minitest::Test
     @adapter.serve_request
     response = read_client_side
 
-    expected = "HTTP/1.1 200\r\nTransfer-Encoding: chunked\r\nCache-Control: max-age=3600\r\nEtag: #{etag}\r\nLast-Modified: #{last_modified}\r\nContent-Type: text/css\r\n\r\n#{size.to_s(16)}\r\n#{content}\r\n0\r\n\r\n"
+    expected = "HTTP/1.1 200\r\nTransfer-Encoding: chunked\r\nCache-Control: max-age=604800\r\nEtag: #{etag}\r\nLast-Modified: #{last_modified}\r\nContent-Type: text/css\r\n\r\n#{size.to_s(16)}\r\n#{content}\r\n0\r\n\r\n"
     assert_equal expected, response
 
     # good etag
@@ -118,7 +118,7 @@ class CachingTest < Minitest::Test
     @adapter.serve_request
     response = read_client_side
 
-    expected = "HTTP/1.1 200\r\nTransfer-Encoding: chunked\r\nCache-Control: max-age=3600\r\nEtag: #{etag}\r\nLast-Modified: #{last_modified}\r\nContent-Type: text/css\r\n\r\n#{size.to_s(16)}\r\n#{content}\r\n0\r\n\r\n"
+    expected = "HTTP/1.1 200\r\nTransfer-Encoding: chunked\r\nCache-Control: max-age=604800\r\nEtag: #{etag}\r\nLast-Modified: #{last_modified}\r\nContent-Type: text/css\r\n\r\n#{size.to_s(16)}\r\n#{content}\r\n0\r\n\r\n"
     assert_equal expected, response
 
     # good etag