syntropy 0.38.1 → 0.40.0

data/examples/blog/app/posts/[id]/index.rb

@@ -8,9 +8,7 @@ def get(req)
   post = @posts.get(id)
   raise Syntropy::Error.not_found if !post
 
-  req.respond_html(
-    @template.render(post:, req:)
-  )
+  req.respond_html(@template.render(post:, req:))
 end
 
 def post(req)
@@ -32,15 +30,15 @@ def delete(req)
   id = req.route_params['id'].to_i
 
   deleted = @posts.delete(id)
-  raise BadRequestError, "Failed to delete post" if deleted != 1
+  raise BadRequestError, 'Failed to delete post' if deleted != 1
 
   req.flash[:notice] = 'Post was successfully destroyed.'
-  req.redirect "/posts", Syntropy::HTTP::SEE_OTHER
+  req.redirect '..', Syntropy::HTTP::SEE_OTHER
 end
 
-@template = @layout.apply { |post:, **props|
-  h1 "My blog"
-  p props[:req]&.flash[:notice], style: 'color: green'
+@template = @layout.apply { |post:, req:, **props|
+  h1 'My blog'
+  p req.flash[:notice], style: 'color: green'
   div {
     h2 {
       a post[:title]
@@ -48,9 +46,9 @@ end
     p post[:body]
   }
   p {
-    a "Edit", href: "/posts/#{post[:id]}/edit"
+    a 'Edit', href: req.rel('./edit')
     span '|'
-    a "Back to posts", href: '/posts'
+    a 'Back to posts', href: req.rel('..')
   }
   div {
     form(method: 'post') {

data/examples/blog/app/posts/index.rb

@@ -5,9 +5,7 @@ export dispatch_by_http_method
 
 def get(req)
   posts = @posts.get_all
-  req.respond_html(
-    @template.render(posts:, req:)
-  )
+  req.respond_html(@template.render(posts:, req:))
 end
 
 def post(req)
@@ -17,16 +15,16 @@ def post(req)
   id = @posts.create(title, body)
 
   req.flash[:notice] = 'Post was successfully created.'
-  req.redirect("posts/#{id}")
+  req.redirect("./#{id}")
 end
 
-@template = @layout.apply { |**props|
+@template = @layout.apply { |req:, **props|
   h1 "My awesome blog"
-  p props[:req]&.flash[:notice], style: 'color: green'
+  p req.flash[:notice], style: 'color: green'
   props[:posts].each { |post|
     div {
       h2 {
-        a post[:title], href: "/posts/#{post[:id]}"
+        a post[:title], href: req.rel("./#{post[:id]}")
       }
       p post[:body]
     }
@@ -34,7 +32,7 @@ end
 
   div {
     p {
-      a "New post", href: '/posts/new'
+      a "New post", href: req.rel('./new')
     }
   }
 }

data/examples/blog/app/posts/new.rb

@@ -5,14 +5,14 @@ export dispatch_by_http_method
 
 def get(req)
   req.respond_html(
-    @template.render
+    @template.render(req:)
   )
 end
 
-@template = @layout.apply { |**props|
+@template = @layout.apply { |req:, **props|
   h1 "Create blog post"
   div {
-    form(action: "/posts", method: 'post') {
+    form(action: req.rel(".."), method: 'post') {
       div {
         label 'Title', for: 'title'
         input name: 'title', type: 'text'

data/examples/blog/config/production.rb

@@ -1,4 +1,5 @@
 export(
-  storage:
+  storage: {
     path: ENV['DATABASE_PATH'] || 'storage/production.db'
+  }
 )

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,
@@ -251,6 +255,8 @@ module Syntropy
       }
     end
 
+    DEFAULT_CACHE_CONTROL = 'max-age=604800' # one week
+
     # Serves a static file from the given target hash with cache validation.
     #
     # @param req [Syntropy::Request] request
@@ -259,7 +265,7 @@ module Syntropy
     def serve_static_file(req, target)
       validate_static_file_info(target)
       cache_opts = {
-        cache_control:  'max-age=3600',
+        cache_control:  DEFAULT_CACHE_CONTROL,
         last_modified:  target[:last_modified_date],
         etag:           target[:etag]
       }
@@ -317,63 +323,9 @@ module Syntropy
     # @param route [Hash] route entry
     # @return [Proc] route proc
     def markdown_route_proc(route)
-      headers = { 'Content-Type' => 'text/html' }
-
-      ->(req) {
-        req.respond_by_http_method(
-          'head'  => [nil, headers],
-          'get'   => -> { [render_markdown(route), headers] }
-        )
-      }
-    end
-
-    # Renders and returns the given markdown route as HTML.
-    #
-    # @param route [Hash] route entry
-    # @return [String] rendered HTML
-    def render_markdown(route)
-      atts, md = Syntropy::Markdown.parse(route[:target][:fn], @env)
-
-      layout = compute_markdown_layout(route, atts)
-      Papercraft.html(layout, md:, **atts)
-    end
-
-    def compute_markdown_layout(route, atts)
-      if (layout = atts[:layout])
-        route[:applied_layouts] ||= {}
-        route[:applied_layouts][layout] ||= markdown_layout_template(layout)
-      else
-        default_markdown_layout_template
-      end
-    end
-
-    # Returns a markdown template based on the given layout.
-    #
-    # @param layout [String] layout name
-    # @return [Proc] layout template
-    def markdown_layout_template(layout)
-      @layouts ||= {}
-      template = @module_loader.load("_layout/#{layout}")
-      @layouts[layout] = Papercraft.apply(template) { |md:, **| markdown(md) }
-    end
-
-    # Returns the default markdown layout, which renders to HTML and includes a
-    # title, the markdown content, and emits code for auto refreshing the page
-    # on file change.
-    #
-    # @return [Proc] default Markdown layout template
-    def default_markdown_layout_template
-      @default_markdown_layout ||= ->(md:, **atts) {
-        html5 {
-          head {
-            title atts[:title]
-          }
-          body {
-            markdown md
-            auto_refresh! if Syntropy.dev_mode
-          }
-        }
-      }
+      env = @env.merge(module_loader: @module_loader)
+      atts, md = Syntropy::Markdown.parse_file(route[:target][:fn], env)
+      Syntropy::Markdown.make_controller(env, atts, md)
     end
 
     # Returns the route proc for a module route.
@@ -535,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/controller_extensions.rb

@@ -53,7 +53,7 @@ module Syntropy
       raise 'Not a directory' if !File.directory?(full_path)
 
       Dir[File.join(full_path, '*.md')].sort.map {
-        atts, markdown = Syntropy::Markdown.parse(it, @env)
+        atts, markdown = Syntropy::Markdown.parse_file(it, @env)
         { atts:, markdown: }
       }
     end

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...')