stipa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff378718ea5094cf20614ab1fa80b2ab2fe66b96dbedfc448f230a752034d69d
+  data.tar.gz: db686eb560e89166d73ddf100c6b65695cc288a0f8118e9461edcb0d9b4e8aa8
+SHA512:
+  metadata.gz: bdc3509de75f0de34b898e68ecbd2f3803eaca1959f0c27162c77b2845e8288bf51f0c329be6db0278491a2a5b9c49010952a11bc804fdc79856250b98594c6f
+  data.tar.gz: '072216312185f44a7f236477fd06cfe1a52f2a33fc286ddd6d00f4bfec92f21054345222fa9a5d6b0e2141ffb5f28ff441999e44895debcf42d9d06c04f2cf3c'

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-03-18
+
+### Added
+
+- Initial release of Stīpa framework
+- Zero-dependency HTTP/1.1 server built on Ruby stdlib
+- Thread pool with bounded queue and graceful shutdown
+- Middleware stack with built-in RequestId, Timing, CORS, and Static middleware
+- ERB template engine with layout support and Vue 3 island helpers
+- Vue.js integration for interactive components
+- CLI generator for scaffolding MVC and API-only applications
+- Comprehensive routing with named captures support
+- Keep-alive connections with configurable timeouts
+- Socket optimization (SO_REUSEPORT, TCP_NODELAY)
+
+### Features
+
+- **HTTP/1.1 Protocol**: Full HTTP/1.1 support with keep-alive
+- **Threading**: Configurable thread pool with graceful shutdown
+- **Middleware**: Pre-compiled middleware stack for zero per-request overhead
+- **Templates**: ERB-based views with partials and layouts
+- **Vue.js**: Island architecture for interactive components
+- **CLI**: `stipa new` command for project generation
+- **Production Ready**: Socket tuning, backpressure handling, structured logging

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pedro Harbs
+
+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,305 @@
+<p align="center">
+  <img src="media/logo.png" alt="Stīpa" width="80">
+</p>
+
+<h1 align="center">Stīpa</h1>
+<p align="center">Minimal, production-ready HTTP framework for Ruby — zero dependencies, stdlib only.</p>
+
+---
+
+## Features
+
+- **Zero dependencies** — pure Ruby stdlib (`socket`, `thread`, `erb`, `json`, `securerandom`)
+- **HTTP/1.1** keep-alive, `SO_REUSEPORT`, `TCP_NODELAY`
+- **Thread pool** with bounded queue and graceful shutdown
+- **Middleware stack** compiled once at startup — zero per-request overhead
+- **ERB template engine** with layouts, partials, and Vue 3 island helpers
+- **CLI generator** — `stipa new myapp` scaffolds a full MVC app with Vue + TypeScript
+
+---
+
+## Installation
+
+```bash
+gem install stipa
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem 'stipa'
+```
+
+---
+
+## Quick start
+
+```ruby
+require 'stipa'
+
+app = Stipa::App.new
+
+app.get '/' do |_req, res|
+  res.body = 'Hello, Stīpa!'
+end
+
+app.get '/health' do |_req, res|
+  res.json(status: 'ok', version: Stipa::VERSION)
+end
+
+app.start(port: 3710)
+```
+
+```bash
+ruby server.rb
+# => Stīpa listening on 0.0.0.0:3710
+```
+
+---
+
+## CLI
+
+Generate a new MVC app with Vue 3 + TypeScript:
+
+```bash
+stipa new myapp          # Vue MVC (default)
+stipa new myapp --vue    # same
+stipa new myapp --api    # API-only, no views
+```
+
+Generated structure (`--vue`):
+
+```
+myapp/
+├── server.rb                    # entry point
+├── Gemfile
+├── package.json                 # rollup + vue + typescript
+├── rollup.config.js
+├── tsconfig.json
+├── src/
+│   ├── config/routes.rb
+│   ├── controllers/
+│   ├── models/
+│   ├── views/
+│   └── components/              # Vue SFC source (.vue, .ts)
+└── public/
+    ├── stipa-vue.js
+    ├── app.css
+    └── components/              # Rollup compiled output
+```
+
+```bash
+cd myapp
+bundle install
+npm install
+npm run build                    # compile Vue components
+bundle exec ruby server.rb
+```
+
+---
+
+## Routing
+
+Patterns are either exact strings or regular expressions. First match wins.
+
+```ruby
+app.get    '/posts',                        &handler
+app.post   '/posts',                        &handler
+app.put    %r{/posts/(?<id>\d+)},           &handler
+app.patch  %r{/posts/(?<id>\d+)},           &handler
+app.delete %r{/posts/(?<id>\d+)},           &handler
+```
+
+Named captures are available as `req.params`:
+
+```ruby
+app.get %r{/users/(?<id>\d+)} do |req, res|
+  res.json(id: req.params[:id].to_i)
+end
+```
+
+---
+
+## Request & Response
+
+```ruby
+app.post '/echo' do |req, res|
+  req.method          # => "POST"
+  req.path            # => "/echo"
+  req.query_string    # => "foo=bar"
+  req.body            # => raw body string
+  req['content-type'] # => "application/json" (case-insensitive)
+  req.params          # => { id: "42" } (from named captures)
+
+  res.status = 201
+  res.body   = 'created'
+  res['X-Custom'] = 'value'
+  res.json(ok: true)  # sets body + Content-Type: application/json
+end
+```
+
+---
+
+## Middleware
+
+```ruby
+app.use Stipa::Middleware::RequestId          # mint/propagate X-Request-Id
+app.use Stipa::Middleware::Timing            # append X-Response-Time
+app.use Stipa::Middleware::Cors, origins: ['https://example.com']
+app.use Stipa::Middleware::Static, root: 'public'
+```
+
+Custom middleware:
+
+```ruby
+# Class-based
+class Auth
+  def initialize(app)
+    @app = app
+  end
+
+  def call(req, res)
+    return res.tap { res.status = 401 } unless req['authorization']
+    @app.call(req, res)
+  end
+end
+
+app.use Auth
+
+# Lambda-based
+app.use ->(req, res, next_app) {
+  puts "#{req.method} #{req.path}"
+  next_app.call(req, res)
+}
+```
+
+---
+
+## MVC
+
+### Routes
+
+```ruby
+# config/routes.rb
+class Routes
+  def self.draw(app) = new(app).draw
+
+  def draw
+    get  '/',      to: 'home#index'
+    get  '/posts', to: 'posts#index'
+    post '/posts', to: 'posts#create'
+  end
+
+  # ...
+end
+```
+
+### Controllers
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    render('posts/index', locals: { posts: Post.all })
+  end
+
+  def create
+    post = Post.create(params.slice(:title, :body))
+    redirect_to "/posts/#{post.id}"
+  end
+end
+```
+
+### Views (ERB)
+
+```
+views/
+  layouts/
+    application.html.erb   ← wraps every page
+  posts/
+    index.html.erb
+    show.html.erb
+    _form.html.erb         ← partial (underscore prefix)
+```
+
+```erb
+<%# layouts/application.html.erb %>
+<%= stylesheet_tag '/app.css' %>
+<main><%= content %></main>
+
+<%# posts/index.html.erb %>
+<% posts.each do |post| %>
+  <%= render 'posts/form', locals: { post: post } %>
+<% end %>
+```
+
+---
+
+## Vue 3 Islands
+
+Mount interactive components anywhere inside ERB views — server renders the shell, Vue hydrates on the client.
+
+**Layout:**
+
+```erb
+<%= vue_script %>
+<%= stipa_vue_bootstrap %>
+
+<script src="/components/Counter.js"></script>
+<script>
+  window.StipaVue.register('Counter', window.Counter)
+</script>
+```
+
+**View:**
+
+```erb
+<%= vue_component('Counter', props: { initial: 0 }) %>
+```
+
+**Component** (`src/components/Counter.vue`):
+
+```vue
+<template>
+  <button @click="n++">Clicked {{ n }} times</button>
+</template>
+
+<script lang="ts">
+import { defineComponent, ref } from "vue";
+export default defineComponent({
+  props: { initial: { type: Number, default: 0 } },
+  setup(props) {
+    const n = ref(props.initial);
+    return { n };
+  },
+});
+</script>
+```
+
+Build: `npm run build` → outputs `public/components/Counter.js`.
+
+---
+
+## Server options
+
+```ruby
+app.start(
+  host:              '0.0.0.0',
+  port:              3710,
+  pool_size:         32,       # worker threads
+  queue_depth:       64,       # max queued jobs before backpressure
+  drain_timeout:     30,       # graceful shutdown wait (seconds)
+  keepalive_timeout: 5,
+  max_requests:      100,      # per connection
+  max_body_size:     1_048_576,
+  backpressure:      :drop,    # :drop (503) or :block
+  log_level:         :info,
+)
+```
+
+Handles `SIGTERM` / `SIGINT` with graceful drain.
+
+---
+
+## License
+
+MIT

data/bin/stipa

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'stipa/cli'
+
+Stipa::CLI.run(ARGV)

data/lib/js/stipa-vue.js

@@ -0,0 +1,108 @@
+/**
+ * Stīpa Vue Bootstrapper
+ *
+ * Automatically mounts Vue 3 components declared with the ERB helper:
+ *   <%= vue_component("Counter", props: { initial: 5 }) %>
+ *
+ * Which renders on the page as:
+ *   <div data-vue-component="Counter" data-props='{"initial":5}'></div>
+ *
+ * Usage in your layout (after vue_script and component <script> tags):
+ *   <%= stipa_vue_bootstrap %>
+ *
+ * Register components before DOMContentLoaded fires, or call StipaVue.mount()
+ * manually after dynamic content is inserted.
+ *
+ * Example:
+ *   <script type="module">
+ *     import Counter from '/components/Counter.js'
+ *     StipaVue.register('Counter', Counter)
+ *   </script>
+ *   <%= stipa_vue_bootstrap %>
+ */
+(() => {
+	const COMPONENT_ATTR = "data-vue-component";
+	const PROPS_ATTR = "data-props";
+	const MOUNTED_ATTR = "data-stipa-vue-mounted";
+
+	const registry = {};
+	const mounted = [];
+
+	const StipaVue = {
+		register(name, component) {
+			registry[name] = component;
+		},
+
+		mount(root) {
+			root = root || document;
+
+			if (typeof Vue === "undefined") {
+				console.error(
+					"[StipaVue] Vue is not defined. Make sure vue_script() appears before stipa_vue_bootstrap() in your layout.",
+				);
+				return;
+			}
+
+			// Prune stale entries for elements no longer in the DOM
+			for (let i = mounted.length - 1; i >= 0; i--) {
+				if (!document.contains(mounted[i].el)) {
+					mounted.splice(i, 1);
+				}
+			}
+
+			const selector = "[" + COMPONENT_ATTR + "]:not([" + MOUNTED_ATTR + "])";
+			const elements = root.querySelectorAll(selector);
+
+			elements.forEach((el) => {
+				const name = el.getAttribute(COMPONENT_ATTR);
+				const component = registry[name];
+
+				if (!component) {
+					console.warn(
+						'[StipaVue] Component "' +
+							name +
+							'" is not registered. ' +
+							'Call StipaVue.register("' +
+							name +
+							'", YourComponent) before the DOM loads.',
+					);
+					return;
+				}
+
+				let props = {};
+				const propsRaw = el.getAttribute(PROPS_ATTR);
+				if (propsRaw) {
+					try {
+						props = JSON.parse(propsRaw);
+					} catch (e) {
+						console.error('[StipaVue] Failed to parse props for "' + name + '":', e);
+					}
+				}
+
+				const app = Vue.createApp(component, props);
+				app.mount(el);
+
+				el.setAttribute(MOUNTED_ATTR, "1");
+				mounted.push({ app, el });
+			});
+		},
+
+		unmountAll() {
+			mounted.forEach((entry) => {
+				entry.app.unmount();
+				entry.el.removeAttribute(MOUNTED_ATTR);
+			});
+			mounted.length = 0;
+		},
+	};
+
+	// DOMContentLoaded handles the synchronous registration pattern:
+	// components registered via classic <script> tags before this event fires
+	// will be mounted automatically. For async/module-based registration,
+	// call StipaVue.mount() manually after registering.
+	document.addEventListener("DOMContentLoaded", () => {
+		StipaVue.mount();
+	});
+
+	window.StipaVue = StipaVue;
+})();

data/lib/stipa/app.rb

@@ -0,0 +1,123 @@
+require_relative 'version'
+require_relative 'logger'
+require_relative 'server'
+require_relative 'middleware'
+require_relative 'request'
+require_relative 'response'
+
+module Stipa
+  # User-facing DSL for defining routes and middleware.
+  #
+  # Usage:
+  #
+  #   app = Stipa::App.new
+  #
+  #   app.use Stipa::Middleware::RequestId
+  #   app.use Stipa::Middleware::Timing
+  #   app.use Stipa::Middleware::Cors, origins: ['https://example.com']
+  #
+  #   app.get '/'            { |_req, res| res.body = 'Hello' }
+  #   app.get '/health'      { |_req, res| res.json(status: 'ok') }
+  #   app.post '/echo'       { |req, res|  res.body = req.body }
+  #   app.get %r{/users/(?<id>\d+)} { |req, res| res.json(id: req.params[:id].to_i) }
+  #
+  #   app.start(port: 3710)
+  #
+  # Handler signature:
+  #   Handlers always receive (req, res) — both the Request and the Response.
+  #   Mutate `res` directly: res.body = ..., res.status = ..., res.json(...).
+  #   Return value of the block is ignored; mutating `res` is the contract.
+  #
+  # Route matching:
+  #   - String patterns: exact path match only.
+  #   - Regexp patterns: full match via Regexp#match. Named capture groups
+  #     (e.g., (?<id>\d+)) are placed into req.params as symbol keys.
+  #   - Routes are checked in insertion order; first match wins.
+  #
+  # Middleware:
+  #   - call `use` before `start`. Order matters: first `use`-d runs first.
+  #   - The chain is compiled once at start time; calling `use` afterwards
+  #     has no effect (a warning is logged).
+  class App
+    HTTP_VERBS = %w[get post put patch delete head options].freeze
+
+    # views:  path to the views directory (enables ERB rendering via res.render)
+    # public: path to the public directory (enables static file serving)
+    #         When provided, Static middleware is automatically prepended.
+    def initialize(views: nil, public: nil)
+      @routes          = []
+      @stack           = MiddlewareStack.new
+      @started         = false
+      @logger          = Logger.new
+      @template_engine = views  ? Template.new(views_dir: views)  : nil
+      @public_dir      = public ? File.expand_path(public)        : nil
+    end
+
+    # DSL: register a route for the given HTTP verb.
+    # Pattern can be a String (exact match) or Regexp (with named captures).
+    HTTP_VERBS.each do |verb|
+      define_method(verb) do |pattern, &handler|
+        @routes << [verb.upcase, pattern, handler]
+      end
+    end
+
+    # Add a middleware to the stack. Must be called before start.
+    def use(middleware, **opts)
+      if @started
+        @logger.warn("use() called after start — #{middleware} will be ignored")
+        return self
+      end
+      @stack.use(middleware, **opts)
+      self
+    end
+
+    # Build the middleware chain and start the TCP server. Blocks until shutdown.
+    def start(**opts)
+      @started = true
+      # Prepend Static middleware automatically when a public dir is configured.
+      # It runs before all user-registered middleware so static assets are served
+      # without going through the full middleware stack.
+      if @public_dir
+        @stack.prepend(Middleware::Static, root: @public_dir)
+      end
+      chain = @stack.build(method(:dispatch))
+      Server.new(app: chain, **opts).start
+    end
+
+    private
+
+    # Core router — the innermost callable in the middleware chain.
+    # Matches req.method + req.path against registered routes.
+    # Sets req.params from Regexp named captures and calls the handler.
+    def dispatch(req, res)
+      @routes.each do |method, pattern, handler|
+        next unless method == req.method
+
+        match = case pattern
+                when String
+                  # Exact string match
+                  req.path == pattern ? true : nil
+                when Regexp
+                  # Full Regexp match — named captures become req.params
+                  pattern.match(req.path)
+                end
+
+        next unless match
+
+        # Populate req.params from named captures (for Regexp routes)
+        if match.respond_to?(:named_captures)
+          req.params = match.named_captures.transform_keys(&:to_sym)
+        end
+
+        res.template_engine = @template_engine if @template_engine
+        handler.call(req, res)
+        return res
+      end
+
+      # No route matched
+      res.status = 404
+      res.body   = "Not Found: #{req.method} #{req.path}"
+      res
+    end
+  end
+end

data/lib/stipa/cli.rb

@@ -0,0 +1,39 @@
+require 'fileutils'
+require_relative 'version'
+require_relative 'generator'
+
+module Stipa
+  module CLI
+    USAGE = <<~TEXT
+      Stipa #{Stipa::VERSION} — Minimal Ruby HTTP Framework
+
+      Usage:
+        stipa new <app_name> [--vue|--api]
+
+      Templates:
+        --vue   MVC app with ERB views and Vue 3 components (default)
+        --api   API-only app with JSON controllers, no views
+
+      Examples:
+        stipa new my_project
+        stipa new my_project --vue
+        stipa new my_api  --api
+
+    TEXT
+
+    def self.run(argv)
+      command = argv[0]
+      case command
+      when 'new'
+        name     = argv.reject { |a| a.start_with?('--') }[1]
+        template = argv.find { |a| a.start_with?('--') }&.delete_prefix('--') || Generator::DEFAULT
+
+        abort "Usage: stipa new <app_name> [--vue|--api]" if name.nil? || name.empty?
+
+        Generator.new(name, template: template).generate
+      else
+        print USAGE
+      end
+    end
+  end
+end