syntropy 0.39.0 → 0.41.0

data/lib/syntropy/app.rb

@@ -26,7 +26,7 @@ module Syntropy
       end
 
       BUILTIN_APPLET_app_root = File.expand_path(File.join(__dir__, 'applets/builtin'))
-  
+
       # Creates a builtin applet with the given environment hash. By default the
       # builtin applet is mounted at /.syntropy.
       #
@@ -102,6 +102,7 @@ module Syntropy
     # @param req [Syntropy::Request] HTTP request
     # @return [void]
     def call(req)
+      # before = GC.stat(:total_allocated_objects)
       path = req.path
       route = @router_proc.(path, req.route_params)
       if !route
@@ -126,6 +127,9 @@ module Syntropy
       end
       error_handler = get_error_handler(route)
       error_handler.(req, e)
+    # ensure
+    #   after = GC.stat(:total_allocated_objects)
+    #   @logger&.debug(message: "Allocated: #{after - before}")
     end
 
     # Returns the route entry for the given path. If compute_proc is true,
@@ -483,7 +487,7 @@ module Syntropy
     #
     # @return [void]
     def start
-      @module_loader.load('_setup', raise_on_missing: false)
+      @module_loader.load('_setup', raise_on_missing_export: false)
 
       @machine.spin do
         # we do startup stuff asynchronously, in order to first let Syntropy do

data/lib/syntropy/applets/builtin/auto_refresh/watch.js

@@ -7,6 +7,6 @@
     if (msg.data != '') window.location.reload();
   })
   eventSource.addEventListener('error', () => {
-    console.log(`Failed to connect to auto refresh watcher (${sseURL})`);
+    // console.log(`Failed to connect to auto refresh watcher (${sseURL})`);
   })
 })()

data/lib/syntropy/applets/builtin/auto_refresh/watch.sse.rb

@@ -9,11 +9,15 @@
 # residing by default at `/.syntropy/auto_refresh/watch.js`.
 
 # Returns a hash holding references to queues for ongoing `watch.sse` requests.
+#
+# @return [Hash] hash of watchers
 def watchers
   @watchers ||= {}
 end
 
 # Signals a file change by pushing to all watcher queues.
+#
+# @return [void]
 def signal!
   watchers.each_key { @machine.push(it, true) }
 end
@@ -21,6 +25,9 @@ end
 # Handles incoming requests to the `watch.sse` route. Adds a queue to the list
 # of watchers, and waits for the queue to be signalled. In the absence of file
 # change, a timeout occurs after one minute, and the request is terminated.
+#
+# @param req [Syntropy::Request] request
+# @return [void]
 def call(req)
   queue = UM::Queue.new
   watchers[queue] = true

data/lib/syntropy/dev_mode.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
-TAG_DEBUG_PROC = ->(level, fn, line, col) {
+# Injects debug information into Papercraft emitted HTML tags.
+#
+# @param level [Integer] nesting level
+# @param fn [String] source filename
+# @param line [Integer] source line
+# @param col [Integer] source column
+# @return [Hash] HTML data attributes
+Papercraft::Compiler.html_debug_attribute_injector = ->(level, fn, line, col) {
   {
     'data-syntropy-level' => level,
     'data-syntropy-fn'    => fn,
     'data-syntropy-loc'   => "zed://file/#{fn}:#{line}:#{col}"
   }
 }
-
-Papercraft::Compiler.html_debug_attribute_injector = TAG_DEBUG_PROC

data/lib/syntropy/http/client.rb

@@ -7,10 +7,16 @@ module Syntropy
   module HTTP
     # HTTP Client class.
     class Client
+      # Initializes an HTTP client.
       def initialize(machine)
         @machine = machine
       end
 
+      # Performs a GET request.
+      #
+      # @param url [String] URL
+      # @param headers [Hash] request headers
+      # @return [Array] array containing response headers and body
       def get(url, **headers, &)
         uri = URI.parse(url)
         headers = headers.merge(
@@ -22,7 +28,11 @@ module Syntropy
 
       private
 
-      # @param uri [URI]
+      # Performs an HTTP request, returning the response headers and body.
+      #
+      # @param uri [URI] request URI
+      # @param headers [Hash] request headers
+      # @return [Array] array containing response headers and body
       def req(uri, **headers)
         connection = make_connection(uri.scheme, uri.host, uri.port)
         response_headers = connection.req(**headers)
@@ -33,6 +43,12 @@ module Syntropy
         end
       end
 
+      # Creates an HTTP connection.
+      #
+      # @param _scheme [String] connection scheme
+      # @param host [String] host
+      # @param port [Integer] port
+      # @return [Syntropy::HTTP::ClientConnection]
       def make_connection(_scheme, host, port)
         ip = (host =~ /^\d+\.\d+\.\d+\.\d+$/) ? host : @machine.resolve(host)[0]
 

data/lib/syntropy/http/client_connection.rb

@@ -5,15 +5,27 @@ require 'syntropy/http/io_extensions'
 
 module Syntropy
   module HTTP
+    # ClientConnection represents an HTTP client connection.
     class ClientConnection
       attr_reader :fd, :response_headers, :logger
 
+      # Initializes a ClientConnection.
+      #
+      # @param machine [UringMachine] machine instance
+      # @param fd [Integer] file descriptor
+      # @param io_mode [Symbol] IO mode
+      # @return [void]
       def initialize(machine, fd, io_mode: :socket)
         @machine = machine
         @fd = fd
         @io = machine.io(fd, io_mode)
       end
 
+      # Performs a request with the given body and headers.
+      #
+      # @param body [String, nil] request body
+      # @param headers [Hash] request headers
+      # @return [Hash] response headers
       def req(body: nil, **headers)
         if body
           headers = headers.merge(
@@ -28,6 +40,10 @@ module Syntropy
         @io.http_read_response_headers
       end
 
+      # Returns the response body
+      #
+      # @param headers [Hash] response headers
+      # @return [String, nil] response body
       def get_response_body(headers)
         @io.http_read_body(headers)
       end

data/lib/syntropy/http/io_extensions.rb

@@ -4,6 +4,7 @@ require 'syntropy/errors'
 
 module Syntropy
   module HTTP
+    # HTTP protocol extensions for UringMachine::IO
     module ProtocolMethods
       RE_REQUEST_LINE = /^(get|head|options|trace|put|delete|post|patch|connect)\s+([^\s]+)\s+HTTP\/([019\.]{1,3})/i
       RE_RESPONSE_LINE = /^HTTP\/1\.1\s+(\d{3})(\s+.+)?$/i
@@ -14,7 +15,9 @@ module Syntropy
       MAX_HEADER_LINE_LEN = 1 << 13 # 8KB
       MAX_CHUNK_SIZE_LEN = 16
 
-      # @return [Hash] headers
+      # Reads HTTP request headers.
+      #
+      # @return [Hash] request headers
       def http_read_request_headers
         line = read_line(MAX_REQUEST_LINE_LEN)
         return nil if !line
@@ -43,6 +46,9 @@ module Syntropy
         headers
       end
 
+      # Reads HTTP response headers.
+      #
+      # @return [Hash] response headers
       def http_read_response_headers
         line = read_line(MAX_RESPONSE_LINE_LEN)
         return nil if !line
@@ -73,6 +79,10 @@ module Syntropy
         headers
       end
 
+      # Reads an HTTP request/response body.
+      #
+      # @param headers [Hash] request/response headers
+      # @return [String] body
       def http_read_body(headers)
         content_length = headers['content-length']
         if content_length
@@ -95,6 +105,10 @@ module Syntropy
         nil
       end
 
+      # Skips an HTTP reuqest/response body.
+      #
+      # @param headers [Hash] request/response headers
+      # @return [void]
       def http_skip_body(headers)
         content_length = headers['content-length']
         if content_length
@@ -109,10 +123,12 @@ module Syntropy
           while http_skip_cte_chunk
           end
         end
-
-        nil
       end
 
+      # Reads an HTTP body chunk. If no chunks remain to be read, returns nil.
+      #
+      # @param headers [Hash] request/response headers
+      # @return [String, nil] body chunk
       def http_read_body_chunk(headers)
         content_length = headers['content-length']
         if content_length
@@ -129,6 +145,10 @@ module Syntropy
         nil
       end
 
+      # Writes HTTP request headers.
+      #
+      # @param headers [Hash] request headers
+      # @return [void]
       def http_write_request_headers(headers)
         method = headers[':method'] || (raise BadRequestError)
         path = headers[':path'] || (raise BadRequestError)
@@ -149,6 +169,11 @@ module Syntropy
 
       private
 
+      # Read a chunk (in chunked transfer encoding) into the given buffer. If no
+      # buffer is given, returns the chunk, otherwise returns the buffer.
+      #
+      # @param buffer [String, nil] buffer
+      # @return [String] buffer or chunk
       def http_read_cte_chunk(buffer)
         chunk_size_str = read_line(MAX_CHUNK_SIZE_LEN)
         return nil if !chunk_size_str
@@ -165,6 +190,9 @@ module Syntropy
         buffer ? (buffer << chunk) : chunk
       end
 
+      # Skips a chunk (in chunked transfer encoding).
+      #
+      # @return [void]
       def http_skip_cte_chunk
         chunk_size_str = read_line(MAX_CHUNK_SIZE_LEN)
         return if !chunk_size_str
@@ -172,7 +200,7 @@ module Syntropy
         chunk_size = chunk_size_str.to_i(16)
         if chunk_size == 0
           read_line(0)
-          return nil
+          return
         end
 
         chunk = skip(chunk_size)

data/lib/syntropy/http/server.rb

@@ -4,41 +4,28 @@ require 'syntropy/http/server_connection'
 
 module Syntropy
   module HTTP
+    # HTTP::Server implements an HTTP server.
     class Server
       PENDING_REQUESTS_GRACE_PERIOD = 0.1
       PENDING_REQUESTS_TIMEOUT_PERIOD = 5
 
-      def self.syntropy_app(_machine, env)
-        if env[:app_location]
-          env[:logger]&.info(message: 'Loading web app', location: env[:app_location])
-          require env[:app_location]
-
-          env.merge!(Syntropy.config)
-        end
-        env[:app]
-      end
-
-      def self.static_app(env); end
-
+      # Initializes a server instance.
+      #
+      # @param machine [UringMachine] machine instance
+      # @param env [Hash] app environment
+      # @param app [Proc, Syntropy::App] app instance
+      # @return [void]
       def initialize(machine, env, &app)
         @machine = machine
         @env = env
-        @app = app || app_from_env
+        @app = app
         @server_fds = []
         @accept_fibers = []
       end
 
-      def app_from_env
-        case @env[:app_type]
-        when nil, :syntropy
-          Server.syntropy_app(@machine, @env)
-        when :static
-          Server.static_app(@env)
-        else
-          raise "Invalid app type #{@env[:app_type].inspect}"
-        end
-      end
-
+      # Runs the server.
+      #
+      # @return [void]
       def run
         setup
         @machine.await(@accept_fibers)
@@ -46,12 +33,18 @@ module Syntropy
         graceful_shutdown
       end
 
+      # Stops the server with graceful shutdown.
+      #
+      # @return [void]
       def stop!
         graceful_shutdown
       end
 
       private
 
+      # Sets up the server.
+      #
+      # @return [void]
       def setup
         bind_info = get_bind_entries
         bind_info.each do |(host, port)|
@@ -67,6 +60,9 @@ module Syntropy
         @connection_fibers = Set.new
       end
 
+      # Returns bind entries from the app environment.
+      #
+      # @return [Array<Array>] array containing host/port tuples
       def get_bind_entries
         bind = @env[:bind]
         case bind
@@ -80,11 +76,20 @@ module Syntropy
         end
       end
 
+      # Parses a bind string into a host/port tuple.
+      #
+      # @param bind_string [String] bind string
+      # @return [Array<String, Integer>] array containing host and port
       def bind_info(bind_string)
         parts = bind_string.split(':')
         [parts[0], parts[1].to_i]
       end
 
+      # Sets up a TCP socket listening on the given host and port.
+      #
+      # @param host [String] host
+      # @param port [Integer] port
+      # @return [Integer] socket fd
       def setup_server_socket(host, port)
         fd = @machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
         @machine.setsockopt(fd, UM::SOL_SOCKET, UM::SO_REUSEADDR, true)
@@ -94,6 +99,10 @@ module Syntropy
         fd
       end
 
+      # Setup server extensions. This is used for adding additional headers to
+      # the response, namely the Server the Date headers.
+      #
+      # @return [void]
       def setup_server_extensions
         extensions = @env[:server_extensions]
         return if !extensions
@@ -109,6 +118,10 @@ module Syntropy
         end
       end
 
+      # Updates server headers.
+      #
+      # @param server_name [String] server name
+      # @return [void]
       def update_server_headers(server_name)
         @env[:server_date] = Time.now
         if server_name
@@ -118,12 +131,20 @@ module Syntropy
         end
       end
 
+      # Accepts incoming connections, spinning up a fiber for connection.
+      #
+      # @param listen_fd [Integer] listening socket fd
+      # @return [void]
       def accept_incoming(listen_fd)
         @machine.accept_each(listen_fd) { start_connection(it) }
       rescue UM::Terminate
         @machine.shutdown(listen_fd, UM::SHUT_RD)
       end
 
+      # Starts handling a connection on a separate fiber.
+      #
+      # @param fd [Integer] socket fd
+      # @return [void]
       def start_connection(fd)
         conn = ServerConnection.new(@machine, fd, @env, &@app)
         f = @machine.spin(conn) do
@@ -134,17 +155,27 @@ module Syntropy
         @connection_fibers << f
       end
 
+      # Closes all listening socket fd's.
+      #
+      # @return [void]
       def close_all_server_fds
         @server_fds.each { @machine.close_async(it) }
       end
 
       STOP = UM::Terminate.new
 
+      # Stops all fibers listening for incoming connections.
+      #
+      # @return [void]
       def stop_accept_fibers
         @accept_fibers.each { @machine.schedule(it, STOP) if !it.done? }
         @machine.await(@accept_fibers)
       end
 
+      # Performs a graceful shutdown by stopping listening, then waiting for
+      # connection fibers to stop with a timeout of 5 seconds.
+      #
+      # @return [void]
       def graceful_shutdown
         @env[:logger]&.info(message: 'Shutting down gracefully...')
 

data/lib/syntropy/http/server_connection.rb

@@ -13,6 +13,14 @@ module Syntropy
     class ServerConnection
       attr_reader :fd, :response_headers, :logger
 
+      # Initializes a server connection.
+      #
+      # @param machine [UringMachine] machine instance
+      # @param fd [Integer] file descriptor
+      # @param env [Hash] app environment
+      # @param io_mode [Symbol] IO mode
+      # @param app [Proc, Syntropy::App] server app
+      # @return [void]
       def initialize(machine, fd, env, io_mode: :socket, &app)
         @machine = machine
         @fd = fd
@@ -26,6 +34,9 @@ module Syntropy
         @response_cookies = nil
       end
 
+      # Runs the connection.
+      #
+      # @return [void]
       def run
         loop do
           persist = serve_request
@@ -33,6 +44,10 @@ module Syntropy
         end
       rescue UM::Terminate
         # server is terminated, do nothing
+      rescue SystemCallError
+        @logger&.error(
+          message:  'IO Error, closing...'
+        )
       rescue StandardError => e
         @logger&.error(
           message:  'Uncaught error while running connection',
@@ -76,9 +91,10 @@ module Syntropy
       # @return [void]
       def handle_error(request, err)
         case err
+        when Errno::ECONNRESET
+          # ignore
         when SystemCallError
-          log_error(err, 'I/O error')
-          false
+          log_error(err, 'Syscall error')
         when ProtocolError
           log_error(err, err.message)
           respond(request, err.message, ':status' => err.http_status)
@@ -99,6 +115,10 @@ module Syntropy
         @logger&.error(message: "#{message}, closing connection", error: err)
       end
 
+      # Reads the request body.
+      #
+      # @param req [Syntropy::Request] request
+      # @return [String, nil] request body
       def get_body(req)
         headers = req.headers
         return nil if headers[':body-done-reading']
@@ -108,6 +128,10 @@ module Syntropy
         body
       end
 
+      # Reads a request body chunk.
+      #
+      # @param req [Syntropy::Request] request
+      # @return [String, nil] request body chunk
       def get_body_chunk(req)
         headers = req.headers
         return nil if headers[':body-done-reading']
@@ -117,6 +141,9 @@ module Syntropy
         chunk
       end
 
+      # Returns true if the request is done
+      #
+      # @return [bool] whether the request is complete
       def complete?(req)
         req.headers[':body-done-reading']
       end
@@ -135,6 +162,11 @@ module Syntropy
 
       DELETE_COOKIE = "; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; Max-Age=0; HttpOnly"
 
+      # Adds a Set-Cookie header to the response headers.
+      #
+      # @param key [String] cookie name
+      # @param value [String] cookie value
+      # @return [void]
       def set_cookie(key, value)
         (@response_cookies ||= {})[key] = value || DELETE_COOKIE
       end
@@ -210,6 +242,13 @@ module Syntropy
         @done = true
       end
 
+      # Responds by rendering a static file.
+      #
+      # @param req [Syntropy::Request] request
+      # @param path [String] file path
+      # @param env [Hash] app environment
+      # @param cache_headers [Hash] cache headers
+      # @return [void]
       def respond_with_static_file(req, path, env, cache_headers)
         fd = @machine.open(path, UM::O_RDONLY)
         env ||= {}
@@ -240,6 +279,9 @@ module Syntropy
         end
       end
 
+      # Closes the connection.
+      #
+      # @return [void]
       def close
         return if @closed
 
@@ -248,6 +290,9 @@ module Syntropy
         @machine.close_async(@fd)
       end
 
+      # Yields the uhnderlying connection IO and fd to the given block.
+      #
+      # @return [void]
       def with_stream
         yield @io, @fd
       end
@@ -260,6 +305,9 @@ module Syntropy
       MAX_HEADER_LINE_LEN = 1 << 10 # 1KB
       MAX_CHUNK_SIZE_LEN = 16
 
+      # Returns true if the connection should be persisted.
+      #
+      # @param headers [Hash] request headers
       def persist_connection?(headers)
         connection = headers['connection']&.downcase
         return connection != 'close'
@@ -285,14 +333,23 @@ module Syntropy
         lines
       end
 
+      # Formats a response status line.
+      #
+      # @param body [String] response body
+      # @param status [Integer] HTTP status code
+      # @return [String] rendered status line
       def format_status_line(body, status)
         if !body
           empty_status_line(status)
         else
-          with_body_status_line(status, body)
+          with_body_status_line(body, status)
         end
       end
 
+      # Returns the status line for an empty response.
+      #
+      # @param status [Integer] HTTP status code
+      # @return [String] rendered status line
       def empty_status_line(status)
         if status == 204
           +"HTTP/1.1 #{status}\r\n"
@@ -301,10 +358,21 @@ module Syntropy
         end
       end
 
-      def with_body_status_line(status, body)
+      # Returns a status line for responses with body.
+      #
+      # @param body [String] response body
+      # @param status [Integer] HTTP status code
+      # @return [String] rendered status line
+      def with_body_status_line(body, status)
         +"HTTP/1.1 #{status}\r\nTransfer-Encoding: chunked\r\n"
       end
 
+      # Renders headers into a lines array.
+      #
+      # @param lines [Array<String>] array of header lines
+      # @param key [String] header name
+      # @param value [String, Array<String>] header value(s)
+      # @return [void]
       def collect_header_lines(lines, key, value)
         if value.is_a?(Array)
           value.inject(lines) { |_, item| lines << "#{key}: #{item}\r\n" }
@@ -313,6 +381,9 @@ module Syntropy
         end
       end
 
+      # Adds Set-Cookie headers to the response headers.
+      #
+      # @return [void]
       def add_set_cookie_headers
         @response_headers ||= {}
         sc = (@response_headers['Set-Cookie'] ||= [])

data/lib/syntropy/logger.rb

@@ -17,6 +17,14 @@ module Syntropy
       @opts = opts
     end
 
+    # Logs an DEBUG entry.
+    #
+    # @param o [Hash] log entry
+    # @return [void]
+    def debug(o)
+      call(:DEBUG, o)
+    end
+
     # Logs an INFO entry.
     #
     # @param o [Hash] log entry