syntropy 0.18.1 → 0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1748e9bb0cb68467f64598d1adfdef654790ab934285a0269cb622aeedf1783
-  data.tar.gz: de07940425a73e41073454a0fce3dd6d8309868fbe8cc3e8476061a99780093b
+  metadata.gz: 48230355504c92bce0f90adb332d50de6699cbefc63c93c7fd594e37f22fb5fe
+  data.tar.gz: 1849eede16f0764b199ee2e343cf95b28c7d45a2de62e217d5b12a916473251b
 SHA512:
-  metadata.gz: b9ed5c3adc822135af00b789a0d735efd34bc8977bd84cb85f43f5a37f07c55e8abf44648eebbd3c206b740ef5158dc24e72195925cb4034a448e1510aa4b7d7
-  data.tar.gz: ec1aa4e1101aa4ff7acc7186b3b0a07755a2baef5b5bfefd5934d743b5dfe5fd7c1589296cb40a5ba691dacefa43db32348f9697b52ceba2036a94fcd055908a
+  metadata.gz: 7e0e4d42d5d227fa11237f759cc3dae325dcff2ea2996746bb664e8e34ea94d831186c78c792422b20881f3a9d393e8f06279b029e42ac19c49e19ddc137b58a
+  data.tar.gz: bd1c8101ac5be676ce1f687be69147432b3200ab74b648b2a66f2a8742b61f28d74f143931cae5eb9b354d6b0b727e9257d6bffe03aa38aceea9170a7d975533

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.19 2025-09-14
+
+- Implement HTTP caching for static files
+- Add `--no-server-headers` option
+- Update TP2: server headers, injected response headers, cookies
+
 # 0.18 2025-09-11
 
 - Rename P2 back to Papercraft

data/README.md

@@ -17,6 +17,16 @@
   </a>
 </p>
 
+```
+   ooo
+  ooooo
+   ooo vvv       Syntropy - a web framework for Ruby
+    o vvvvv     -------------------------------------
+    |  vvv o      
+   :|:::|::|:
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+```
+
 ## What is Syntropy?
 
 | Syntropy: A tendency towards complexity, structure, order, organization of

data/bin/syntropy

@@ -8,7 +8,11 @@ env = {
   mount_path: '/',
   banner: Syntropy::BANNER,
   logger: true,
-  builtin_applet_path: '/.syntropy'
+  builtin_applet_path: '/.syntropy',
+  server_extensions: {
+    date: true,
+    name: 'Syntropy'
+  }
 }
 
 parser = OptionParser.new do |o|
@@ -45,6 +49,10 @@ parser = OptionParser.new do |o|
     env[:builtin_applet_path] = nil
   end
 
+  o.on('--no-server-headers', 'Don\'t include Server and Date headers') do
+    env[:server_extensions] = nil
+  end
+
   o.on('-v', '--version', 'Show version') do
     require 'syntropy/version'
     puts "Syntropy version #{Syntropy::VERSION}"

data/lib/syntropy/app.rb

@@ -81,8 +81,17 @@ module Syntropy
       error_handler.(req, e)
     end
 
+    # Returns the route entry for the given path. If compute_proc is true,
+    # computes the route proc if not yet computed.
+    #
+    # @param path [String] path
+    # @param params [Hash] hash receiving path parameters
+    # @param compute_proc [bool] whether to compute the route proc
+    # @return [Hash] route entry
     def route(path, params = {}, compute_proc: false)
       route = @router_proc.(path, params)
+      return if !route
+
       route[:proc] ||= compute_route_proc(route) if compute_proc
       route
     end
@@ -101,6 +110,7 @@ module Syntropy
       @router_proc = @routing_tree.router_proc
     end
 
+
     def mount_builtin_applet
       path = @env[:builtin_applet_path]
       @builtin_applet ||= Syntropy.builtin_applet(@env, mount_path: path)
@@ -117,6 +127,11 @@ module Syntropy
       compose_up_tree_hooks(route, pure)
     end
 
+    # Returns the pure route proc for the given route. A pure route proc is the
+    # computed proc for the route without any middleware hooks.
+    #
+    # @param route [Hash] route entry
+    # @return [Proc] route proc
     def pure_route_proc(route)
       case (kind = route[:target][:kind])
       when :static
@@ -131,19 +146,90 @@ module Syntropy
     end
 
     # Returns a proc rendering the given static route
+    #
+    # @param [Hash] route entry
+    # @return [Proc] route handler proc
     def static_route_proc(route)
       fn = route[:target][:fn]
       headers = { 'Content-Type' => Qeweney::MimeTypes[File.extname(fn)] }
 
       ->(req) {
-        req.respond_by_http_method(
-          'head'  => [nil, headers],
-          'get'   => -> { [IO.read(fn), headers] }
-        )
+        case req.method
+        when 'head'
+          req.respond(nil, headers)
+        when 'get'
+          serve_static_file(req, route[:target])
+        else
+          raise Syntropy::Error.method_not_allowed
+        end
       }
     end
 
-    # Returns a proc rendering the given markdown route
+    # Serves a static file from the given target hash with cache validation.
+    # 
+    # @param req [Qeweney::Request] request
+    # @param target [Hash] route target hash
+    # @return [void]
+    def serve_static_file(req, target)
+      validate_static_file_info(target)
+      cache_opts = {
+        cache_control:  'max-age=3600',
+        last_modified:  target[:last_modified_date],
+        etag:           target[:etag]
+      }
+      req.validate_cache(**cache_opts) {
+        req.respond(target[:content], 'Content-Type' => target[:mime_type])
+      }
+    rescue => e
+      p e
+      p e.backtrace
+      exit!
+    end
+
+    # Validates and conditionally updates the file information for the given
+    # target.
+    # 
+    # @param target [Hash] route target hash
+    # @return [void]
+    def validate_static_file_info(target)
+      now = Time.now
+      return if target[:last_update] && ((Time.now - target[:last_update]) < 390)
+
+      update_static_file_info(target, now)
+    end
+
+    STATX_MASK = UM::STATX_MTIME | UM::STATX_SIZE
+
+    # Updates the static file information for the given target
+    # 
+    # @param target [Hash] route target hash
+    # @param now [Time] current time
+    # @return [void]
+    def update_static_file_info(target, now)
+      target[:last_update] = now
+      fd = @machine.open(target[:fn], UM::O_RDONLY)
+      stat = @machine.statx(fd, nil, UM::AT_EMPTY_PATH, STATX_MASK)
+      target[:size] = size = stat[:size]
+      mtime = stat[:mtime].to_i
+      return if target[:last_modified] == mtime # file not modified
+
+      target[:last_modified] = mtime
+      target[:last_modified_date] = Time.at(mtime).httpdate
+      target[:content] = buffer = String.new(capacity: size)
+      target[:mime_type] = Qeweney::MimeTypes[File.extname(target[:fn])]
+      len = 0
+      while len < size
+        len += @machine.read(fd, buffer, size, len)
+      end
+      target[:etag] = Digest::SHA1.hexdigest(buffer)
+    ensure
+      @machine.close_async(fd) if fd
+    end
+
+    # Returns a proc rendering the given markdown route.
+    #
+    # @param route [Hash] route entry
+    # @return [Proc] route proc
     def markdown_route_proc(route)
       headers = { 'Content-Type' => 'text/html' }
 
@@ -155,27 +241,39 @@ module Syntropy
       }
     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.parse_markdown_file(route[:target][:fn], @env)
 
       if (layout = atts[:layout])
         route[:applied_layouts] ||= {}
-        proc = route[:applied_layouts][layout] ||= markdown_layout_proc(layout)
+        proc = route[:applied_layouts][layout] ||= markdown_layout_template(layout)
         html = proc.render(md:, **atts)
       else
-        html = default_markdown_layout_proc.render(md:, **atts)
+        html = default_markdown_layout_template.render(md:, **atts)
       end
       html
     end
 
-    # returns a markdown template based on the given layout
-    def markdown_layout_proc(layout)
+    # 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] = template.apply { |md:, **| markdown(md) }
     end
 
-    def default_markdown_layout_proc
+    # 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 {
@@ -189,12 +287,22 @@ module Syntropy
       }
     end
 
+    # Returns the route proc for a module route.
+    #
+    # @param route [Hash] route entry
+    # @return [Proc] route proc
     def module_route_proc(route)
       ref = @routing_tree.fn_to_rel_path(route[:target][:fn])
       mod = @module_loader.load(ref)
       compute_module_proc(mod)
     end
 
+    # Computes a route proc for the given module. If the module is a template,
+    # returns a route proc wrapping the template, otherwise the module itself is
+    # considered as the route proc.
+    #
+    # @param mod [any] module value
+    # @return [Proc] route proc
     def compute_module_proc(mod)
       case mod
       when Papercraft::Template
@@ -204,6 +312,10 @@ module Syntropy
       end
     end
 
+    # Returns a route proc for the given template.
+    #
+    # @param template [Papercraft::Template] template
+    # @return [Proc] route proc
     def papercraft_template_proc(template)
       xml_mode = template.mode == :xml
       template = template.proc
@@ -244,6 +356,11 @@ module Syntropy
       (parent = route[:parent]) ? compose_up_tree_hooks(parent, proc) : proc
     end
 
+    # Loads and returns an auxiliary module. This method is used for loading
+    # hook modules.
+    #
+    # @param hook_spec [Hash] hook spec
+    # @return [any] hook module
     def load_aux_module(hook_spec)
       ref = @routing_tree.fn_to_rel_path(hook_spec[:fn])
       @module_loader.load(ref)
@@ -348,6 +465,9 @@ module Syntropy
       end
     end
 
+    # Signals a file change to any auto refresh watchers.
+    #
+    # @return [void]
     def signal_auto_refresh_watchers!
       return if !@builtin_applet
 

data/lib/syntropy/applets/builtin/debug/debug.js

@@ -28,7 +28,7 @@
     const attachment = document.createElement('debug-attachment');
     const tag = ele.tagName;
     if (tag == 'SCRIPT' || tag == 'HEAD') return;
-  
+
     const level = ele.dataset.syntropyLevel;
     const href = ele.dataset.syntropyLoc;
     const fn = ele.dataset.syntropyFn;

data/lib/syntropy/request_extensions.rb

@@ -140,6 +140,36 @@ module Syntropy
       value
     end
 
+    # Validates request cache information. If the request cache information
+    # matches the given etag or last_modified values, responds with a 304 Not
+    # Modified status. Otherwise, yields to the given block for a normal
+    # response, and sets cache control headers according to the given arguments.
+    # 
+    # @param cache_control [String] value for Cache-Control header
+    # @param etag [String, nil] Etag header value
+    # @param last_modified [String, nil] Last-Modified header value
+    # @return [void]
+    def validate_cache(cache_control: 'public', etag: nil, last_modified: nil)
+      validated = false
+      if (client_etag = headers['if-none-match'])
+        validated = true if client_etag == etag
+      end
+      if (client_mtime = headers['if-modified-since'])
+        validated = true if client_mtime == last_modified
+      end
+      if validated
+        respond(nil, ':status' => Qeweney::Status::NOT_MODIFIED)
+      else
+        cache_headers = {
+          'Cache-Control' => cache_control
+        }
+        cache_headers['Etag'] = etag if etag
+        cache_headers['Last-Modified'] = last_modified if last_modified
+        set_response_headers(cache_headers)
+        yield
+      end
+    end
+
     # Reads the request body and returns form data.
     #
     # @return [Hash] form data

data/lib/syntropy/version.rb

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

data/syntropy.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |s|
   s.add_dependency 'json',          '2.13.2'
   s.add_dependency 'papercraft',    '2.13'
   s.add_dependency 'qeweney',       '0.22'
-  s.add_dependency 'tp2',           '0.16'
+  s.add_dependency 'tp2',           '0.18'
   s.add_dependency 'uringmachine',  '0.18'
 
   s.add_dependency 'listen',        '3.9.0'

data/test/bm_server.rb

@@ -12,5 +12,5 @@ def m(x=1)
   e = Time.now - t0
   p [x, e, e/x, x/e]
 end
-  
+
 m(10000) { t('http://localhost:1234/') }

data/test/test_app.rb

@@ -117,7 +117,6 @@ class AppTest < Minitest::Test
 
     req = make_request(':method' => 'GET', ':path' => '/test/rss')
     assert_equal '<link>foo</link>', req.response_body
-
   end
 
   def test_app_file_watching
@@ -208,3 +207,67 @@ class MultiSiteAppTest < Minitest::Test
     assert_equal '<h1>bar.baz</h1>', req.response_body.chomp
   end
 end
+
+class AppAPITest < Minitest::Test
+  Status = Qeweney::Status
+
+  APP_ROOT = File.join(__dir__, 'app')
+
+  def setup
+    @machine = UM.new
+
+    @tmp_path = '/test/tmp'
+    @tmp_fn = File.join(APP_ROOT, 'tmp.rb')
+
+    @app = Syntropy::App.new(
+      root_dir: APP_ROOT,
+      mount_path: '/test',
+      watch_files: 0.05,
+      machine: @machine
+    )
+  end
+
+  def test_route_method
+    route = @app.route('/')
+    assert_nil route
+
+    route = @app.route('/', compute_proc: true)
+    assert_nil route
+
+    route = @app.route('/test')
+    assert_nil route[:parent]
+    assert_equal '/test', route[:path]
+    assert_equal :static, route[:target][:kind]
+    assert_equal File.join(APP_ROOT, 'index.html'), route[:target][:fn]
+
+    route = @app.route('/test/assets/style.css')
+    assert_equal '/test/assets', route[:parent][:path]
+    assert_equal :static, route[:target][:kind]
+    assert_equal File.join(APP_ROOT, 'assets/style.css'), route[:target][:fn]
+
+    route = @app.route('/test/api')
+    assert_equal '/test', route[:parent][:path]
+    assert_equal :module, route[:target][:kind]
+    assert_equal File.join(APP_ROOT, 'api+.rb'), route[:target][:fn]
+
+    route = @app.route('/test/api/foo')
+    assert_equal '/test', route[:parent][:path]
+    assert_equal :module, route[:target][:kind]
+    assert_equal File.join(APP_ROOT, 'api+.rb'), route[:target][:fn]
+
+    route = @app.route('/test/bar')
+    assert_equal '/test', route[:parent][:path]
+    assert_equal :module, route[:target][:kind]
+    assert_equal File.join(APP_ROOT, 'bar.rb'), route[:target][:fn]
+
+    route = @app.route('/test/about/raise')
+    assert_equal '/test/about', route[:parent][:path]
+    assert_equal :module, route[:target][:kind]
+    assert_equal File.join(APP_ROOT, 'about/raise.rb'), route[:target][:fn]
+
+    route = @app.route('/test/about/foo')
+    assert_equal '/test/about', route[:parent][:path]
+    assert_equal :markdown, route[:target][:kind]
+    assert_equal File.join(APP_ROOT, 'about/foo.md'), route[:target][:fn]
+  end
+end

data/test/test_caching.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'helper'
+require 'digest/sha1'
+
+class CachingTest < Minitest::Test
+  Status = Qeweney::Status
+
+  APP_ROOT = File.join(__dir__, 'app')
+
+  def make_socket_pair
+    port = SecureRandom.random_number(10000..40000)
+    server_fd = @machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+    @machine.setsockopt(server_fd, UM::SOL_SOCKET, UM::SO_REUSEADDR, true)
+    @machine.bind(server_fd, '127.0.0.1', port)
+    @machine.listen(server_fd, UM::SOMAXCONN)
+
+    client_conn_fd = @machine.socket(UM::AF_INET, UM::SOCK_STREAM, 0, 0)
+    @machine.connect(client_conn_fd, '127.0.0.1', port)
+
+    server_conn_fd = @machine.accept(server_fd)
+
+    @machine.close(server_fd)
+    [client_conn_fd, server_conn_fd]
+  end
+
+  def setup
+    @machine = UM.new
+
+    @tmp_path = '/test/tmp'
+    @tmp_fn = File.join(APP_ROOT, 'tmp.rb')
+
+    @env = {
+      machine: @machine,
+      root_dir: APP_ROOT,
+      mount_path: '/test',
+      watch_files: 0.05
+    }
+
+    @app = Syntropy::App.new(**@env)
+
+    @c_fd, @s_fd = make_socket_pair
+    @adapter = TP2::Connection.new(nil, @machine, @s_fd, @env) { @app.(it) }
+  end
+
+  def teardown
+    @machine.close(@c_fd) rescue nil
+    @machine.close(@s_fd) rescue nil
+  end
+
+  def write_http_request(msg, shutdown_wr = false)
+    @machine.send(@c_fd, msg, msg.bytesize, UM::MSG_WAITALL)
+    @machine.shutdown(@c_fd, UM::SHUT_WR) if shutdown_wr
+  end
+
+  def write_client_side(msg)
+    @machine.send(@c_fd, msg, msg.bytesize, UM::MSG_WAITALL)
+  end
+
+  def read_client_side(len = 65536)
+    buf = +''
+    res = @machine.recv(@c_fd, buf, len, 0)
+    res == 0 ? nil : buf
+  end
+
+  def test_static_file_caching
+    fn = File.join(APP_ROOT, 'assets/style.css')
+    stat = @machine.statx(UM::AT_FDCWD, fn, 0, UM::STATX_ALL)
+    content = IO.read(fn)
+    etag = Digest::SHA1.hexdigest(content)
+    last_modified = Time.at(stat[:mtime]).httpdate
+    size = stat[:size]
+
+    write_http_request "GET /test/assets/style.css HTTP/1.1\r\n\r\n"
+    @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"
+    assert_equal expected, response
+  end
+
+  def test_static_file_caching_validate_etag
+    fn = File.join(APP_ROOT, 'assets/style.css')
+    stat = @machine.statx(UM::AT_FDCWD, fn, 0, UM::STATX_ALL)
+    content = IO.read(fn)
+    etag = Digest::SHA1.hexdigest(content)
+    last_modified = Time.at(stat[:mtime]).httpdate
+    size = stat[:size]
+
+    # bad etag
+    write_http_request "GET /test/assets/style.css HTTP/1.1\r\nIf-None-Match: foo\r\n\r\n"
+    @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"
+    assert_equal expected, response
+
+    # good etag
+    @adapter.response_headers.clear
+    write_http_request "GET /test/assets/style.css HTTP/1.1\r\nIf-None-Match: #{etag}\r\n\r\n"
+    @adapter.serve_request
+    response = read_client_side
+
+    expected = "HTTP/1.1 304\r\nContent-Length: 0\r\n\r\n"
+    assert_equal expected, response
+  end
+
+  def test_static_file_caching_validate_last_modified
+    fn = File.join(APP_ROOT, 'assets/style.css')
+    stat = @machine.statx(UM::AT_FDCWD, fn, 0, UM::STATX_ALL)
+    content = IO.read(fn)
+    etag = Digest::SHA1.hexdigest(content)
+    last_modified = Time.at(stat[:mtime]).httpdate
+    size = stat[:size]
+
+    # bad stamp
+    write_http_request "GET /test/assets/style.css HTTP/1.1\r\nIf-Modified-Since: foo\r\n\r\n"
+    @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"
+    assert_equal expected, response
+
+    # good etag
+    @adapter.response_headers.clear
+    write_http_request "GET /test/assets/style.css HTTP/1.1\r\nIf-Modified-Since: #{last_modified}\r\n\r\n"
+    @adapter.serve_request
+    response = read_client_side
+
+    expected = "HTTP/1.1 304\r\nContent-Length: 0\r\n\r\n"
+    assert_equal expected, response
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: syntropy
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: '0.19'
 platform: ruby
 authors:
 - Sharon Rosner
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.18'
 - !ruby/object:Gem::Dependency
   name: uringmachine
   requirement: !ruby/object:Gem::Requirement
@@ -248,6 +248,7 @@ files:
 - test/helper.rb
 - test/run.rb
 - test/test_app.rb
+- test/test_caching.rb
 - test/test_connection_pool.rb
 - test/test_errors.rb
 - test/test_file_watch.rb