aris 1.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 939f838547c98d96452cf200c2b5ae4d9cbdfaf17f6811415f2f341e7cf96a32
+  data.tar.gz: c7c25cd371a1413068d0b490b7d92fa29809c077fde4c04f75a8619427de600f
+SHA512:
+  metadata.gz: 4f4b0181b8df3cf3f7b421cbfef4bf9082324e833f31c688d638c41808845b81842448243da9e91279d0781f690edb7b76fde2c6859d060df58c4e3bf906e9fb
+  data.tar.gz: 756840ba2f35be79777e3aeeb01be6a4ca560119d85d5e5ba11a725cc7f87ab8e2afa73a0fbd22c5ac97f4dcccfde31bf1c1ff621cddeea62c4864c3df15bdc9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Steven Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,342 @@
+<img width="1696" height="704" alt="aris" src="https://github.com/user-attachments/assets/3f0a67d1-c4c0-4357-b0e7-8d8ad62563ba" />
+
+# Aris
+
+**A fast, framework-agnostic router for Ruby.**
+
+Aris treats routes as plain data structures instead of code. This design choice makes routing predictable, testable, and roughly 3× faster than comparable frameworks. It works anywhere—Rack apps, CLI tools, background jobs, or custom servers.
+
+## Installation
+
+```ruby
+gem 'aris'
+```
+
+## Quick Start
+
+Routes are just hashes. Define them once at boot, and Aris compiles them into an optimized lookup structure.
+
+```ruby
+Aris.routes({
+  "api.example.com": {
+    "/users/:id": { 
+      get: { to: UserHandler, as: :user }
+    }
+  }
+})
+```
+
+Match incoming requests:
+
+```ruby
+result = Aris::Router.match(
+  domain: "api.example.com",
+  method: :get,
+  path: "/users/123"
+)
+
+result[:handler]  # => UserHandler
+result[:params]   # => { id: "123" }
+```
+
+Generate paths from named routes:
+
+```ruby
+Aris.path("api.example.com", :user, id: 123)
+# => "/users/123"
+```
+
+That's the core. Everything else builds on these three concepts: define, match, generate.
+
+---
+
+## Core Features
+
+### Multiple HTTP Methods
+
+```ruby
+Aris.routes({
+  "example.com": {
+    "/posts/:id": {
+      get: { to: PostShowHandler },
+      put: { to: PostUpdateHandler },
+      delete: { to: PostDeleteHandler }
+    }
+  }
+})
+```
+
+### Wildcards for Catch-All Routes
+
+```ruby
+Aris.routes({
+  "example.com": {
+    "/files/*path": { get: { to: FileHandler } }
+  }
+})
+
+result = Aris::Router.match(
+  domain: "example.com",
+  method: :get,
+  path: "/files/docs/2024/report.pdf"
+)
+result[:params]  # => { path: "docs/2024/report.pdf" }
+```
+
+### Parameter Constraints
+
+Validate parameters at the routing level to fail fast on invalid input.
+
+```ruby
+Aris.routes({
+  "example.com": {
+    "/users/:id": { 
+      get: { 
+        to: UserHandler,
+        constraints: { id: /\A\d{1,8}\z/ }
+      }
+    }
+  }
+})
+```
+
+### Multi-Domain Routing
+
+Define different routing trees per domain, with wildcard fallback support.
+
+```ruby
+Aris.routes({
+  "example.com": {
+    "/": { get: { to: HomeHandler } }
+  },
+  "admin.example.com": {
+    "/": { get: { to: AdminDashboardHandler } }
+  },
+  "*": {
+    "/health": { get: { to: HealthHandler } }
+  }
+})
+```
+
+### Composable Plugins
+
+Plugins execute between routing and handler dispatch. They're just callables that can inspect, modify, or halt the request.
+
+```ruby
+class Auth
+  def self.call(request, response)
+    unless authorized?(request)
+      response.status = 401
+      response.body = ['Unauthorized']
+      return response  # Halts processing
+    end
+    nil  # Continue to next plugin or handler
+  end
+end
+
+Aris.routes({
+  "api.example.com": {
+    use: [CorsHeaders, Auth],  # Applied to all routes
+    "/users": { get: { to: UsersHandler } }
+  }
+})
+```
+
+Plugins inherit down the routing tree and can be overridden at any level.
+
+---
+
+### File-Based Route Discovery
+
+Define routes by creating files instead of writing hash definitions. The directory structure maps directly to your routes.
+
+```ruby
+# Directory structure:
+# app/routes/
+#   example.com/
+#     users/
+#       get.rb          # GET /users
+#       _id/
+#         get.rb        # GET /users/:id
+#   _/
+#     health/
+#       get.rb          # GET /health on any domain
+
+# app/routes/example.com/users/_id/get.rb
+class Handler
+  def self.call(request, params)
+    { id: params[:id], name: "User #{params[:id]}" }
+  end
+end
+
+# Boot configuration
+Aris.discover_and_define('app/routes')
+```
+
+Convention: `domain/path/segments/_param/method.rb`. Use `_` for wildcard domains and parameter names. Each file defines a `Handler` class with a `.call` method.
+
+
+---
+
+## Use Cases
+
+### Rack Applications
+
+```ruby
+# config.ru
+Aris.routes({
+  "example.com": {
+    "/": { get: { to: HomeHandler } }
+  }
+})
+
+run Aris::Adapters::RackApp.new
+```
+
+### CLI Tools
+
+```ruby
+# Route commands to handlers
+result = Aris::Router.match(
+  domain: "cli.internal",
+  method: :get,
+  path: "/users/#{ARGV[0]}/report"
+)
+
+result[:handler].call(result[:params]) if result
+```
+
+### Background Jobs
+
+```ruby
+class WebhookRouter
+  def self.route(event_type, payload)
+    result = Aris::Router.match(
+      domain: "webhooks.internal",
+      method: :post,
+      path: "/events/#{event_type}"
+    )
+    
+    result[:handler].call(payload) if result
+  end
+end
+```
+
+### Custom Servers
+
+```ruby
+class ServerAdapter
+  def handle(native_request)
+    result = Aris::Router.match(
+      domain: native_request.host,
+      method: native_request.method,
+      path: native_request.path
+    )
+    
+    return [404, {}, ['Not Found']] unless result
+    
+    result[:handler].call(native_request, result[:params])
+  end
+end
+```
+
+---
+
+## Error Handling
+
+Define custom handlers for 404s and 500s once, and they'll be used everywhere.
+
+```ruby
+Aris.default(
+  not_found: ->(req, params) {
+    [404, {}, ['{"error": "Not found"}']]
+  },
+  error: ->(req, exception) {
+    ErrorTracker.log(exception)
+    [500, {}, ['{"error": "Internal error"}']]
+  }
+)
+```
+
+Trigger these handlers from your code:
+
+```ruby
+class UserHandler
+  def self.call(request, params)
+    user = User.find(params[:id])
+    return Aris.not_found(request) unless user
+    
+    user.to_json
+  end
+end
+```
+
+
+
+---
+
+## Performance
+
+Aris compiles routes into a Trie structure at boot time, enabling constant-time lookups regardless of route count. Benchmarks against Roda show 2.5-3.8× faster routing across all scenarios.
+
+```
+Root path:            3.1× faster  (570ns vs 1.75μs)
+Single parameter:     2.8× faster  (998ns vs 2.78μs)
+Two parameters:       3.0× faster  (1.31μs vs 3.89μs)
+```
+
+Route matching is O(k) where k is path depth, not route count. Adding 1,000 routes has zero impact on lookup speed—only compilation time increases (3ms for 1,000 routes).
+
+**Why is it fast?**
+
+Routes are data structures, not code. Matching a request is a tree traversal with no method dispatch, no block evaluation, and no runtime metaprogramming. The implementation caches aggressively and minimizes object allocation in the hot path.
+
+---
+
+## Documentation
+
+**[Full Usage Guide](docs/USAGE.md)** - Complete API reference with detailed examples  
+**[Adapters Guide](docs/ADAPTERS.md)** - Build on top of aris agnostic interface
+**[Architecture](docs/ARCHITECTURE.md)** - Learn all about the design decisions behind Aris
+**[Plugin Development](docs/PLUGIN_DEVELOPMENT.md)** - How to build custom middleware  
+**[Performance Details](docs/PERFORMANCE.md)** - Benchmarks, profiling, and optimization
+
+---
+
+## FAQ
+
+**Can I use this with Rails or Sinatra?**  
+Yes, but it's better suited for new projects or specific use cases like API-only apps, CLI routing, or background job dispatch. For existing apps, Aris works well alongside framework routing rather than replacing it.
+
+**How does this compare to Rack middleware?**  
+Aris's plugins run after route matching, so they have access to route parameters and metadata. Rack middleware runs before routing and only sees raw HTTP data. Use both together—Rack for HTTP concerns, Aris plugins for application logic.
+
+**What if I need to add routes at runtime?**  
+Calling `Aris.routes` performs a full recompilation (milliseconds for thousands of routes) and isn't thread-safe. Most apps define routes once at boot. For truly dynamic routing, use parameterized routes with dynamic handler logic instead.
+
+**Does it support regex patterns in routes?**  
+No, because that would break the Trie optimization. Use wildcard parameters (`*path`) for globbing and constraints for validation. This keeps routing fast while still enforcing requirements.
+
+**How do I handle API versioning?**  
+Use domain-based (`v1.api.example.com`) or path-based (`/api/v1/users`) versioning. Both work identically—domain-based gives cleaner separation, path-based keeps everything on one domain.
+
+---
+
+## Contributing
+
+Pull requests welcome. The codebase prioritizes simplicity and performance—every feature should justify its complexity and impact on routing speed.
+
+Run tests: `ruby test/run_all_tests.rb`  
+Run benchmarks: `ruby test/bench/vs_roda.rb`
+
+---
+
+## License
+
+MIT
+
+---
+
+## Acknowledgments
+
+Inspired by the pragmatic design of Roda, the performance focus of Aaron Patterson's work, and the elegance of Rack. Thanks to the Ruby community for constantly pushing what's possible.

data/lib/aris/adapters/base.rb

@@ -0,0 +1,25 @@
+# lib/aris/adapters/base.rb
+module Aris
+  module Adapters
+    class Base
+      def handle_sitemap(request)
+        return nil unless defined?(Aris::Utils::Sitemap) && request.path == '/sitemap.xml'
+        
+        xml = Aris::Utils::Sitemap.generate(
+          base_url: "#{request.scheme}://#{request.host}",
+          domain: request.host
+        )
+        [200, {'content-type' => 'application/xml'}, [xml]]
+      end
+      
+      def handle_redirect(request)
+        return nil unless defined?(Aris::Utils::Redirects)
+        
+        redirect = Aris::Utils::Redirects.find(request.path)
+        return nil unless redirect
+        
+        [redirect[:status], {'Location' => redirect[:to]}, []]
+      end
+    end
+  end
+end

data/lib/aris/adapters/joys_integration.rb

@@ -0,0 +1,94 @@
+require_relative 'base'
+
+class JoysPlugin
+  def initialize(app)
+    @app = app
+  end
+  def call(env)
+    request = Rack::Request.new(env)
+    Thread.current[:joys_request] = request
+    Thread.current[:joys_params] = {} 
+    
+    begin
+      @app.call(env)
+    ensure
+      # Comprehensive cleanup
+      Thread.current[:joys_request] = nil
+      Thread.current[:joys_params]  = nil
+      Thread.current[:joys_locals]  = nil
+    end
+  end
+end
+
+module Joys
+  module Adapters
+    class Aris < ::Aris::Adapters::Base
+      def integrate!
+        inject_helpers!
+        [::Aris::Adapters::Mock::Response, ::Aris::Adapters::Rack::Response].each do |klass|
+          klass.include(Renderer)
+        end
+      end
+
+      def inject_helpers!
+        Joys::Render::Helpers.module_eval do
+          def request; Thread.current[:joys_request]; end
+          def params;  Thread.current[:joys_params];  end
+          def _(content); raw(content); end
+          def path(route_name, **params)
+            ::Aris.path(route_name, **params)  # Call on ::Aris module, not the adapter
+          end
+          def make(name, *args, **kwargs, &block)
+            Joys.define :comp, name, *args, **kwargs, &block
+          end 
+          def load_css_file(*names)
+			      names.each do |name|
+			        file_path = File.join(Joys::Config.css_parts, "#{name}.css")
+			        if File.exist?(file_path)
+			          raw File.read(file_path)
+			        else
+			          raise "CSS file not found: #{file_path}"
+			        end
+			      end
+			      nil
+			    end
+        end
+      end
+
+
+module Renderer
+  def render(path, **locals)
+    Thread.current[:joys_params] = locals[:params] || {}
+    file = File.join(Joys::Config.pages, "#{path}.rb")
+    raise "Template not found: #{file}" unless File.exist?(file)
+    
+    renderer = Object.new
+    renderer.extend(Joys::Render::Helpers)
+    renderer.extend(Joys::Tags)
+    
+    # Set the page name for style compilation
+    page_name = "page_#{path.gsub('/', '_')}"
+    
+    # Initialize ALL Joys state on the renderer instance
+    renderer.instance_variable_set(:@bf, String.new(capacity: 16384))
+    renderer.instance_variable_set(:@slots, {})
+    renderer.instance_variable_set(:@styles, [])
+    renderer.instance_variable_set(:@style_base_css, [])
+    renderer.instance_variable_set(:@style_media_queries, {})
+    renderer.instance_variable_set(:@used_components, Set.new)
+    renderer.instance_variable_set(:@current_page, page_name)  # ADD THIS!
+    
+    # Inject locals as methods
+    locals.each { |k, v| renderer.define_singleton_method(k) { v } }
+    
+    # Evaluate the page file
+    renderer.instance_eval(File.read(file), file)
+    
+    # Set the HTML on the Aris response
+    self.html(renderer.instance_variable_get(:@bf))
+    self
+  end
+end
+    end
+  end
+end

data/lib/aris/adapters/mock/adapter.rb

@@ -0,0 +1,141 @@
+# lib/aris/adapters/mock/adapter.rb
+require_relative '../../core'
+require_relative '../../pipeline_runner'
+require_relative 'request'
+require_relative 'response'
+require 'json'
+
+module Aris
+  module Adapters
+    module Mock
+      class Adapter
+        def call(method:, path:, domain:, headers: {}, body: '', query: '')
+          # Parse cookies from headers before creating request
+          cookies = parse_cookies(headers)
+          
+          request = Request.new(
+            method: method,
+            path: path,
+            domain: domain,
+            headers: headers,
+            body: body,
+            query: query,
+            cookies: cookies  # Add cookies
+          )
+          
+          request_domain = request.host
+          Thread.current[:aris_current_domain] = request_domain
+          
+          begin
+            redirect_response, normalized_path = Aris.handle_trailing_slash(path)
+            if redirect_response
+              return { 
+                status: redirect_response[0], 
+                headers: redirect_response[1], 
+                body: redirect_response[2] 
+              }
+            end
+            domain_config = Aris::Router.domain_config(domain)
+            if domain_config && domain_config[:locales] && domain_config[:locales].any? && domain_config[:root_locale_redirect] != false
+              if path == '/' || path.empty?
+                default_locale = domain_config[:default_locale] || domain_config[:locales].first
+                return { status: 302, headers: {'Location' => "/#{default_locale}/"}, body: [] }
+              end
+            end
+            
+            if defined?(Aris::Utils::Sitemap) && path == '/sitemap.xml'
+              xml = Aris::Utils::Sitemap.generate(base_url: "https://#{domain}", domain: domain)
+              return { status: 200, headers: {'content-type' => 'application/xml'}, body: [xml] }
+            end
+            
+            # Check redirects
+            if defined?(Aris::Utils::Redirects)
+              redirect = Aris::Utils::Redirects.find(path)
+              if redirect
+                return { status: redirect[:status], headers: {'Location' => redirect[:to]}, body: [] }
+              end
+            end
+            
+            route = Aris::Router.match(
+              domain: request_domain,
+              method: request.request_method.downcase.to_sym,
+              path: request.path_info
+            )
+
+            unless route
+              return format_response(Aris.not_found(request))
+            end
+            
+            # Inject locale methods into request if locale is present
+            if route[:locale]
+              request.define_singleton_method(:locale) { route[:locale] }
+              if domain_config
+                request.define_singleton_method(:available_locales) { domain_config[:locales] }
+                request.define_singleton_method(:default_locale) { domain_config[:default_locale] }
+              end
+            end
+            
+            response = Response.new
+            request.instance_variable_set(:@response, response)
+            request.define_singleton_method(:response) { @response }
+            # Execute plugins and handler via PipelineRunner
+            result = PipelineRunner.call(request: request, route: route, response: response)
+            
+            # Format the result
+            format_response(result, response)
+
+          rescue Aris::Router::RouteNotFoundError
+            return format_response(Aris.not_found(request))
+          rescue Exception => e
+            return format_response(Aris.error(request, e))
+          ensure
+            Thread.current[:aris_current_domain] = nil
+          end
+        end
+
+        def subdomain
+          @subdomain || extract_subdomain_from_domain
+        end
+
+        private
+
+        def extract_subdomain_from_domain
+          return nil unless @env[:subdomain] || @env['SUBDOMAIN']
+          
+          @env[:subdomain] || @env['SUBDOMAIN']
+        end
+
+        def parse_cookies(headers)
+          return {} unless headers && headers['Cookie']
+          
+          cookies = {}
+          headers['Cookie'].split(';').each do |cookie|
+            name, value = cookie.strip.split('=', 2)
+            cookies[name] = value if name && value
+          end
+          cookies
+        end
+
+def format_response(result, response = nil)
+  case result
+  when Response
+    { status: result.status, headers: result.headers, body: result.body }
+  when Array
+    # Don't unwrap - keep body as-is
+    { status: result[0], headers: result[1], body: result[2] }
+  when Hash
+    headers = response ? response.headers.merge({'content-type' => 'application/json'}) : {'content-type' => 'application/json'}
+    { status: 200, headers: headers, body: [result.to_json] }
+  else
+    if result.respond_to?(:status) && result.respond_to?(:headers) && result.respond_to?(:body)
+      { status: result.status, headers: result.headers, body: result.body }
+    else
+      headers = response ? response.headers.merge({'content-type' => 'text/plain'}) : {'content-type' => 'text/plain'}
+      { status: 200, headers: headers, body: [result.to_s] }
+    end
+  end
+end
+      end
+    end
+  end
+end