stipa 0.1.0

data/lib/stipa/template.rb

@@ -0,0 +1,234 @@
+require 'erb'
+require 'json'
+
+module Stipa
+  # ERB template engine with layout support and Vue.js integration helpers.
+  #
+  # Usage:
+  #   engine = Stipa::Template.new(views_dir: 'views')
+  #   html   = engine.render('home', locals: { user: 'Alice' })
+  #
+  # With an explicit layout:
+  #   html = engine.render('home', layout: 'layouts/admin')
+  #
+  # Without a layout (useful for partials / API fragments):
+  #   html = engine.render('_row', locals: { item: obj }, layout: false)
+  #
+  # Directory conventions:
+  #   views/
+  #     layouts/
+  #       application.html.erb   ← default layout
+  #     home.html.erb
+  #     users/
+  #       show.html.erb
+  #     _sidebar.html.erb        ← partials start with _
+  class Template
+    attr_reader :views_dir
+
+    def initialize(views_dir:)
+      @views_dir = File.expand_path(views_dir)
+    end
+
+    # Render a template, optionally wrapped in a layout.
+    #
+    # template - name like 'home', 'users/show', or 'home.html.erb'
+    # locals   - Hash of variables made available inside the template
+    # layout   - :default  → auto-detect views/layouts/application.html.erb
+    #            a String  → explicit layout name (same resolution as template)
+    #            false     → no layout
+    def render(template, locals: {}, layout: :default)
+      ctx = ViewContext.new(self)
+      locals.each { |k, v| ctx._set_local(k, v) }
+
+      content = render_file(resolve(template), ctx)
+
+      layout_path = resolve_layout(layout)
+      if layout_path && File.exist?(layout_path)
+        ctx._set_content(content)
+        render_file(layout_path, ctx)
+      else
+        content
+      end
+    end
+
+    private
+
+    def render_file(path, ctx)
+      template = ERB.new(File.read(path), trim_mode: '-')
+      template.result(ctx._binding)
+    rescue Errno::ENOENT => e
+      raise "Template not found: #{path}"
+    end
+
+    def resolve(name)
+      # If it already ends with .erb, use it as-is; otherwise add .html.erb
+      name = "#{name}.html.erb" unless name.end_with?('.erb')
+      File.join(@views_dir, name)
+    end
+
+    def resolve_layout(layout)
+      return nil if layout == false
+      name = layout == :default ? 'layouts/application.html.erb' : "#{layout}.html.erb"
+      File.join(@views_dir, name)
+    end
+  end
+
+  # -------------------------------------------------------------------------
+  # View Context: the binding for ERB templates
+  # -------------------------------------------------------------------------
+
+  # The context object that becomes `self` inside every template.
+  # Includes helpers for rendering, HTML escaping, and Vue integration.
+  class ViewContext
+    def initialize(engine)
+      @engine = engine
+      @_blocks = {}
+    end
+
+    # -------------------------------------------------------------------------
+    # General helpers
+    # -------------------------------------------------------------------------
+
+    # Render a template (same engine, layout: false by default).
+    # Useful for partials; pass layout: :default if you want to wrap it.
+    def render_template(name, locals: {})
+      @engine.render(name, locals: locals, layout: false)
+    end
+
+    # HTML-escape a value. Use this in attributes or when interpolating
+    # untrusted user input inside text content.
+    #
+    #   <div class="<%= escape_html(user.css_class) %>">
+    #
+    # Or use the alias:
+    #
+    #   <div class="<%= h(user.css_class) %>">
+    def h(value)
+      ERB::Util.html_escape(value.to_s)
+    end
+    alias escape_html h
+
+    # -------------------------------------------------------------------------
+    # Vue.js helpers
+    # -------------------------------------------------------------------------
+
+    # Emit a Vue 3 component mount point.
+    #
+    # The Stīpa Vue bootstrapper (stipa-vue.js) picks up all elements with
+    # data-vue-component and mounts the corresponding registered component,
+    # passing data-props as the component's initial props.
+    #
+    # ERB:
+    #   <%= vue_component("Counter", props: { initial: 5 }) %>
+    #   <%= vue_component("SearchBox", props: { q: params[:q] }, class: "mt-4") %>
+    #
+    # Rendered HTML:
+    #   <div data-vue-component="Counter" data-props="{&quot;initial&quot;:5}"></div>
+    #
+    # Options:
+    #   props:  Hash passed as JSON to the component (default {})
+    #   tag:    HTML wrapper element (default 'div')
+    #   Any other keyword args become HTML attributes on the wrapper element.
+    def vue_component(name, props: {}, tag: 'div', **html_attrs)
+      attr_parts = html_attrs.map { |k, v| %(#{k}="#{h(v)}") }
+      attr_str   = attr_parts.empty? ? '' : " #{attr_parts.join(' ')}"
+      props_json = h(props.to_json)
+      %(<#{tag} data-vue-component="#{h(name)}" data-props="#{props_json}"#{attr_str}></#{tag}>)
+    end
+
+    # Include Vue 3 from a CDN (or a local path you serve).
+    #
+    #   <%= vue_script %>                          → unpkg, production build
+    #   <%= vue_script(version: '3.4.21') %>       → pin a specific version
+    #   <%= vue_script(dev: true) %>               → development build (warnings)
+    #   <%= vue_script(src: '/vendor/vue.js') %>   → self-hosted
+    def vue_script(src: nil, version: '3', dev: false)
+      unless src
+        build = dev ? 'vue.global.js' : 'vue.global.prod.js'
+        src   = "https://unpkg.com/vue@#{version}/dist/#{build}"
+      end
+      %(<script src="#{src}"></script>)
+    end
+
+    # Include the Stīpa Vue bootstrapper.
+    # This script auto-discovers vue_component mount points and mounts them.
+    # Must appear AFTER vue_script and AFTER any component registrations.
+    #
+    #   <%= stipa_vue_bootstrap %>
+    def stipa_vue_bootstrap(src: '/stipa-vue.js')
+      %(<script src="#{src}"></script>)
+    end
+
+    # Include one or more JavaScript files.
+    #   <%= javascript_tag '/app.js' %>
+    #   <%= javascript_tag '/a.js', '/b.js', type: 'module' %>
+    def javascript_tag(*srcs, type: nil, **attrs)
+      extra     = attrs.map { |k, v| %( #{k}="#{h(v)}") }.join
+      type_attr = type ? %( type="#{h(type)}") : ''
+      srcs.map { |src| %(<script src="#{h(src)}"#{type_attr}#{extra}></script>) }.join("\n")
+    end
+
+    # Include one or more stylesheets.
+    #   <%= stylesheet_tag '/app.css' %>
+    #   <%= stylesheet_tag '/reset.css', '/app.css' %>
+    def stylesheet_tag(*hrefs, **attrs)
+      extra = attrs.map { |k, v| %( #{k}="#{h(v)}") }.join
+      hrefs.map { |href| %(<link rel="stylesheet" href="#{h(href)}"#{extra}>) }.join("\n")
+    end
+
+    # -------------------------------------------------------------------------
+    # Private: template/layout machinery
+    # -------------------------------------------------------------------------
+
+    # Internal: inject a local variable as a method on this context.
+    def _set_local(name, value)
+      define_singleton_method(name) { value }
+    end
+
+    # Internal: store the inner-page HTML for the layout's `yield`.
+    def _set_content(html)
+      @_layout_content = html
+    end
+
+    # Internal: expose binding for ERB.
+    def _binding
+      binding
+    end
+
+    # Called inside a layout template to render the inner page content.
+    #
+    # Use one of these in your layout:
+    #   <body><%= content %></body>
+    #   <body><%= yield_content %></body>
+    #
+    # (Plain ERB `yield` is a Ruby keyword and cannot be used here.)
+    def content
+      @_layout_content
+    end
+    alias yield_content content
+
+    # Named content blocks — store content from a page, render in the layout.
+    #
+    # Page:   <% content_for :title do %>Home<% end %>
+    # Layout: <title><%= content_for(:title) %></title>
+    def content_for(section = nil, &block)
+      return @_blocks[section] if section && !block
+      @_blocks[section] = block.call if section && block
+    end
+
+    # Render a partial from within a template.
+    # Partials follow the Rails convention of a leading underscore on disk,
+    # but you refer to them without it.
+    #
+    #   <%= render 'sidebar' %>                         → views/_sidebar.html.erb
+    #   <%= render 'users/row', locals: { u: user } %> → views/users/_row.html.erb
+    def render(partial, locals: {})
+      name = if partial.include?('/')
+               partial.sub(%r{([^/]+)\z}, '_\1')
+             else
+               "_#{partial}"
+             end
+      @engine.render(name, locals: locals, layout: false)
+    end
+  end
+end

data/lib/stipa/thread_pool.rb

@@ -0,0 +1,98 @@
+require 'thread'
+
+module Stipa
+  # Bounded thread pool with a fixed-depth work queue.
+  #
+  # Design:
+  #   - SizedQueue (stdlib) handles all mutex/condvar complexity.
+  #   - Workers loop forever, pulling callables off the queue.
+  #   - Shutdown sends one :stop sentinel per worker (poison-pill pattern)
+  #     so every thread unblocks from its blocking `pop` and exits cleanly.
+  #   - submit returns true/false (never blocks the caller by default).
+  #
+  # Capacity math:
+  #   pool_size=32, queue_depth=64, avg handler=10ms
+  #   → steady-state concurrency at 1k req/s = 10 threads (31% utilization)
+  #   → 64-slot queue absorbs ~64ms burst before 503s begin
+  class ThreadPool
+    def initialize(size: 16, queue_depth: nil, on_error: nil)
+      @size        = size
+      @queue_depth = queue_depth || size * 4
+      @on_error    = on_error || method(:default_error_handler)
+      @queue       = SizedQueue.new(@queue_depth)
+      @workers     = []
+      @shutdown    = false
+      @mutex       = Mutex.new
+      @size.times { @workers << spawn_worker }
+    end
+
+    # Submit a job (callable block) to the pool.
+    #
+    # mode: :drop  — return false immediately if queue is full (default).
+    #       :block — spin up to push_timeout seconds before giving up.
+    #
+    # Returns true if the job was accepted, false if dropped.
+    def submit(mode: :drop, push_timeout: 0.5, &job)
+      raise ArgumentError, 'job block required' unless job
+      return false if @shutdown
+
+      case mode
+      when :drop
+        # Non-blocking push. SizedQueue raises ThreadError when full.
+        begin
+          @queue.push(job, true)   # true = non_block
+          true
+        rescue ThreadError
+          false
+        end
+      when :block
+        deadline = Time.now + push_timeout
+        loop do
+          begin
+            @queue.push(job, true)
+            return true
+          rescue ThreadError
+            return false if Time.now >= deadline
+            sleep 0.001   # 1ms spin — releases GVL while waiting
+          end
+        end
+      else
+        raise ArgumentError, "unknown mode: #{mode.inspect}"
+      end
+    end
+
+    # Graceful shutdown: stop accepting new jobs, drain the queue,
+    # then send a stop sentinel to every worker.
+    def shutdown(drain_timeout: 30.0)
+      @mutex.synchronize { @shutdown = true }
+      deadline = Time.now + drain_timeout
+      sleep 0.05 until @queue.empty? || Time.now >= deadline
+      # Poison-pill: one :stop per worker so each thread unblocks from pop
+      @size.times { @queue.push(:stop) }
+      @workers.each { |t| t.join(5) }   # 5s hard join timeout per thread
+    end
+
+    def queue_depth; @queue.length; end
+
+    private
+
+    def spawn_worker
+      Thread.new do
+        loop do
+          job = @queue.pop   # blocks until work is available or :stop arrives
+          break if job == :stop
+          begin
+            job.call
+          rescue => e
+            @on_error.call(e, job)
+          end
+        end
+      end
+    end
+
+    def default_error_handler(err, _job)
+      warn "[Stipa::ThreadPool] worker error: #{err.class}: #{err.message}"
+      err.backtrace&.first(3)&.each { |l| warn "  #{l}" }
+    end
+  end
+end

data/lib/stipa/version.rb

@@ -0,0 +1,3 @@
+module Stipa
+  VERSION = "0.1.0"
+end

data/lib/stipa.rb

@@ -0,0 +1,30 @@
+# lib/stipa.rb — single require entry point
+#
+# Load order follows the dependency graph: leaf modules first,
+# composite modules last. Adding `require 'stipa'` to a user's file
+# loads the entire framework.
+#
+# Dependency order:
+#   version      — no deps
+#   logger       — no deps
+#   thread_pool  — no deps
+#   middleware   — no deps
+#   static       — depends on middleware
+#   template     — no deps (stdlib only: erb, json)
+#   request      — no deps
+#   response     — depends on template (via render helper)
+#   connection   — depends on request, response
+#   server       — depends on thread_pool, connection
+#   app          — depends on server, middleware, template, request, response
+
+require_relative 'stipa/version'
+require_relative 'stipa/logger'
+require_relative 'stipa/thread_pool'
+require_relative 'stipa/middleware'
+require_relative 'stipa/static'
+require_relative 'stipa/template'
+require_relative 'stipa/request'
+require_relative 'stipa/response'
+require_relative 'stipa/connection'
+require_relative 'stipa/server'
+require_relative 'stipa/app'

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: stipa
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Pedro Harbs
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  Stīpa is a lightweight, zero-dependency HTTP/1.1 framework built entirely on Ruby stdlib.
+
+  Features:
+  - Pure stdlib (socket, thread, erb, json, securerandom)
+  - HTTP/1.1 with keep-alive, SO_REUSEPORT, and TCP_NODELAY
+  - Thread pool with bounded queue and graceful shutdown
+  - Pre-compiled middleware stack with zero per-request overhead
+  - ERB templates with layouts, partials, and Vue 3 island helpers
+  - CLI generator for MVC and API-only applications
+  - Structured logging in logfmt format
+  - Named route parameters via regex captures
+email:
+- harbspj@gmail.com
+executables:
+- stipa
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/stipa
+- lib/js/stipa-vue.js
+- lib/stipa.rb
+- lib/stipa/app.rb
+- lib/stipa/cli.rb
+- lib/stipa/connection.rb
+- lib/stipa/generator.rb
+- lib/stipa/generators/api.rb
+- lib/stipa/generators/base.rb
+- lib/stipa/generators/vue.rb
+- lib/stipa/logger.rb
+- lib/stipa/middleware.rb
+- lib/stipa/request.rb
+- lib/stipa/response.rb
+- lib/stipa/server.rb
+- lib/stipa/static.rb
+- lib/stipa/template.rb
+- lib/stipa/thread_pool.rb
+- lib/stipa/version.rb
+- media/favicon.ico
+- media/logo.png
+homepage: https://github.com/pedroharbs/stipa
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/pedroharbs/stipa/issues
+  changelog_uri: https://github.com/pedroharbs/stipa/releases
+  documentation_uri: https://github.com/pedroharbs/stipa
+  homepage_uri: https://github.com/pedroharbs/stipa
+  source_code_uri: https://github.com/pedroharbs/stipa
+  rubygems_mfa_required: 'true'
+post_install_message: "╔══════════════════════════════════════════════════════════════════════════╗\n║
+  \                                                                         ║\n║                 Welcome
+  to Stīpa! \U0001F680                                    ║\n║                                                                          ║\n║
+  \ Minimal, production-ready HTTP framework for Ruby with zero deps.     ║\n║                                                                          ║\n║
+  \ Get started:                                                           ║\n║    $
+  stipa new my_app                                                   ║\n║    $ cd
+  my_app && bundle install && npm install                        ║\n║    $ bundle
+  exec ruby server.rb                                        ║\n║                                                                          ║\n║
+  \ Documentation: https://github.com/pedroharbs/stipa                   ║\n║                                                                          ║\n╚══════════════════════════════════════════════════════════════════════════╝\n"
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Minimal, production-ready HTTP framework for Ruby
+test_files: []