syntropy 0.3 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43d7686b3b9f5f09c819bebb9e46fdceb45c8c0a66441b1e12b130fa376defc5
-  data.tar.gz: f616e5dcdedc8a08fb23d5a52c1a92296cd348f8555fede1ac31ba0859c1be28
+  metadata.gz: 7f125135bc3ed83c1050467241f48caf366600fead1d75db79455038e42e311a
+  data.tar.gz: ee9bd2bbf906eea9c90481ecdf643126285f65f63fe66a3f2b4f3050893e7c28
 SHA512:
-  metadata.gz: 1f6d14df3cbbaa74d9ec897cb50fd35caed0f48b6410f2abb13fad79947b50bbf33c32aa6358ab6464ac5b90e861fffacb345805d487cd67f5bd77b36cd7295b
-  data.tar.gz: af07c19a78d94fe37403246b302f95f047aeb12c764e8914e43f5ed1e1b1245cc0678a01e964e895fdc7aef0e775194c6ee9744939113352db07eca166693cc1
+  metadata.gz: 0bdce31c490701521d73829c02e1193fcd0da399b1e6186066ad5d6ecfa067dc143941300bf670fa4b447d5d5c177e903fa273d9d6d5bbfa2319ec0c74fd2678
+  data.tar.gz: 7b5eddf105f8654f379bf1d7f52948b713ee342dbd97eb1896e28b618b442ccf33c716d27a7f67c21cfd2c65f610b5c9677cd5e4faa0e777b8f727552628865c

data/.rubocop.yml

@@ -7,8 +7,16 @@ AllCops:
     - "test/**/*.rb"
     - "examples/**/*.rb"
     - "Gemfile*"
-# Style/LambdaCall:
-#   Enabled: false
+Style/LambdaCall:
+  Enabled: false
+
+Style/BlockDelimiters:
+  Enabled: false
+
+Style/Semicolon:
+  Exclude:
+    - cmd/setup/template/site/site/articles/cage.rb
+
 # Style/ModuleFunction:
 #   Enabled: false
 # Style/RegexpLiteral:

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.5 2025-07-05
+
+- Refactor App class to use Router
+- Refactor routing functionality into separate Router class
+- Add support for _site.rb file
+
+## 0.4 2025-07-03
+
+- Improve errors API
+- Add HTTP method validation
+- Refactor Qeweney::Request extensions
+- Add side_run API for running tasks on a side thread
+- Add support for rendering markdown with layout
+
 ## 0.3 2025-06-25
 
 - Implement module reloading on file change

data/README.md

@@ -22,22 +22,42 @@
 | Syntropy: A tendency towards complexity, structure, order, organization of
 ever more advantageous and orderly patterns.
 
-Syntropy is a WIP web framework for building multi-page and single-page apps.
+Syntropy is a web framework for building multi-page and single-page apps.
 Syntropy uses file tree-based routing, and provides controllers for a number of
 common patterns, such as a SPA with client-side rendering, a standard
 server-rendered MPA, a REST API etc.
 
+Syntropy also provides tools for working with lists of items represented as
+files (ala Jekyll and other static site generators), allowing you to build
+read-only apps (such as a markdown blog) without using a database.
+
+For interactive apps, Syntropy provides basic tools for working with SQLite
+databases in a concurrent environment.
+
+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
+  concurrent Ruby apps.
+- [Qeweney](https://github.com/digital-fabric/qeweney) a uniform interface for
+  working with HTTP requests and responses.
+- [Papercraft](https://github.com/digital-fabric/papercraft) HTML templating
+  with plain Ruby.
+- [Extralite](https://github.com/digital-fabric/extralite) a fast and innovative
+  SQLite wrapper for Ruby.
+
 ## Routing
 
-Routing is performed automatically by following the tree structure of the
-Syntropy app. A simple example:
+Syntropy routes request by following the tree structure of the Syntropy app. A
+simple example:
 
 ```
 site/
 ├ _layout/
 | └ default.rb
 ├ _articles/
-| └ 2025-06-01-hello_world.md
+| └ 2025-01-01-hello_world.md
 ├ api/
 | └ v1.rb
 ├ assets/
@@ -50,9 +70,8 @@ site/
 └ robots.txt
 ```
 
-The routing follows the file hierarchy, and Syntropy knows how to serve static
-asset files (CSS, JS, images...) as well as render markdown files and run custom
-Ruby code.
+Syntropy knows how to serve static asset files (CSS, JS, images...) as well as
+render markdown files and run modules written in Ruby.
 
 ## What does a Syntropic Ruby module look like?
 
@@ -67,7 +86,7 @@ def articles
   Syntropy.stamped_file_entries('/_articles')
 end
 
-@@layout.apply(title: 'archive') {
+export @@layout.apply(title: 'archive') {
   div {
     ul {
       articles.each { |article|
@@ -98,8 +117,8 @@ class APIV1 < Syntropy::RPCAPI
   end
 end
 
-APIV1.new(Syntropy.env.open_db)
+export APIV1
 ```
 
-Basically, the return value of the module is a template or a resource that
-responds to the request.
+Basically, the exported value can be a template, a callable or a class that
+responds to the request.

data/TODO.md

@@ -0,0 +1,135 @@
+- Refactor routing code into a separate Router class.
+- The Router class is in charge of:
+  - caching routes
+  - loading modules
+  - unloading modules on file change
+  - calculating middleware for routes
+    - middleware is defined in `_hook.rb` modules
+      - interface: ->(req, next)
+    - a special case for handling errors is `_error.rb`
+      - interface: ->(req, err)
+  - dispatching routes
+    - error handling:
+      - on uncaught error, if an `_error.rb` file exists in the same directory
+        or up the file tree
+    - middleware:
+      - a closure is created from the composition of the different hooks
+        defined, from the route's directory and up the file
+    - error handlers and middleware closures are cached as part of the route's
+      entry
+    - on file change for any _hook.rb or _error.rb files, all route entries in
+      the corresponding subtree are invalidated
+
+
+- Middleware
+
+  ```Ruby
+  # site/_hook.rb
+  export ->(req, &app) do
+    app.call(req)
+  rescue Syntropy::Error => e
+    render_error_page(req, e.http_status)
+  end
+
+  # an alternative, at least for errors is a _error.rb file:
+  # site/_error.rb
+  # Just a normal callable:
+  #
+  export ->(req, err) do
+    render_error_page(req, err.http_status)
+  end
+
+  # a _site.rb file can be used to wrap a whole app
+  # site/_site.rb
+
+  # this means we route according to the host header, with each
+  export Syntropy.route_by_host
+
+  # we can also rewrite requests:
+  rewriter = Syntropy
+    .select { it.host =~ /^tolkora\.(org|com)$/ }
+    .terminate { it.redirect_permanent('https://tolkora.net') }
+
+  # This is actuall a pretty interesting DSL design:
+  # a chain of operations that compose functions. So, we can select a
+  export rewriter.wrap(default_app)
+
+  # composing
+  export rewriter.wrap(Syntropy.some_custom_app.wrap(app))
+
+  # or maybe
+  export rewriter << some_other_middleware << app
+  ```
+
+
+
+
+- CLI tool for setting up a site repo:
+
+  ```bash
+  # clone a newly created repo
+  ~/repo$ git clone https://github.com/foo/bar
+  ...
+  ~/repo$ syntropy setup bar
+
+  (syntropy banner)
+
+  Setting up Syntropy project in /home/sharon/repo/bar:
+
+  bar/
+    bin/
+      start
+      stop
+      restart
+      console
+      server
+    docker-compose.yml
+    Dockerfile
+    Gemfile
+    proxy/
+
+    README.md
+    site/
+      _layout/
+        default.rb
+      _lib/
+      about.md
+      articles/
+        long-form.md
+      assets/
+        js/
+        css/
+          style.css
+        img/
+          syntropy.png
+      index.rb
+  ```
+
+  - Some of the files might need templating, but we can maybe do without, or at
+  least make it as generic as possible.
+
+- `syntropy setup` steps:
+
+  1. Verify existence of target directory
+  2. Copy files from Syntropy template to target directory
+  3. Do chmod +x for bin/*
+  4. Do bundle install in the target directory
+  5. Show some information with regard to how to get started working with the
+     repo
+
+- `syntropy provision` steps:
+
+  1. Verify Ubuntu 22.x or higher
+  2. Install git, docker, docker-compose
+
+- `syntropy deploy` steps:
+
+  1. Verify no uncommitted changes.
+  2. SSH to remote machine.
+    2.1. If not exists, clone repo
+    2.2. Otherwise, verify remote machine repo is on same branch as local repo
+    2.3. Do a git pull (what about credentials?)
+    2.4. If gem bundle has changed, do a docker compose build
+    2.5. If docker compose services are running, restart
+    2.6. Otherwise, start services
+    2.7. Verify service is running correctly

data/bin/syntropy

@@ -57,9 +57,9 @@ if !File.directory?(opts[:location])
 end
 
 
-
-opts[:machine] = UM.new
+# We set Syntropy.machine so we can reference it from anywhere
+opts[:machine] = Syntropy.machine = UM.new
 opts[:logger] = opts[:logger] && TP2::Logger.new(opts[:machine], **opts)
 
-app = Syntropy::App.new(opts[:machine], opts[:location], '/', opts)
+app = Syntropy::App.load(opts)
 TP2.run(opts) { app.call(it) }

data/cmd/setup/template/site/.gitignore

@@ -0,0 +1,57 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+# .rubocop-https?--*
+log

data/cmd/setup/template/site/Dockerfile

@@ -0,0 +1,32 @@
+ARG RUBY_BASE_IMAGE=ruby:3.4.1-alpine
+ARG GEM_CACHE_IMAGE=${RUBY_BASE_IMAGE}
+
+# base image
+FROM ${RUBY_BASE_IMAGE} AS base
+RUN apk add --update sqlite-dev openssl-dev tzdata bash curl zip git
+RUN apk add --update build-base
+RUN gem install bundler:2.6.9
+
+# gem cache
+FROM ${GEM_CACHE_IMAGE} AS gem-cache
+RUN mkdir -p /usr/local/bundle
+
+FROM base AS gems
+COPY --from=gem-cache /usr/local/bundle /usr/local/bundle
+COPY Gemfile Gemfile.lock ./
+RUN bundle install --jobs=4 --retry=5
+
+# Final backend image
+FROM base AS deploy
+
+RUN adduser -D app
+RUN chown app:app /home/app
+WORKDIR /home/app
+USER app
+
+RUN mkdir -p /tmp
+COPY --from=gems --chown=app:app /usr/local/bundle /usr/local/bundle
+
+EXPOSE 1234
+
+CMD ["bundle", "exec", "tp2", "."]

data/cmd/setup/template/site/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'syntropy', '0.3'

data/cmd/setup/template/site/docker-compose.yml

@@ -0,0 +1,51 @@
+services:
+  backend:
+    build: .
+    privileged: true
+    restart: always
+    ports:
+      - 127.0.0.1:1234:1234
+    # expose:
+    #   - 1234
+    volumes:
+      - .:/home/app
+    deploy:
+      # replicas: 1
+      resources:
+        limits:
+          memory: 500M
+    # restart: unless-stopped
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "1M"
+        max-file: "10"
+
+    # healthcheck:
+    #   test: "curl 'http://localhost:1234/?q=ping'"
+    #   interval: "30s"
+    #   timeout: "3s"
+    #   start_period: "5s"
+    #   retries: 3
+
+  proxy:
+    depends_on:
+      - backend
+    build:
+      context: ./proxy
+      dockerfile: Dockerfile
+    restart: always
+    volumes:
+      - ./proxy/etc/Caddyfile:/etc/caddy/Caddyfile
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    # env_file:
+      # - ./conf/caddy.env
+      # - ./conf/caddy_sensitive.env
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "1M"
+        max-file: "10"

data/cmd/setup/template/site/proxy/Dockerfile

@@ -0,0 +1,5 @@
+FROM caddy:2.10.0-builder AS builder
+RUN xcaddy build
+
+FROM caddy:2.10.0
+COPY --from=builder /usr/bin/caddy /usr/bin/caddy

data/cmd/setup/template/site/proxy/etc/Caddyfile

@@ -0,0 +1,7 @@
+localhost {
+  reverse_proxy noteflakescom-backend-1:1234
+}
+
+my-awesome-domain.com {
+  reverse_proxy noteflakescom-backend-1:1234
+}

data/cmd/setup/template/site/proxy/etc/tls_auto

@@ -0,0 +1,2 @@
+tls {$TLS_AUTO_EMAIL}
+

data/cmd/setup/template/site/proxy/etc/tls_cloudflare

@@ -0,0 +1,4 @@
+tls {
+	dns cloudflare {env.CLOUDFLARE_API_TOKEN}
+}
+

data/cmd/setup/template/site/proxy/etc/tls_custom

@@ -0,0 +1 @@
+tls {$TLS_CUSTOM_CERT} {$TLS_CUSTOM_KEY}

data/cmd/setup/template/site/proxy/etc/tls_selfsigned

@@ -0,0 +1 @@
+tls internal

data/cmd/setup/template/site/site/_layout/default.rb

@@ -0,0 +1,11 @@
+export templ { |*a, **b|
+  html {
+    head {
+      title 'My awesome Syntropy website'
+      link rel: 'stylesheet', type: 'text/css', href: '/assets/css/style.css'
+    }
+    body {
+      emit_yield(*a, **b)
+    }
+  }
+}

data/cmd/setup/template/site/site/about.md

@@ -0,0 +1,6 @@
+---
+layout: default
+---
+# About my site
+
+Lorem ipsum my awesome site.

data/cmd/setup/template/site/site/articles/cage.rb

@@ -0,0 +1,29 @@
+layout = import('_layout/default')
+
+poem = [
+  "        in ten\xA0", 'M', 'inutes',
+  '                  ', 'C', 'ome back: you will',
+  'have taught me chi', 'N', 'ese',
+  '                (s', 'A', 'tie).',
+  '       shall I ret', 'U', 'rn the favor?',
+  '                  ', 'G', 'ive you',
+  '                ot', 'H', 'er lessons',
+  '                 (', 'T', 'ing!)?',
+  '                  ', 'O', 'r would you prefer',
+  '              sile', 'N', 'ce?',
+]
+
+export layout.apply {
+  article(class: 'mesostic') {
+    h2 'For William McN. who studied with Ezra Pound'
+
+    content {
+      span(_for: poem) { text it }
+    }
+
+    author {
+      span "-\xA0"
+      a 'John cage', href: 'https://en.wikipedia.org/wiki/John_Cage'
+    }
+  }
+}

data/cmd/setup/template/site/site/articles/index.rb

@@ -0,0 +1,3 @@
+export templ {
+  h1 'Articles'
+}

data/cmd/setup/template/site/site/assets/css/style.css

@@ -0,0 +1,40 @@
+body {
+  font-family: sans-serif;
+}
+
+article.mesostic {
+  width: 600px;
+  margin: 2em auto;
+  font-size: 1.4em;
+
+  * {
+    font-family: monospace;
+  }
+
+  h2 {
+    text-align: center;
+  }
+
+  content {
+    display: grid;
+    margin: 2em 0;
+    grid-template-columns: 1fr auto 1fr;
+
+    span {
+      display: inline-block;
+    }
+    span:nth-child(3n + 1) {
+      text-align: right;
+    }
+
+    span:nth-child(3n + 2) {
+      text-align: center;
+      font-weight: bold;
+    }
+  }
+
+  author {
+    display: block;
+    text-align: right;
+  }
+}

data/cmd/setup/template/site/site/index.rb

@@ -0,0 +1,15 @@
+layout = import('_layout/default')
+
+export layout.apply {
+  h1 'Hello from Syntropy'
+  p {
+    span "Here's an "
+    a 'about', href: 'about'
+    span ' page.'
+  }
+  p {
+    span "Here's an "
+    a 'article', href: 'articles/cage'
+    span ' page.'
+  }
+}

data/docker-compose.yml

@@ -0,0 +1,51 @@
+services:
+  backend:
+    build: .
+    privileged: true
+    restart: always
+    ports:
+      - 127.0.0.1:1234:1234
+    # expose:
+    #   - 1234
+    volumes:
+      - .:/home/app
+    deploy:
+      # replicas: 1
+      resources:
+        limits:
+          memory: 500M
+    # restart: unless-stopped
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "1M"
+        max-file: "10"
+
+    # healthcheck:
+    #   test: "curl 'http://localhost:1234/?q=ping'"
+    #   interval: "30s"
+    #   timeout: "3s"
+    #   start_period: "5s"
+    #   retries: 3
+
+  proxy:
+    depends_on:
+      - backend
+    build:
+      context: ./proxy
+      dockerfile: Dockerfile
+    restart: always
+    volumes:
+      - ./proxy/etc/Caddyfile:/etc/caddy/Caddyfile
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    # env_file:
+      # - ./conf/caddy.env
+      # - ./conf/caddy_sensitive.env
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "1M"
+        max-file: "10"