syntropy 0.32.0 → 0.34.0

data/examples/mcp-oauth/test/test_oauth.rb

@@ -1,28 +1,12 @@
 # frozen_string_literal: true
 
-require_relative 'helper'
 require 'base64'
 require 'digest'
 
-class OAuthBaseTest < Minitest::Test
-  APP_ROOT = File.expand_path(File.join(__dir__, '../app'))
-  HTTP = Syntropy::HTTP
-
+class OAuthBaseTest < Syntropy::Test
   def setup
-    @machine = UM.new
-    @app = Syntropy::App.new(
-      root_dir: APP_ROOT,
-      mount_path: '/',
-      machine: @machine
-    )
-    @store = @app.module_loader.load('_lib/auth_store')
-    @test_harness = Syntropy::TestHarness.new(@app)
-  end
-
-  def teardown
-    @machine = nil
-    @app = nil
-    @test_harness = nil
+    super
+    @store = load_module('_lib/auth_store')
   end
 end
 
@@ -42,18 +26,15 @@ end
 
 class OAuthPhase1DiscoveryTest < OAuthBaseTest
   def test_mcp_no_bearer_token
-    req = @test_harness.request(
+    req = post_json(
+      '/mcp',
       {
-        ':method'       => 'POST',
-        ':path'         => '/mcp',
-        'content-type'  => 'application/json'
-      },
-      JSON.dump({
         method: 'initialize',
         jsonrpc: '2.0',
         params: {}
-      })
+      }
     )
+
     assert_equal HTTP::UNAUTHORIZED, req.response_status
 
     www_auth = req.response_headers['WWW-Authenticate']
@@ -62,18 +43,14 @@ class OAuthPhase1DiscoveryTest < OAuthBaseTest
   end
 
   def test_mcp_invalid_bearer_token
-    req = @test_harness.request(
+    req = post_json(
+      '/mcp',
       {
-        ':method'       => 'POST',
-        ':path'         => '/mcp',
-        'content-type'  => 'application/json',
-        'authorization' => 'Bearer foobar'
-      },
-      JSON.dump({
         method: 'initialize',
         jsonrpc: '2.0',
         params: {}
-      })
+      },
+      'authorization' => 'Bearer foobar'
     )
     assert_equal HTTP::UNAUTHORIZED, req.response_status
 
@@ -83,10 +60,7 @@ class OAuthPhase1DiscoveryTest < OAuthBaseTest
   end
 
   def test_oauth_protected_resource_metadatas
-    req = @test_harness.request(
-      ':method' => 'GET',
-      ':path'   => '/.well-known/oauth-protected-resource'
-    )
+    req = get('/.well-known/oauth-protected-resource')
     assert_equal HTTP::OK, req.response_status
     json = req.response_json
     assert_equal ["http://localhost:1234/"],  json['authorization_servers']
@@ -94,10 +68,7 @@ class OAuthPhase1DiscoveryTest < OAuthBaseTest
   end
 
   def test_oauth_authorization_server_metadata
-    req = @test_harness.request(
-      ':method' => 'GET',
-      ':path'   => '/.well-known/oauth-authorization-server'
-    )
+    req = get('/.well-known/oauth-authorization-server')
     assert_equal HTTP::OK, req.response_status
     json = req.response_json
     assert_equal "http://localhost:1234/",                json['issuer']
@@ -117,14 +88,10 @@ class OAuthPhase2ClientRegistrationTest < OAuthBaseTest
       "grant_types"   => ["authorization_code", "refresh_token"]
     }
 
-    req = @test_harness.request(
-      {
-        ':method'       => 'POST',
-        ':path'         => '/oauth/register',
-        'content-type'  => 'application/json',
-        'authorization' => 'Bearer foobar'
-      },
-      JSON.dump(client_info)
+    req = post_json(
+      '/oauth/register',
+      client_info,
+      'authorization' => 'Bearer foobar'
     )
 
     assert_equal HTTP::CREATED, req.response_status
@@ -148,14 +115,10 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
       "redirect_uris" => ["http://localhost:8400/callback"],
       "grant_types"   => ["authorization_code", "refresh_token"]
     }
-    req = @test_harness.request(
-      {
-        ':method'       => 'POST',
-        ':path'         => '/oauth/register',
-        'content-type'  => 'application/json',
-        'authorization' => 'Bearer foobar'
-      },
-      JSON.dump(client_info)
+    req = post_json(
+      '/oauth/register',
+      client_info,
+      'authorization' => 'Bearer foobar'
     )
     assert_equal HTTP::CREATED, req.response_status
     json = req.response_json
@@ -169,10 +132,7 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
       'code_challenge_method' => 'S256',
       'state'                 => 'my_state'
     }
-    req = @test_harness.request(
-      ':method' => 'GET',
-      ':path'   => "/oauth/authorize?#{URI.encode_www_form(params)}"
-    )
+    req = get("/oauth/authorize?#{URI.encode_www_form(params)}")
     assert_equal HTTP::FOUND, req.response_status
     assert_equal '/signin', req.response_headers['Location']
 
@@ -202,17 +162,10 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
     }
     oauth_signin_id = @store.store(auth_params)
 
-    req = @test_harness.request(
-      {
-        ':method'       => 'POST',
-        ':path'         => '/signin',
-        'cookie'        => "oauth_signin_id=#{oauth_signin_id}",
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        username: 'foobar',
-        password: 'foobar'
-      )
+    req = post_form(
+      '/signin',
+      { username: 'foobar', password: 'foobar' },
+      'cookie' => "oauth_signin_id=#{oauth_signin_id}",
     )
 
     auth_info = @store.fetch(oauth_signin_id)
@@ -227,27 +180,15 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
   end
 
   def test_signin_endpoint_get
-    req = @test_harness.request(
-      {
-        ':method' => 'GET',
-        ':path'   => '/signin',
-      }
-    )
+    req = get('/signin')
     assert_equal HTTP::OK, req.response_status
     assert_equal 'text/html', req.response_content_type
   end
 
   def test_signin_endpoint_post_bad_creds
-    req = @test_harness.request(
-      {
-        ':method' => 'POST',
-        ':path'   => '/signin',
-        'content-type' => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        username: 'foobar',
-        password: 'bad'
-      )
+    req = post_form(
+      '/signin',
+      { username: 'foobar', password: 'bad' }
     )
     assert_equal HTTP::UNAUTHORIZED, req.response_status
     assert_equal 'text/html', req.response_content_type
@@ -255,16 +196,9 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
   end
 
   def test_signin_endpoint_post_good_creds
-    req = @test_harness.request(
-      {
-        ':method' => 'POST',
-        ':path'   => '/signin',
-        'content-type' => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        username: 'foobar',
-        password: 'foobar'
-      )
+    req = post_form(
+      '/signin',
+      { username: 'foobar', password: 'foobar' }
     )
     assert_equal HTTP::SEE_OTHER, req.response_status
     assert_equal '/', req.response_headers['Location']
@@ -277,22 +211,14 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
   end
 
   def test_oauth_consent_endpoint_get_no_oauth_signin_id
-    req = @test_harness.request(
-      {
-        ':method' => 'GET',
-        ':path'   => '/oauth/consent',
-      }
-    )
+    req = get('/oauth/consent')
     assert_equal HTTP::BAD_REQUEST, req.response_status
   end
 
   def test_oauth_consent_endpoint_get_invalid_oauth_signin_id
-    req = @test_harness.request(
-      {
-        ':method' => 'GET',
-        ':path'   => '/oauth/consent',
-        'cookie'  => 'outh_signin_id=foo'
-      }
+    req = get(
+      '/oauth/consent',
+      'cookie' => 'outh_signin_id=foo'
     )
     assert_equal HTTP::BAD_REQUEST, req.response_status
   end
@@ -321,12 +247,9 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
     }
     oauth_signin_id = @store.store(auth_params)
 
-    req = @test_harness.request(
-      {
-        ':method' => 'GET',
-        ':path'   => '/oauth/consent',
-        'cookie'  => "oauth_signin_id=#{oauth_signin_id}"
-      }
+    req = get(
+      '/oauth/consent',
+      'cookie' => "oauth_signin_id=#{oauth_signin_id}"
     )
     assert_equal HTTP::OK, req.response_status
   end
@@ -355,16 +278,10 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
     }
     oauth_signin_id = @store.store(auth_params)
 
-    req = @test_harness.request(
-      {
-        ':method' => 'POST',
-        ':path'   => '/oauth/consent',
-        'cookie'  => "oauth_signin_id=#{oauth_signin_id}",
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        decision: 'deny',
-      )
+    req = post_form(
+      '/oauth/consent',
+      { decision: 'deny' },
+      'cookie'  => "oauth_signin_id=#{oauth_signin_id}"
     )
     assert_equal HTTP::FOUND, req.response_status
 
@@ -396,16 +313,10 @@ class OAuthPhase3AuthorizationTest < OAuthBaseTest
     }
     oauth_signin_id = @store.store(auth_params)
 
-    req = @test_harness.request(
-      {
-        ':method' => 'POST',
-        ':path'   => '/oauth/consent',
-        'cookie'  => "oauth_signin_id=#{oauth_signin_id}",
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        decision: 'allow',
-      )
+    req = post_form(
+      '/oauth/consent',
+      { decision: 'allow' },
+      'cookie'  => "oauth_signin_id=#{oauth_signin_id}"
     )
     assert_equal HTTP::FOUND, req.response_status
 
@@ -452,19 +363,15 @@ class OAuthPhase4AuthorizationTest < OAuthBaseTest
   end
 
   def test_oauth_token_exchange
-    req = @test_harness.request(
+    req = post_form(
+      '/oauth/token',
       {
-        ':method' => 'POST',
-        ':path'   => '/oauth/token',
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        grant_type: 'authorization_code',
-        code: @auth_code,
-        redirect_uri: 'http://localhost:4321/callback',
-        client_id: @client_id,
-        code_verifier: @code_verifier
-      )
+        grant_type:     'authorization_code',
+        code:           @auth_code,
+        redirect_uri:   'http://localhost:4321/callback',
+        client_id:      @client_id,
+        code_verifier:  @code_verifier
+      }
     )
 
     assert_equal HTTP::OK, req.response_status
@@ -483,19 +390,8 @@ class OAuthPhase4AuthorizationTest < OAuthBaseTest
   end
 
   def test_oauth_token_exchange_missing_params
-    req = @test_harness.request(
-      {
-        ':method' => 'POST',
-        ':path'   => '/oauth/token',
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form({}
-        # grant_type: 'authorization_code',
-        # code: auth_code,
-        # redirect_uri: 'http://localhost:4321/callback',
-        # client_id: client_id,
-        # code_verifier: code_verifier
-      )
+    req = post_form(
+      '/oauth/token', {}
     )
 
     assert_equal HTTP::BAD_REQUEST, req.response_status
@@ -507,19 +403,15 @@ class OAuthPhase4AuthorizationTest < OAuthBaseTest
   end
 
   def test_oauth_token_exchange_invalid_grant_type
-    req = @test_harness.request(
+    req = post_form(
+      '/oauth/token',
       {
-        ':method' => 'POST',
-        ':path'   => '/oauth/token',
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
         grant_type: 'foo',
         code: @auth_code,
         redirect_uri: 'http://localhost:4321/callback',
         client_id: @client_id,
         code_verifier: @code_verifier
-      )
+      }
     )
 
     assert_equal HTTP::BAD_REQUEST, req.response_status
@@ -531,19 +423,15 @@ class OAuthPhase4AuthorizationTest < OAuthBaseTest
   end
 
   def test_oauth_token_exchange_invalid_code
-    req = @test_harness.request(
+    req = post_form(
+      '/oauth/token',
       {
-        ':method' => 'POST',
-        ':path'   => '/oauth/token',
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        grant_type: 'authorization_code',
-        code: @auth_code + '!',
-        redirect_uri: 'http://localhost:4321/callback',
-        client_id: @client_id,
-        code_verifier: @code_verifier
-      )
+        grant_type:     'authorization_code',
+        code:           @auth_code + '!',
+        redirect_uri:   'http://localhost:4321/callback',
+        client_id:      @client_id,
+        code_verifier:  @code_verifier
+      }
     )
 
     assert_equal HTTP::BAD_REQUEST, req.response_status
@@ -555,19 +443,15 @@ class OAuthPhase4AuthorizationTest < OAuthBaseTest
   end
 
   def test_oauth_token_exchange_invalid_redirect_uri
-    req = @test_harness.request(
+    req = post_form(
+      '/oauth/token',
       {
-        ':method' => 'POST',
-        ':path'   => '/oauth/token',
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        grant_type: 'authorization_code',
-        code: @auth_code,
-        redirect_uri: 'http://localhost:4321/foo',
-        client_id: @client_id,
-        code_verifier: @code_verifier
-      )
+        grant_type:     'authorization_code',
+        code:           @auth_code,
+        redirect_uri:   'http://localhost:4321/foo',
+        client_id:      @client_id,
+        code_verifier:  @code_verifier
+      }
     )
 
     assert_equal HTTP::BAD_REQUEST, req.response_status
@@ -579,19 +463,15 @@ class OAuthPhase4AuthorizationTest < OAuthBaseTest
   end
 
   def test_oauth_token_exchange_invalid_client_id
-    req = @test_harness.request(
+    req = post_form(
+      '/oauth/token',
       {
-        ':method' => 'POST',
-        ':path'   => '/oauth/token',
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        grant_type: 'authorization_code',
-        code: @auth_code + '!',
-        redirect_uri: 'http://localhost:4321/callback',
-        client_id: @client_id + 'foo',
-        code_verifier: @code_verifier
-      )
+        grant_type:     'authorization_code',
+        code:           @auth_code + '!',
+        redirect_uri:   'http://localhost:4321/callback',
+        client_id:      @client_id + 'foo',
+        code_verifier:  @code_verifier
+      }
     )
 
     assert_equal HTTP::BAD_REQUEST, req.response_status
@@ -603,19 +483,15 @@ class OAuthPhase4AuthorizationTest < OAuthBaseTest
   end
 
   def test_oauth_token_exchange_invalid_code_verifier
-    req = @test_harness.request(
+    req = post_form(
+      '/oauth/token',
       {
-        ':method' => 'POST',
-        ':path'   => '/oauth/token',
-        'content-type'  => 'application/x-www-form-urlencoded'
-      },
-      URI.encode_www_form(
-        grant_type: 'authorization_code',
-        code: @auth_code + '!',
-        redirect_uri: 'http://localhost:4321/callback',
-        client_id: @client_id,
-        code_verifier: @code_verifier + 'abc'
-      )
+        grant_type:     'authorization_code',
+        code:           @auth_code + '!',
+        redirect_uri:   'http://localhost:4321/callback',
+        client_id:      @client_id,
+        code_verifier:  @code_verifier + 'abc'
+      }
     )
 
     assert_equal HTTP::BAD_REQUEST, req.response_status

data/lib/syntropy/app.rb

@@ -11,35 +11,52 @@ require 'syntropy/routing_tree'
 require 'syntropy/mime_types'
 
 module Syntropy
+  # The App implements a Syntropy application. It is responsible for handling
+  # incoming HTTP requests, routing them to the correct handler, and maintaining
+  # application state.
   class App
     class << self
+      # Creates an app instance based on the given environment hash.
+      #
+      # @param env [Hash] environment hash
+      # @return [Syntropy::App]
       def load(env)
         site_file_app(env) || default_app(env)
       end
 
       private
 
-      # for apps with a _site.rb file
+      # Creates a multi-hostname app if a _site.rb file is detected.
+      #
+      # @param env [Hash] environment hash
+      # @return [Syntropy::App]
       def site_file_app(env)
-        fn = File.join(env[:root_dir], '_site.rb')
+        fn = File.join(env[:app_root], '_site.rb')
         return nil if !File.file?(fn)
 
         loader = Syntropy::ModuleLoader.new(env)
         loader.load('_site')
       end
 
-      # default app
+      # Creates a normal Syntropy app.
+      #
+      # @param env [Hash] environment hash
+      # @return [Syntropy::App]
       def default_app(env)
         new(**env)
       end
     end
 
-    attr_reader :module_loader, :routing_tree, :root_dir, :mount_path, :env
+    attr_reader :module_loader, :routing_tree, :app_root, :mount_path, :env
     attr_accessor :raise_on_internal_server_error
 
+    # Initializes the app instance.
+    #
+    # @param env [Hash] environment hash
+    # @return [void]
     def initialize(**env)
       @machine = env[:machine]
-      @root_dir = File.expand_path(env[:root_dir])
+      @app_root = File.expand_path(env[:app_root])
       @mount_path = env[:mount_path]
       @env = env
       @logger = env[:logger]
@@ -77,12 +94,14 @@ module Syntropy
       proc = route[:proc] ||= compute_route_proc(route)
       proc.(req)
     rescue ScriptError, StandardError => e
-      @logger&.error(
-        message: "Error while serving request: #{e.message}",
-        method: req.method,
-        path: path,
-        error: e
-      ) if Error.log_error?(e)
+      if Error.log_error?(e)
+        @logger&.error(
+          message: "Error while serving request: #{e.message}",
+          method: req.method,
+          path: path,
+          error: e
+        )
+      end
       error_handler = get_error_handler(route)
       error_handler.(req, e)
     end
@@ -102,21 +121,6 @@ module Syntropy
       route
     end
 
-    def setup_db(db_path:, schema_root: '_schema')
-      @env[:db_path] = db_path
-      @env[:schema_root] = schema_root
-
-      class << self
-        def connection_pool
-          @connection_pool ||= DB::ConnectionPool.new(@machine, @env[:db_path], 4)
-        end
-
-        def schema
-          @schema ||= DB::Schema.new(module_loader: @module_loader, schema_root: @env[:schema_root])
-        end
-      end
-    end
-
     private
 
     # Handles a not found error, taking into account hooks up the tree from the
@@ -134,7 +138,10 @@ module Syntropy
       end
     end
 
-    # Returns the find
+    # Finds the first up-tree route entry for the given path.
+    #
+    # @param path [String] path
+    # @return [Hash] route entry
     def find_first_uptree_route(path)
       route = @router_proc.(path, {})
       if !route && path != '/'
@@ -149,7 +156,7 @@ module Syntropy
     # @return [void]
     def setup_routing_tree
       @routing_tree = Syntropy::RoutingTree.new(
-        root_dir: @root_dir, mount_path: @mount_path, **@env
+        app_root: @app_root, mount_path: @mount_path, **@env
       )
       mount_builtin_applet if @env[:builtin_applet_path]
       @router_proc = @routing_tree.router_proc
@@ -164,6 +171,10 @@ module Syntropy
       @routing_tree.mount_applet(path, @builtin_applet)
     end
 
+    # Sets and returns the not found proc for the given route entry.
+    #
+    # @param route [Hash] route entry
+    # @return [Proc] not found proc
     def route_not_found_proc(route)
       route[:not_found_proc] ||= compose_up_tree_hooks(route, ->(req) {
         raise Syntropy::Error.not_found('Not found')
@@ -233,7 +244,7 @@ module Syntropy
       req.validate_cache(**cache_opts) {
         req.respond(target[:content], 'Content-Type' => target[:mime_type])
       }
-    rescue => e
+    rescue StandardError => e
       p e
       p e.backtrace
       exit!
@@ -299,7 +310,7 @@ module Syntropy
     # @param route [Hash] route entry
     # @return [String] rendered HTML
     def render_markdown(route)
-      atts, md = Syntropy.parse_markdown_file(route[:target][:fn], @env)
+      atts, md = Syntropy::Markdown.parse(route[:target][:fn], @env)
 
       layout = compute_markdown_layout(route, atts)
       Papercraft.html(layout, md:, **atts)
@@ -337,7 +348,7 @@ module Syntropy
           }
           body {
             markdown md
-            auto_refresh! if @env[:dev_mode]
+            auto_refresh! if Syntropy.dev_mode
           }
         }
       }
@@ -482,6 +493,9 @@ module Syntropy
       req.respond(msg, ':status' => status) rescue nil
     }
 
+    # Returns the default error handler for the app.
+    #
+    # @return [Proc] error handler
     def default_error_handler
       @default_error_handler ||= begin
         if @builtin_applet
@@ -507,7 +521,7 @@ module Syntropy
         @machine.sleep 0.1
         route_count = @routing_tree.static_map.size + @routing_tree.dynamic_map.size
         @logger&.info(
-          message: "Serving from #{@root_dir} (#{route_count} routes found)"
+          message: "Serving from #{@app_root} (#{route_count} routes found)"
         )
 
         file_watcher_loop if @env[:watch_files]
@@ -519,18 +533,12 @@ module Syntropy
     #
     # @return [void]
     def file_watcher_loop
-      @machine.file_watch(@root_dir, UM::IN_CREATE | UM::IN_DELETE | UM::IN_CLOSE_WRITE) { |e|
+      @machine.file_watch(@app_root, UM::IN_CREATE | UM::IN_DELETE | UM::IN_CLOSE_WRITE) { |e|
         fn = e[:fn]
         @logger&.info(message: 'File change detected', fn: fn)
         @module_loader.invalidate_fn(fn)
         debounce_file_change
       }
-
-      # Syntropy.file_watch(@machine, @root_dir, period: period) do |event, fn|
-      #   @logger&.info(message: 'File change detected', fn: fn)
-      #   @module_loader.invalidate_fn(fn)
-      #   debounce_file_change
-      # end
     rescue Exception => e
       p e
       p e.backtrace
@@ -564,7 +572,7 @@ module Syntropy
 
       watcher_mod = watcher_route[:proc]
       watcher_mod.signal!
-    rescue => e
+    rescue StandardError => e
       @logger&.error(
         message: 'Unexpected error while signalling auto refresh watcher',
         error: e