syntropy 0.15.1 → 0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef2840797122cef8e0f7f7675c10665c35f60915e091043416ffd0ed70e1cb5c
-  data.tar.gz: 0d929bfbe0d629879b05c57b7c01c1e8c0ee1af148dc23570c30233f19e81156
+  metadata.gz: db440894351239f4fdc164cd3550d741919a8fed568f20620040cca54b7dbebd
+  data.tar.gz: 165d4a52b7d7ce7fb8377d7b0e96f108ef7c65cfc768cf59ec73b97a4f7c84e0
 SHA512:
-  metadata.gz: 6375f3fb5cbab65d6b710b613c32d0eb9ebb714880f0eb3921fd0b07da9219e0ab94faec2398ae2f33a21fa4f21a8135416faf5b6f2ad0721a99afa067b854f7
-  data.tar.gz: 715274f642dc3b0db72b0ec37526f26221b56930e19eb324f804408b18552a5c465d59f313cd8329a24a9caa0aa05abaa6907d523f15e1e7061e3e9e1bf1762c
+  metadata.gz: d2bb77e92b44ca5e66a46c4427a4705cb2316b42372a71ce3c1e250bf1f93bccbe9201fe9602c174a6315880f33d47338133c121871561ab31e98c5a095bb385
+  data.tar.gz: c1069d92fbdb6a4a9eb792fa26c16e3d3494c882eb8a8d09e211a0f16b7b880bab8e0004a74cf4d1969398c2185091282bc3a4eebbf37b325c31ae06d52d3cd0

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+# 0.17 2025-09-11
+
+- Move repo to [digital-fabric](https://github.com/digital-fabric/syntropy)
+
+# 0.16 2025-09-11
+
+- `syntropy` script:
+  - Remove trailing slash for root dir in syntropy script
+  - Rename `-w/--watch` option to `-d/--dev` for development mode
+  - Fix `--mount` option
+- Add builtin `/.syntropy` applet for builtin features:
+  - auto refresh for web pages
+  - JSON API
+  - Template debugging frontend tools
+  - ping route
+  - home page with links to examples
+- Implement applet mounting and loading
+- Remove Papercraft dependency
+- Add support for P2 XML templates, using `#template_xml`
+- Update P2, TP2
+
 # 0.15 2025-08-31
 
 - Implement invalidation of reverse dependencies on module file change

data/README.md

@@ -9,10 +9,10 @@
   <a href="http://rubygems.org/gems/syntropy">
     <img src="https://badge.fury.io/rb/syntropy.svg" alt="Ruby gem">
   </a>
-  <a href="https://github.com/noteflakes/syntropy/actions">
-    <img src="https://github.com/noteflakes/syntropy/actions/workflows/test.yml/badge.svg" alt="Tests">
+  <a href="https://github.com/digital-fabric/syntropy/actions">
+    <img src="https://github.com/digital-fabric/syntropy/actions/workflows/test.yml/badge.svg" alt="Tests">
   </a>
-  <a href="https://github.com/noteflakes/syntropy/blob/master/LICENSE">
+  <a href="https://github.com/digital-fabric/syntropy/blob/master/LICENSE">
     <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
   </a>
 </p>
@@ -38,7 +38,7 @@ Syntropy is based on:
 
 - [UringMachine](https://github.com/digital-fabric/uringmachine) - a lean mean
   [io_uring](https://unixism.net/loti/what_is_io_uring.html) machine for Ruby.
-- [TP2](https://github.com/noteflakes/tp2) - an io_uring-based web server for
+- [TP2](https://github.com/digital-fabric/tp2) - an io_uring-based web server for
   concurrent Ruby apps.
 - [Qeweney](https://github.com/digital-fabric/qeweney) a uniform interface for
   working with HTTP requests and responses.
@@ -46,6 +46,16 @@ Syntropy is based on:
 - [Extralite](https://github.com/digital-fabric/extralite) a fast and innovative
   SQLite wrapper for Ruby.
 
+## Examples
+
+To get a taste of some of Syntropy's capabilities, you can run the included
+examples site inside the Syntropy repository:
+
+```bash
+$ cd syntropy
+$ bundle exec syntropy -d examples
+```
+
 ## Routing
 
 Syntropy routes request by following the tree structure of the Syntropy app. A
@@ -93,6 +103,28 @@ Some conventions employed in Syntropy-based web apps:
 - The Syntrpy router accepts clean URLs for Ruby modules and Markdown files. It
   also accepts clean URLs for `index.html` files.
 
+## Running Syntropy
+
+Note: Syntropy runs exclusively on Linux and requires kernel version >= 6.4.
+
+To start a web server on the working directory, use the `syntropy` command:
+
+```bash
+$ # install syntropy:
+$ gem install syntropy
+$ # run syntropy
+$ syntropy path/to/my_site
+```
+
+To get help for the different options available, run `syntropy -h`.
+
+## Development mode
+
+When developing and making changes to your site, you can run Syntropy in
+development mode, which automatically reloads changed modules and provides tools
+to automatically refresh open web pages and debug HTML templates. To start
+Syntropy in development mode, run `syntropy -d path/to/my_site`.
+
 ## What does a Syntropic Ruby module look like?
 
 Consider `site/archive.rb` in the file tree above. We want to get a list of
@@ -121,7 +153,7 @@ But a module can also be something completely different:
 
 ```ruby
 # api/v1.rb
-class APIV1 < Syntropy::RPCAPI
+class APIV1 < Syntropy::JSONAPI
   def initialize(db)
     @db = db
   end

data/TODO.md

@@ -22,6 +22,8 @@
   article.layout #=>
   article.render_proc #=> (load layout, apply article)
   article.render #=> (render to HTML)
+
+  # there should also be methods for creating, updating and deleting of articles/items.
   ...
   ```
 
@@ -30,6 +32,149 @@
   - [ ] support for caching headers
   - [ ] add `Request#render_static_file(route, fn)
 
+- [ ] Serving of built-in assets (mostly JS)
+  - [ ] JS lib for RPC API
+
+## Missing for a first public release
+
+- [ ] Logo
+- [ ] Website
+- [ ] Frontend part of RPC API
+- [v] Auto-refresh page when file changes
+- [ ] Examples
+  - [ ] Reactive app - counter or some other simple app showing interaction with server
+  - [ ] ?
+
+## Counter example
+
+Here's a react component (from https://fresh.deno.dev/):
+
+```jsx
+// islands/Counter.tsx
+import { useSignal } from "@preact/signals";
+
+export default function Counter(props) {
+  const count = useSignal(props.start);
+
+  return (
+    <div>
+      <h3>Interactive island</h3>
+      <p>The server supplied the initial value of {props.start}.</p>
+      <div>
+        <button onClick={() => count.value -= 1}>-</button>
+        <div>{count}</div>
+        <button onClick={() => count.value += 1}>+</button>
+      </div>
+    </div>
+  );
+}
+```
+
+How do we do this with Syntropy? Can we make a component that does the
+templating and the reactivity in a single file? Can we wrap reactivity in a
+component that has its own state? And where does the state live?
+
+```ruby
+class Counter < Syntropy::Component
+  def initialize(start:, **props)
+    @count = reactive()
+  end
+
+  def template
+    div {
+      h3 'Interactive island'
+      p "The server supplied the initial value of #props[:start]}"
+      div {
+        button '-', on_click: -> { @count.value -= 1 }
+        div @count.value
+        button '+', on_click: -> { @count.value += 1 }
+      }
+    }
+  end
+end
+```
+
+Hmm, don't know if the complexity is worth it. It's an abstraction that's very
+costly - both in terms of complexity of computation, and in terms of having a
+clear mental model of what's happening under the hood.
+
+I think a more logical approach is to stay with well-defined boundaries between
+computation on the frontend and computation on the backend, and a having a clear
+understanding of where things happen:
+
+```ruby
+class Counter < Syntropy::Component
+  def incr
+    update(value: @props[:value] + 1)
+  end
+
+  def decr
+    update(value: @props[:value] - 1)
+  end
+
+  def template
+    div {
+      h3 'Interactive island'
+      div {
+        button '-', syn_click: 'decr'
+        div @props[:value]
+        button '+', syn_click: 'incr'
+      }
+    }
+  end
+end
+```
+
+Now, we can do all kinds of wrapping with scripts and ids and stuff to make this
+work, but still, it would be preferable for the interactivity to be expressed in
+JS. Maybe we just need a way to include a script that acts on the local HTML
+code. How can we do this without writing a web component etc?
+
+One way is to assign a random id to the template, then have a script that works
+on it locally.
+
+```ruby
+export template { |**props|
+  id = SecureRandom.hex(4)
+  div(id: id) {
+    h3 'Interactive island'
+    div {
+      button '-', syn_action: "decr"
+      div props[:value], syn_value: "value"
+      button '+', syn_action: "incr"
+    }
+    script <<~JS
+      const state = { value: #{props[:value]} }
+      const root = document.querySelector('##{id}')
+      const decr = root.querySelector('[syn-action="decr"]')
+      const incr = root.querySelector('[syn-action="incr"]')
+      const value = root.querySelector('[syn-value="value"]')
+      const updateValue = (v) => { state.value = v; value.innerText = String(v) }
+
+      decr.addEventListener('click', (e) => { updateValue(state.value - 1) })
+      incr.addEventListener('click', (e) => { updateValue(state.value + 1) })
+    JS
+  }
+}
+```
+
+How can we make this less verbose, less painful, less error-prone?
+
+One way is to say - we don't worry about this on the backend, we just write
+normal JS for the frontend and forget about the whole thing. Another way is to
+provide a set of tools for making this less painful:
+
+- Add some fancier abstractions on top of the JS RPC lib
+- Add some template extensions that inject JS into the generated HTML
+
+## Testing facilities
+
+- What do we need to test?
+  - Routes
+  - Route responses
+  - Changes to state / DB
+  -
+
 ## Support for applets
 
 - can be implemented as separate gems

data/bin/syntropy

@@ -7,7 +7,8 @@ require 'optparse'
 env = {
   mount_path: '/',
   banner: Syntropy::BANNER,
-  logger: true
+  logger: true,
+  builtin_applet_path: '/.syntropy'
 }
 
 parser = OptionParser.new do |o|
@@ -24,7 +25,8 @@ parser = OptionParser.new do |o|
     env[:logger] = nil
   end
 
-  o.on('-w', '--watch', 'Watch for changed files') do
+  o.on('-d', '--dev', 'Development mode') do
+    env[:dev_mode] = true
     env[:watch_files] = 0.1
   end
 
@@ -33,8 +35,14 @@ parser = OptionParser.new do |o|
     exit
   end
 
-  o.on('-m', '--mount', 'Set mount path (default: /)') do
-    env[:mount_path] = it
+  o.on('-m', '--mount PATH', 'Set mount path (default: /)') do |path|
+    p mount: path
+    env[:mount_path] = path
+    env[:builtin_applet_path] = File.join(path, '.syntropy')
+  end
+
+  o.on('--no-builtin-applet', 'Do not mount builtin applet') do
+    env[:builtin_applet_path] = nil
   end
 
   o.on('-v', '--version', 'Show version') do
@@ -54,7 +62,7 @@ rescue StandardError => e
   exit
 end
 
-env[:root_dir] = ARGV.shift || '.'
+env[:root_dir] = (ARGV.shift || '.').gsub(/\/$/, '')
 
 if !File.directory?(env[:root_dir])
   puts "#{File.expand_path(env[:root_dir])} Not a directory"
@@ -70,6 +78,7 @@ env[:machine] = Syntropy.machine = UM.new
 env[:logger] = env[:logger] && TP2::Logger.new(env[:machine], **env)
 
 require 'syntropy/version'
+require 'syntropy/dev_mode' if env[:dev_mode]
 
 env[:logger]&.info(message: "Running Syntropy version #{Syntropy::VERSION}")
 app = Syntropy::App.load(env)

data/examples/card.rb

@@ -0,0 +1,12 @@
+export template {
+  card {
+    h2 'Some card'
+    h3 'Some subtitle'
+
+    markdown <<~MARKDOWN
+      - Foo
+      - Bar
+      - Baz
+    MARKDOWN
+  }
+}

data/examples/counter.js

@@ -0,0 +1,20 @@
+import JSONAPI from '/.syntropy/json_api.js'
+
+(() => {
+  const api = new JSONAPI('/counter_api');
+
+  const value = document.querySelector('#value');
+  const decr  = document.querySelector('#decr');
+  const incr  = document.querySelector('#incr');
+
+  decr.addEventListener('click', async () => {
+    const result = await api.post('decr')
+    value.innerText = String(result);
+  });
+
+  incr.addEventListener('click', async () => {
+    const result = await api.post('incr')
+    value.innerText = String(result);
+  });
+
+})()

data/examples/counter.rb

@@ -0,0 +1,23 @@
+CounterAPI = import 'counter_api'
+
+export template {
+  html5 {
+    body {
+      p { a '< Home', href: '/' }
+
+      h1 'Counter'
+
+      div {
+        button '-', id: 'decr'
+        value CounterAPI.value, id: 'value'
+        button '+', id: 'incr'
+      }
+    }
+    script src: '/counter.js', type: 'module'
+    style <<~CSS
+      div { font-weight: bold; font-size: 1.3em }
+      value { display: inline-block; padding: 0 1em; color: blue; width: 1em }
+    CSS
+    auto_refresh_watch!
+  }
+}

data/examples/counter_api.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CounterAPI < Syntropy::JSONAPI
+  def initialize(env)
+    @env = env
+    @value = env[:counter_value] || 0
+  end
+
+  def value(req = nil)
+    @value
+  end
+
+  def incr!(req)
+    @value += 1
+  end
+
+  def decr!(req)
+    @value -= 1
+  end
+end
+
+export CounterAPI

data/examples/index.md

@@ -0,0 +1,8 @@
+---
+title: Syntropy Examples
+---
+
+# Syntropy Examples
+
+- [Template composition](/templates)
+- [JSON API](/counter)

data/examples/templates.rb

@@ -0,0 +1,40 @@
+Card = import 'card'
+
+export template {
+  html5 {
+    head {
+      style {
+        raw <<~CSS
+          div {
+            display: grid;
+            grid-template-columns: 1fr 1fr;
+          }
+          span.foo {
+            color: white;
+            background-color: blue;
+            padding: 1em;
+          }
+          span.bar {
+            color: white;
+            background-color: green;
+            padding: 1em;
+          }
+        CSS
+      }
+    }
+    body {
+      p { a '< Home', href: '/' }
+
+      h1 'Testing'
+
+      div {
+        span 'foo', class: 'foo'
+        span 'bar', class: 'bar'
+      }
+
+      Card()
+    }
+    auto_refresh_watch!
+    debug_template!
+  }
+}

data/lib/syntropy/app.rb

@@ -43,6 +43,7 @@ module Syntropy
       @root_dir = File.expand_path(env[:root_dir])
       @mount_path = env[:mount_path]
       @env = env
+      @logger = env[:logger]
 
       @module_loader = Syntropy::ModuleLoader.new(app: self, **env)
       setup_routing_tree
@@ -70,15 +71,22 @@ module Syntropy
       proc = route[:proc] ||= compute_route_proc(route)
       proc.(req)
     rescue StandardError => e
-      @env[:logger]&.error(
-        message: "Error while serving request",
+      @logger&.error(
+        message: "Error while serving request: #{e.message}",
         method: req.method,
-        path: req.path
+        path: req.path,
+        error: e
       )
       error_handler = get_error_handler(route)
       error_handler.(req, e)
     end
 
+    def route(path, params = {}, compute_proc: false)
+      route = @router_proc.(path, params)
+      route[:proc] ||= compute_route_proc(route) if compute_proc
+      route
+    end
+
     private
 
     # Instantiates a routing tree with the app settings, and generates a router
@@ -89,9 +97,16 @@ module Syntropy
       @routing_tree = Syntropy::RoutingTree.new(
         root_dir: @root_dir, mount_path: @mount_path, **@env
       )
+      mount_builtin_applet if @env[:builtin_applet_path]
       @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)
+      @routing_tree.mount_applet(path, @builtin_applet)
+    end
+
     # Computes the route proc for the given route, wrapping it in hooks found up
     # the routing tree.
     #
@@ -146,9 +161,9 @@ module Syntropy
       if (layout = atts[:layout])
         route[:applied_layouts] ||= {}
         proc = route[:applied_layouts][layout] ||= markdown_layout_proc(layout)
-        html = proc.render(md: md, **atts)
+        html = proc.render(md:, **atts)
       else
-        html = P2.markdown(md)
+        html = default_markdown_layout_proc.render(md:, **atts)
       end
       html
     end
@@ -160,9 +175,22 @@ module Syntropy
       @layouts[layout] = template.apply { |md:, **| markdown(md) }
     end
 
+    def default_markdown_layout_proc
+      @default_markdown_layout ||= ->(md:, **atts) {
+        html5 {
+          head {
+            title atts[:title]
+          }
+          body {
+            markdown md
+            auto_refresh_watch! if @env[:dev_mode]
+          }
+        }
+      }
+    end
+
     def module_route_proc(route)
       ref = @routing_tree.fn_to_rel_path(route[:target][:fn])
-      # ref = route[:target][:fn].sub(@mount_path, '')
       mod = @module_loader.load(ref)
       compute_module_proc(mod)
     end
@@ -171,31 +199,23 @@ module Syntropy
       case mod
       when P2::Template
         p2_template_proc(mod)
-      when Papercraft::Template
-        papercraft_template_proc(mod)
       else
         mod
       end
     end
 
     def p2_template_proc(template)
+      xml_mode = template.mode == :xml
       template = template.proc
-      headers = { 'Content-Type' => 'text/html' }
+      mime_type = xml_mode ? 'text/xml; charset=UTF-8' : 'text/html; charset=UTF-8'
+      headers = { 'Content-Type' => mime_type }
 
-      ->(req) {
-        req.respond_by_http_method(
-          'head'  => [nil, headers],
-          'get'   => -> { [template.render, headers] }
-        )
-      }
-    end
+      get_proc = xml_mode ? -> { [template.render_xml, headers] } : -> { [template.render, headers] }
 
-    def papercraft_template_proc(template)
-        headers = { 'Content-Type' => template.mime_type }
       ->(req) {
         req.respond_by_http_method(
           'head'  => [nil, headers],
-          'get'   => -> { [template.render, headers] }
+          'get'   => get_proc
         )
       }
     end
@@ -232,7 +252,7 @@ module Syntropy
     DEFAULT_ERROR_HANDLER = ->(req, err) {
       msg = err.message
       msg = nil if msg.empty? || (req.method == 'head')
-      req.respond(msg, ':status' => Syntropy::Error.http_status(err))
+      req.respond(msg, ':status' => Syntropy::Error.http_status(err)) rescue nil
     }
 
     # Returns an error handler for the given route. If route is nil, looks up
@@ -286,7 +306,7 @@ module Syntropy
         # setup tasks
         @machine.sleep 0.2
         route_count = @routing_tree.static_map.size + @routing_tree.dynamic_map.size
-        @env[:logger]&.info(
+        @logger&.info(
           message: "Serving from #{@root_dir} (#{route_count} routes found)"
         )
 
@@ -302,7 +322,7 @@ module Syntropy
       wf = @env[:watch_files]
       period = wf.is_a?(Numeric) ? wf : 0.1
       Syntropy.file_watch(@machine, @root_dir, period: period) do |event, fn|
-        @env[:logger]&.info(message: "File change detected", fn: fn)
+        @logger&.info(message: 'File change detected', fn: fn)
         @module_loader.invalidate_fn(fn)
         debounce_file_change
       end
@@ -324,7 +344,23 @@ module Syntropy
         @machine.sleep(0.1)
         setup_routing_tree
         @routing_tree_reloader = nil
+        signal_auto_refresh_watchers!
       end
     end
+
+    def signal_auto_refresh_watchers!
+      return if !@builtin_applet
+
+      watcher_route_path = File.join(@env[:builtin_applet_path], 'auto_refresh/watch.sse')
+      watcher_route = @builtin_applet.route(watcher_route_path, compute_proc: true)
+
+      watcher_mod = watcher_route[:proc]
+      watcher_mod.signal!
+    rescue => e
+      @logger&.error(
+        message: 'Unexpected error while signalling auto refresh watcher',
+        error: e
+      )
+    end
   end
 end

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

@@ -0,0 +1,12 @@
+(() => {
+  const jsURL = import.meta.url;
+  const sseURL = jsURL.replace(/\.js$/, '.sse');
+  const eventSource = new EventSource(sseURL);
+
+  eventSource.addEventListener('message', (msg) => {
+    if (msg.data != '') window.location.reload();
+  })
+  eventSource.addEventListener('error', () => {
+    console.log(`Failed to connect to auto refresh watcher (${sseURL})`);
+  })
+})()